read
Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.
| parameter | type | what it is |
|---|---|---|
path * | string | Path to the file to read (relative or absolute) |
offset | number | Line number to start reading from (1-indexed) |
limit | number | Maximum number of lines to read |
bash
Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last 2000 lines or 50KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.
| parameter | type | what it is |
|---|---|---|
command * | string | Shell command to execute |
timeout | number | Timeout in seconds (optional, no default timeout) |
edit
Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.
| parameter | type | what it is |
|---|---|---|
path * | string | Path to the file to edit (relative or absolute) |
edits * | array | One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead. |
write
Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.
| parameter | type | what it is |
|---|---|---|
path * | string | Path to the file to write (relative or absolute) |
content * | string | Content to write to the file |
subagent
Spawn a sub-[local account redacted] in a dedicated terminal herdr pane. For Pi-backed OpenAI or OpenAI-Codex subagents, set fast: true to opt into service_tier: "priority" (fast mode). Omit fast or set it to false to force the standard service_tier: "default". This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. When the sub-[local account redacted] finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT call subagents_list or any other tool to 'check' status. All of that is wasted work — the harness handles delivery for you. DO NOT fabricate, assume, or summarize results after calling this tool. After spawning, either end your turn immediately, or work on other independent tasks (including spawning more subagents in parallel). The harness will wake you with the result when it is ready.
| parameter | type | what it is |
|---|---|---|
name * | string | Display name for the subagent |
task * | string | Task/prompt for the sub-[local account redacted] |
[local account redacted] | string | [local account redacted] name to load defaults from the available named subagent catalog. [local account redacted] frontmatter can provide model, thinking, tools, skills, and role instructions. |
systemPrompt | string | Appended to system prompt (role instructions) |
model | string | Exact authenticated provider/model-id. Omit to use a named [local account redacted]'s model default, then the configured or parent model. Passing a value explicitly overrides [local account redacted] frontmatter for this spawn. |
fast | boolean | Opt into OpenAI priority processing for this Pi-backed subagent. Set true for service_tier: "priority". Omit or set false to force the standard service_tier: "default". Ignored by non-Pi or non-OpenAI runtimes. |
thinking | Pi thinking level. Omit to use a named [local account redacted]'s thinking default, then the parent level. Passing a value explicitly overrides [local account redacted] frontmatter for this spawn. | |
skills | string | Comma-separated skills (overrides [local account redacted] default) |
tools | string | Comma-separated tools (overrides [local account redacted] default) |
cwd | string | Working directory for the sub-[local account redacted]. The [local account redacted] starts in this folder and picks up its local .pi/ config, CLAUDE.md, skills, and extensions. Use for role-specific subfolders. |
fork | boolean | Force the full-context fork mode for this spawn. The sub-[local account redacted] inherits the current session conversation, overriding any [local account redacted] frontmatter session-mode. |
interactive | boolean | Mark the subagent as interactive (long-running, user drives the conversation in its own pane). When true, the main session is not woken by status transitions (stalled/recovered) for this subagent. If omitted, falls back to the [local account redacted]'s `interactive` frontmatter, otherwise the inverse of `auto-exit` (agents that auto-exit are autonomous and get stall pings; agents that don't are interactive and stay quiet). |
resumeSessionId | string | Resume a previous Claude Code session by its ID. Loads the conversation history and continues where it left off. The session ID is returned in details of every claude tool call. Use this to retry cancelled runs or ask follow-up questions. |
subagent_interrupt
Send Escape to the active turn of a currently running Pi-backed subagent. The child pane, session, watcher, and running entry remain alive; this returns only a local acknowledgement and does not emit a subagent_result solely because of this request.
| parameter | type | what it is |
|---|---|---|
id | string | Exact running subagent id |
name | string | Exact running subagent display name |
subagents_list
List all available subagent definitions. Scans project-local .pi/agents/ and global [local path redacted] Project-local agents override global ones with the same name.
subagent_resume
Resume a previous sub-[local account redacted] session in a new herdr pane. For Pi-backed OpenAI or OpenAI-Codex subagents, set fast: true to opt into service_tier: "priority" (fast mode). Omit fast or set it to false to force the standard service_tier: "default". This is a fire-and-forget async tool: the call returns immediately with only an acknowledgement. When the resumed sub-[local account redacted] finishes, the harness AUTOMATICALLY delivers its result as a steer message that wakes you up and starts a new turn — you do not need to do anything to receive it. DO NOT write polling loops, sleep/wait commands, tail/watch scripts, or repeatedly read session/log files to detect completion. DO NOT poll for status. All of that is wasted work — the harness handles delivery for you. DO NOT fabricate or assume results. After resuming, either end your turn or work on other independent tasks; the harness will wake you when the result is ready. Use when a sub-[local account redacted] was cancelled or needs follow-up work.
| parameter | type | what it is |
|---|---|---|
sessionPath * | string | Path to the session .jsonl file to resume |
name | string | Display name for the terminal tab. Default: 'Resume' |
message | string | Optional message to send after resuming (e.g. follow-up instructions) |
autoExit | boolean | Whether the resumed session should automatically exit after completing its response. Defaults to true for autonomous follow-up work; set false for interactive resumed sessions. |
fast | boolean | Opt into OpenAI priority processing for this resumed Pi session. Set true for service_tier: "priority". Omit or set false to force the standard service_tier: "default". |
caller_ping
Send a help request to the parent [local account redacted] and exit this session. The parent will be notified with your message and can resume this session with a response. Use when you're stuck, need clarification, or need the parent to take action.
| parameter | type | what it is |
|---|---|---|
message * | string | What you need help with |
subagent_done
Call this tool when you have completed your task. It will close this session and return your results to the main session. Your LAST assistant message before calling this becomes the summary returned to the caller.
todo
Manage a task list for tracking multi-step progress. Actions: create (new task), update (change status/fields/dependencies), list (all tasks, optionally filtered by status), get (single task details), delete (tombstone), clear (reset all). Status: pending → in_progress → completed, plus deleted tombstone. Use this to plan and track multi-step work like research, design, and implementation.
| parameter | type | what it is |
|---|---|---|
action * | string | |
subject | string | Task subject line (required for create) |
description | string | Long-form task description |
activeForm | string | Present-continuous spinner label shown while status is in_progress (e.g. 'writing tests') |
status | string | Set this task's status (update): one of pending, in_progress, completed, deleted. When action is list, filters returned tasks by this status. |
blockedBy | array | Initial blockedBy ids (create only) |
addBlockedBy | array | Task ids to add to blockedBy (update only, additive merge) |
removeBlockedBy | array | Task ids to remove from blockedBy (update only, additive merge) |
owner | string | [local account redacted]/owner assigned to this task |
metadata | object | Arbitrary metadata; pass null value for a key to delete that key on update |
id | number | Task id (required for update, get, delete) |
includeDeleted | boolean | If true, list action returns deleted (tombstoned) tasks as well. Default: false. |
web_search
Search the web using the current supported provider (Google Gemini, OpenAI, or Anthropic). Optionally include URLs to analyze alongside search results.
| parameter | type | what it is |
|---|---|---|
query * | string | The search query or question to answer |
urls | array | Additional URLs to analyze along with search (up to 20) |
bg_start
Start a task asynchronously only when background execution is genuinely needed: for concurrent work, later interaction, or an explicit user request. Its unique name can immediately reference ordered follow-up bg_* calls in the same assistant response.
| parameter | type | what it is |
|---|---|---|
name * | string | A short unique name for the task (case-insensitive among retained tasks) |
command * | string | The shell command to run |
cwd | string | Working directory (defaults to current) |
pty | boolean | Run in a pseudoterminal for interactive/TUI programs (default: false) |
cols | number | Initial PTY columns (default: current terminal or 120) |
rows | number | Initial PTY rows (default: current terminal or 30) |
bg_wait
Wait for a finite task to finish or time out and include its latest pipe log line when available. Use bg_logs for full pipe output or PTY terminal output.
| parameter | type | what it is |
|---|---|---|
id * | string | Task ID or unique name (case-insensitive) |
timeout | number | Maximum seconds to wait (default: 300) |
bg_status
Inspect task status and metadata or list current tasks, including each task's latest pipe log line when available. This is not a polling or waiting tool and does not return full or PTY output.
| parameter | type | what it is |
|---|---|---|
id | string | Task ID or unique name. If omitted, lists all retained tasks. |
bg_logs
Read retained pipe or PTY output when the latest pipe line returned by bg_wait or bg_status is insufficient. Place bg_logs after bg_wait in the same response when fuller final output is needed.
| parameter | type | what it is |
|---|---|---|
id * | string | Task ID or unique name (case-insensitive) |
tail | number | Read last N lines (default: 100) |
stream | string | Which stream (default: 'both'); use terminal for explicit PTY output |
from_line | number | Start from this line (0-indexed). Overrides tail. |
max_lines | number | Max lines with from_line (default: 500) |
bg_send
Send text and terminal keys to a running task, or signal a running/disconnected adapter-owned task.
| parameter | type | what it is |
|---|---|---|
id * | string | Task ID or unique name (case-insensitive) |
input | string | Exact text; terminal keys must use <...> tokens, for example y<Enter>, <A-f>, or <C-d> |
signal | string | Named signal validated against the task's local or adapter execution environment |
bg_kill
Terminate a running or disconnected background task and report the result. Sends SIGTERM by default or SIGKILL with force=true; does not return process output.
| parameter | type | what it is |
|---|---|---|
id * | string | Task ID or unique name (case-insensitive) |
force | boolean | Send SIGKILL instead of SIGTERM (default: false) |
* required