Run a shell command and wait for it to finish. Returns exit code, stdout and stderr. Full system access via the default shell (or the one you name). Use for anything short-lived.

Start a command in the background and return a job_id immediately. For long builds, dev servers, watchers and tailing logs. Read or stop it later with shell_job.

Inspect and control background jobs. actions: list | status | output | write | kill | wait | remove. output/wait can block up to wait_ms until new output appears, so one call replaces a polling loop; pass the returned next_offset back as offset to stream without re-reading what you already saw.

Run MANY commands in one call, in order — the token-efficient way to work. Each step supports: delay_before_ms/delay_after_ms, when (condition), expect_exit, retry, on_failure, assign (capture output into a variable) and capture (how much output to return). Conditions and ${...} interpolation can read earlier steps: prev.ok, prev.exit, prev.stdout, step..ok, steps[0].exit, vars., failed_count. Prefer capture="on_failure" for long pipelines: silent on success, full output where it broke.

Read a file, or just the part you need: a line range (start_line/end_line, negatives count from the end), head_lines/tail_lines, or match="regex" to return only matching lines with optional context — far cheaper than reading a whole file. Output is line-numbered and middle-truncated at max_output_bytes.

Write a whole file. mode: overwrite (default) | append | prepend | create_new (fails if it exists). Creates parent directories and keeps the file existing EOL style. For a small change to a big file use file_edit.

Patch parts of a file — several edits in ONE call. ops types: replace_lines, delete_lines, insert_before, insert_after, replace_text (exact string), regex_replace, append, prepend. Line numbers in every op refer to the ORIGINAL file and line ranges must not overlap, so you can plan all edits from a single file_read. replace_text fails unless it matches expect_count times (default 1) — pass all=true for every occurrence. Use dry_run=true to preview a diff first.

List a directory (or stat one path). Recurses to "depth", filters with a glob "pattern", and skips .git/node_modules/dist and friends by default.

Report the environment: platform, server cwd, active shell, which shells are installed, effective config and any active guardrails. Call this once at the start if you need to know what you are driving.

Server-side variables that persist between calls, so a value never has to be re-sent through the conversation. Store once, then reference it as ${vars.} in later calls — in a command, cwd, env, a path, a URL, a header, a git message, a bulk step. list shows names, types and sizes but NOT full values (that is the saving). Mark a token secret:true and it stays usable via ${vars.…} while never being echoed back. shell_bulk assign, shell_exec assign and http_request assign all write here.

Grep a whole tree: regex (or literal) across files, returning only matching lines with file:line and optional context. Skips .git/node_modules/build dirs and binaries, honours .gitignore. Use files_only=true to just locate files, count_only=true for tallies. Set replace= to rewrite every match (dry_run=true first shows a diff).

Find files and directories by name glob, size, age or type — the find you would otherwise shell out for, with consistent output on every platform. Sorts by path, size or mtime.

Run git with compact, token-cheap output. Read: status, log, diff, show, blame, branches, tags, remotes, stash_list, file_history, current, root, config_get. Write: add, unstage, commit, checkout, branch_create, branch_delete, merge, rebase, reset, revert, restore, stash, stash_pop, tag_create, fetch, pull, push, apply, clean, init. Anything else: action="raw" with args=["..."]. git runs directly, not through a shell, so commit messages with quotes and newlines need no escaping.

Filesystem operations other than reading/writing content: copy, move, delete, mkdir, touch, stat, chmod, symlink, readlink, hash (md5/sha1/sha256/sha512), disk_usage (recursive size, biggest files), tree (indented listing). Works on files and directories; recursive where it makes sense. delete refuses a non-empty directory unless recursive=true.

Create, list and extract archives: zip, tar, tar.gz (tgz) and plain gzip. Implemented in process, so it behaves the same on Windows, macOS and Linux with no zip/tar binary needed. create takes a directory or a file list (with glob filters); extract refuses paths that escape the destination.

Facts about the machine: overview (default), cpu, memory, disk (free space per mount), network (interfaces), env (environment variables), uptime, user. Read-only.

Processes on this machine: list (filter by name, sort by cpu/memory), tree (parent/child hierarchy), info (one pid in detail), kill (by pid, or every process matching a name — which requires confirm=true). Uses ps on Unix and PowerShell/tasklist on Windows.

Make an HTTP(S) request and report status, timing, headers and body — for testing the API you are building or calling. JSON bodies are pretty-printed; large bodies are truncated. Pass json= for a JSON body (sets Content-Type), or body= for anything else.

Network probes: dns (A/AAAA/MX/TXT/CNAME/NS/PTR lookup), tcp_check (is host:port accepting connections, with timing), listening (which ports are open on this machine, and which pid owns them), interfaces (local addresses), ping.

Drive whichever package manager the project uses, without having to know which: npm, pnpm, yarn, bun, deno, pip, uv, poetry, pipenv, cargo, go, composer, bundler, maven, gradle, dotnet. Actions: detect, install, add, remove, run (a script/task), scripts (list them), list, outdated. Detection reads lockfiles, so it picks the manager the repo actually uses.

Orient yourself in an unfamiliar repository in ONE call: languages by file count and lines, package manager and manifests, dependencies and detected frameworks, available scripts, entry points, test/build/lint commands, git branch and dirty state, and config files. Much cheaper than exploring the tree by hand.

Structural views of source code: outline (functions, classes, types in a file, with line numbers — read this before reading the file), imports (what a file depends on), todos (TODO/FIXME/HACK/XXX across the tree), stats (lines of code by language).

Query and patch JSON without rewriting the whole file: get (read a path), set, delete, merge (deep), keys (list a level), validate, format (pretty-print or minify). Paths look like "scripts.build" or "items[0].name". Works on a file (path=) or inline text (content=).

Compare and patch text: files (unified diff between two files), text (between two inline strings), apply (apply a unified diff to a file — hunk line numbers are matched by context, so a patch still applies after unrelated edits shifted the file).

Small conversions: base64/hex/url/html encode and decode, hash (md5/sha1/sha256/sha512), uuid, random bytes, jwt_decode (header and payload — signature is NOT verified), timestamp (epoch <-> ISO). Reads inline text or a file.

Watch a file or directory for changes. start returns a watch_id; poll blocks up to wait_ms for new events and returns them (so one call replaces a polling loop); list shows active watchers; stop ends one. Events are coalesced per path, so a save that fires three times is reported once.