aitools

A command-line tool for AI agents with built-in file and text operations and an external-program runner. Use the built-ins instead of cat, grep, sed, find, jq, or tar, or invoke installed programs through aitools run. Every call prints one JSON object. File reads support bounded windows and continuation; journaled writes are guarded by the expected text, hash, or count, support crash recovery and guarded undo; known secret formats are masked in JSON output; and every error names an aitools command to run next. It has no features for people (no color, prompts, or completion). Written in Common Lisp for SBCL.

Quick Start

# After `nix build` in the Install section below:
export PATH="$PWD/result/bin:$PATH"
aitools schema                                 # every command with a summary
aitools read src/app.lisp --range 1:40         # lines 1-40, with the file hash
aitools search 'defun build-' src              # grouped matches with context
aitools run -- awk 'END { print NR }' README.md # an external program, JSON result
aitools sys metrics --limit 10                # CPU, memory, and busiest processes

For guarded edits and undo, follow the write workflow using text that exists in the target file. history lists journaled writes; pass a returned operation ID to undo.

run passes arguments directly to the program. It does not interpret shell syntax. For a pipeline, invoke a shell explicitly:

aitools run -- sh -c 'grep "aitools" README.md | sort -u'

External programs keep their normal filesystem and network access. Their writes are not guarded or journaled by aitools and cannot be reverted with aitools undo. --root is not a sandbox. Inspect exit_code, signal, and timed_out in the result: a child failure or timeout does not make run fail. It returns exit code 0, or 3 when --grep results exceed --grep-limit. Other output trimming still returns 0. --stdout-to writes unmodified stdout to a new file without secret masking.

Success goes to standard output with exit code 0, or 3 for a partial result. Errors go to standard error with exit code 1, or 2 when the file was not in the state the call assumed:

$ aitools cat README.md
{"schema_version":1,"status":"error","command":"cat","error":{"code":"argument.invalid","message":"unknown command cat","exit_code":1,"repairs":[{"action":"run-instead","detail":"Read a file with line numbers and range control.","command":"aitools read"}]}}

Install

From a checkout:

nix build              # -> ./result/bin/aitools
./result/bin/aitools --version

flake.nix declares x86_64-linux and aarch64-darwin. CI requires both platforms: the Linux Nix test suite and the Darwin delivery checks plus the full host test suite. See development for the commands. The package's bin/ also holds cl-process-kit-spawn, the helper bg start uses to detach a process; aitools looks for it next to its own executable, so copy both together.

Documentation

• Getting started
• Using aitools from an agent: the call loop, guards, transactions, and the shell-command table
• State inspection: host and workspace observations, with coverage limits
• Migrating session commands: native candidates and external execution boundaries
• Commands
• JSON output
• Errors and exit codes
• Transactions
• Architecture
• Benchmarks

The documentation is the specification of aitools's behavior.

For AI agents

skills/aitools/SKILL.md is an agent skill that tells an AI agent how to use aitools. A contract test checks it against the real CLI. Load it into an agent that supports skills, or give it to the agent as instructions.

Development

nix develop                        # SBCL with the dependencies on CL_SOURCE_REGISTRY
sbcl --script run-tests.lisp       # the test suite
nix run .#test                     # full suite on the host against Nix-built delivery; no skips/todos
nix flake check                    # syntax, formatting, docs; Linux also runs the full suite
nix fmt                            # format Nix sources

Outside nix develop, set CL_SOURCE_REGISTRY to checkouts of the dependencies flake.nix pins before running sbcl --script run-tests.lisp. Use nix flake check path:. to include files git does not track yet. On Darwin, both nix flake check and nix run .#test are required.

Tests live in t/ and run under cl-weave. See Development for the layout, how to add a command, and how to regenerate the reference pages.

Contributing

Open a GitHub issue for a bug report or feature proposal. Changes must pass the platform's required development gates and include tests for behavior changes.

License

MIT. See LICENSE.