> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools stay in your workspace

> The default toolset gives an agent useful local capabilities while rejecting absolute paths and attempts to escape upward from the workspace root.

## 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.

<Note>
  **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.
</Note>

## 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.

```bash theme={"dark"}
# 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.

<Note>
  **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.
</Note>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.