Built-in tools

• Read files and select lines.
• Find paths and search contents.
• Edit existing files or write files.
• Run shell commands or stop background shells.

codemode

{ "defaultTools": ["+codemode"] }

const files = await Promise.all([
  tools.read({ path: "README.md" }),
  tools.read({ path: "package.json" }),
]);
return files.map((text) => text.slice(0, 1000));

// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}
return await tools.read({ path: "README.md" });

tool_search

code_search

code_search({ repoName: "facebook/react", query: "How does useEffect cleanup work?" })

edit

{
  "path": "src/example.ts",
  "edits": [
    { "oldText": "const value = 1;", "newText": "const value = 2;" },
    { "oldText": "console.log(value);", "newText": "console.info(value);" }
  ]
}

• Every oldText must match exactly one region of the file as it is when the edit runs, including whitespace and newlines. Overlapping occurrences count: }\n} occurs twice in }\n}\n}. Edits are matched against the original file, not one after another, and must not overlap. Merge changes to the same or nearby lines into one edit.
• edit does not depend on an earlier read. A file changed by bash, another tool, or another program is edited by its current text.
• When no exact match exists, edit retries after normalizing trailing whitespace, Unicode quotes, dashes, spaces, and compatibility forms such as full-width characters. The normalization only finds the region; newText replaces the file’s original text there, and everything outside that region, including the rest of its lines, stays byte-for-byte unchanged. A single exact match is always used, even when the normalized text would match more than once.
• edit only edits UTF-8 text. A file that is not valid UTF-8, such as a Latin-1 file, is refused with target-not-utf8 and left unchanged.
• A UTF-8 byte-order mark is kept, and every line outside the replaced text keeps its own line ending (LF, CRLF, or a lone CR). Line breaks in newText take the line ending of the line where the replaced text starts; a file that uses only lone CR line endings gets CR.
• Either every edit applies or the file is left unchanged.
• In the built-in tool, a notebook (.ipynb) is edited through the same # %% [code] cell:N text that read shows; cell metadata, outputs, and execution counts are kept.

write

Edit and write errors

bash

• cwd and env set the working directory and environment for local execution.
• timeout is in seconds and defaults to 300. Explicit values must be finite, greater than zero, and no more than 3600. Invalid values fail before execution. Fractional seconds are honoured to the nearest millisecond, with a one-millisecond minimum. The timeout keeps counting after a command continues in the background: the launch result names it, and a later wait on a command it stopped returns an error naming the timeout. See Background shells.
• pty: true uses the bundled native PTY session, falling back to pipes if unavailable. Set PI_NO_PTY=1 or ATOMIC_NO_PTY=1 to force pipes.
• heartbeatMs sets how often a command that keeps running as a background task sends a task heartbeat. Omit it for the chat’s default (15 minutes unless tasks.heartbeatMs changes it), use 0 to turn heartbeats off, or give at least 60000.

kill

find and search

Finding paths

• Hidden files are included by default, and .gitignore rules are respected, including nested rules outside a Git checkout.
• Broad scans prune .git and node_modules even with gitignore: false. To search node_modules, name it explicitly in the path or glob.
• Results are capped at 200 by default; the default timeout is 5 seconds.

Searching contents

• Omitted, empty-string, or empty-array paths search the workspace root.
• Quoted and delimiter-separated paths follow the same rules as find.
• Whitespace-only patterns are rejected. Other patterns are preserved verbatim, including (?i), (?m), and (?x) flags for resource-backed selectors.
• Output is paged by matching files, 20 by default. Multi-file searches show up to 20 matches per file; single-file searches allow 200 matches.
• skip pages files and is ignored for single-file searches. At the internal collection ceiling, refine the pattern or path as the output requests.
• Context defaults to one line before and three after each match, controlled by search.contextBefore and search.contextAfter. Line selectors scope matches first; context outside the range does not count as a hit.

read and path selectors

Lines and local resources

• Local zip/jar/tar/tgz/gzip archive members without a Python dependency. Member names may include raw, conflicts, 1, L1, or raw:notes.txt.
• SQLite table and row selectors, with limit, offset, where, order, schema, and sampleRows query parameters.
• skill:// (read and search only; edit a skill file by its path) and source-backed local:// selectors. Search output and write results name the underlying filesystem path.
• artifact://<id> for saved tool output (read-only), and conflict:// for merge conflicts under the working directory.
• history:// for the current project’s past sessions and workflow runs (read-only), through whichever session store and workflow journal are configured. See Recalling earlier work.

SQLite limits and writes

• Table reads show the schema and a 5-row sample by default. Query reads default to 20 rows, capped at 500.
• Raw ?q= queries accept only single-statement SELECT and stream at most 1000 rows. They reject sqlite_% internals, pragma_* table-valued functions, and dangerous keywords such as ATTACH.
• Table lists cap at 500, excluding sqlite_% tables. Row counts probe at most 50,001 rows.
• Table writes accept {} as INSERT DEFAULT VALUES. Row writes parse non-empty JSON5-style objects (unquoted keys, single-quoted strings, comments, trailing commas, + and hex numbers; text inside strings is kept as written) and validate column names and scalar values before binding.
• Empty SQLite row writes delete only when a row ID is present.
• A row selector names one row by its primary key, as in data.sqlite:users:42. Tables without a primary key use rowid. For a composite primary key, give every key value as a JSON array in key order, such as data.sqlite:members:["acme",2]; a partial key is refused. A row update or delete that would change more than one row is refused and changes nothing. A row id is never read as a line range, so data.sqlite:events:2024-01-05 names that row. A key column declared without a type matches a numeric id such as 42 by its number.

Conflict resolution and file writes

Documents and URLs

• Local text reads show up to 3,000 lines or 50 KiB.
• Unselected URL reads show the first 300 rendered lines, capped at 50 KiB. Large rendered bodies are truncated rather than blocked solely for their size; full-output and truncation metadata are retained when available.
• Search match and context lines are capped at 512 characters, followed by a truncation notice.
• Oversized resource/document reads return guidance and structured details identifying the block reason.

ask_user_question

{
  "questions": [{
    "header": "Merge approval",
    "question": "Remove the stack grouping, then admin-merge the same seven PRs in dependency order without changing repository protections?",
    "options": [
      { "label": "Proceed", "description": "Remove the grouping and admin-merge those seven PRs in dependency order. Leave repository protections unchanged." },
      { "label": "Do not proceed", "description": "Leave the grouping and PRs unchanged." }
    ]
  }]
}

Persisted tool output

<tmpdir>/atomic-<uid>/<session-id>/