Tools stay in your workspace

Files and search

read_file, grep, and glob inspect the workspace. write_file creates or replaces a file; edit_file makes an exact replacement, or an ordered edits batch across files that is checked in full before anything is written. File writes to the same path serialize; unrelated files can proceed concurrently.

Read before write: Existing files normally must be read before write_file will replace them. This guard prevents blind overwrites. edit_file instead fails if its exact old text does not match.

Commands and persistent compute

Tool	What it does
`shell`	Runs a command and captures stdout, stderr, and exit status.
`process`	Starts and controls long-lived background or interactive processes, with optional completion and log-match wakeups.
`pykernel`	Runs persistent Python; values and imports survive calls.
`bun_repl`	Intended to run persistent JavaScript or TypeScript with top-level await; currently broken on recent Bun because the `bun-repl` package refuses piped stdin.

Use pykernel when a task benefits from retained Python state. bun_repl requires a Bun executable on PATH and does not install packages; do not rely on it as a working persistent runtime until the piped-stdin issue is resolved.

Wait for background work without polling

The process tool has two execution styles. For a finite command, waitForExit: true keeps its original tool call open and returns once with the final output. For a server, watcher, or interactive process, leave it detached: the initial spawn result returns its process ID while the child continues running.

# finite job: one tool call returns when the command exits
{"action":"spawn","command":"gh run watch 33854691034","waitForExit":true}

# server: wake once when ready, and again if it later exits
{"action":"spawn","command":"npm run dev","notifyOnMatch":"ready"}

Spawn option	Behavior
`waitForExit`	Wait for a finite process to exit inside the original tool call. Intermediate output is buffered rather than causing repeated model calls.
`notifyOnExit`	For a detached process, wake the interactive agent once when the process exits. Defaults to `true`; set it to `false` when exit needs no follow-up.
`notifyOnMatch`	Wake the interactive agent once when this literal text first appears in new output. Use a stable readiness or important-log marker, not a broad value that appears in routine logs.

The process spawn cap counts live processes and in-flight spawn reservations, not exited entries retained for list. Completed finite jobs therefore do not exhaust the cap over a long session, and parallel spawns share the same limit. Notifications do not create a second tool or fabricate a tool result. Orcacode adds a bounded, explicitly untrusted runtime event to model context and starts one continuation. The synthetic event stays hidden from the transcript; only the model’s response is shown. Output already returned by spawn is not sent again, and output delivered by a match notification is not repeated by the later exit notification.

Poll manually only when needed: Use poll when you explicitly need current logs from an interactive process or a server that has not reached a notification condition. Do not repeatedly poll a finite job merely to discover completion; use waitForExit instead.

Large output

Tool output is capped to protect the context window. When a result is truncated, use read_tool_result with its call ID and offset to retrieve the original output in pages. In the terminal UI, /expand <n> shows the full output of a recent tool call.

Start here

Getting started

Work safely

Configure

Use the agent

Extend

Embed

Automate

Under the hood

Reference

Tools stay in your workspace

Files and search

Commands and persistent compute

Wait for background work without polling

Large output

​Files and search

​Commands and persistent compute

​Wait for background work without polling

​Large output

Files and search

Commands and persistent compute

Wait for background work without polling

Large output