Tools Reference

Read a file from disk, returning line-numbered content. Optionally bounded by start_line/end_line. Includes diagnostic headers when configured.

Write content to a file, creating it if needed. Uses atomic writes (temp file + rename) for crash safety. Validates against security policy and runs diagnostics pre-flight.

Performs exact string replacement: old_str must match the file content exactly, once. The call fails if old_str is not unique unless replace_all is set. Runs diagnostics pre-flight to reject edits that introduce errors.

Apply several exact string replacements to one file in a single call. Edits are applied sequentially, so later edits see earlier ones' output. One call replaces a noisy sequence of edit_file calls.

Edit Jupyter notebook (.ipynb) cells in place: replace a cell's source, insert a new cell, or delete one. Cells are addressed by cell id or zero-based index. Preserves notebook metadata and outputs.

Fast file pattern matching using glob patterns. Supports *, **, ?, and {a,b} alternatives. Skips node_modules, vendor, .git, __pycache__, .venv, venv automatically.

Search file contents using regular expressions. Supports full regex syntax, file pattern filtering, and returns file paths with line numbers and matching lines.

List files and directories at a given path. Directories are suffixed with /. Simple and fast for exploring project structure.

Write a deliverable document (plan, review, design, summary, report) as a Markdown artifact file. Includes metadata the review UI needs and can request user feedback before continuing.

Execute shell commands with sync or async support. Sync mode auto-backgrounds after 8s for long commands. Async mode returns a shell_id for read_shell/write_shell interaction. Supports detach for processes that survive session shutdown.

Read output from an async shell session. Returns stdout and stderr since last read. Shows completion status and exit code if finished. Large outputs are preserved to file.

Send input to a running async shell session. Supports text and special keys: {enter}, {up}, {down}, {left}, {right}, {backspace}, {tab}, {escape}.

Terminate a running async shell session. First cancels the context for graceful shutdown, then force-kills if still running. Cleans up session state.

List shell sessions and background history. Shows status, duration, and truncated command for each session.

Fetch the content of a web URL with strong SSRF protections. Validates DNS resolution, blocks private/local addresses, enforces content-type allowlists, and follows redirects with validation.

Search the web via DuckDuckGo HTML. Returns parsed results with titles and links. Useful for finding documentation, solutions, or references.

Scan files for hardcoded secrets, API keys, and credentials. Detects AWS, GitHub, GitLab, Google, Slack tokens, private keys, JWTs, Stripe, Twilio, SendGrid keys, database URLs, and generic API keys. Secrets are masked in output.

Audit dependencies for known vulnerabilities. Auto-detects package manager (go, npm, pip, cargo) and runs the appropriate tool (govulncheck, npm audit, pip-audit, cargo audit). Paths are sanitized in output.

Get compiler diagnostics for a Go file (package build errors) or lint findings for Python (via ruff). Reports real compiler output rather than unrelated test results. Includes recovery guidance for common errors.

Launch a specialized sub-agent for a task. Agent types include general-purpose, explore, review, code-review, contexter, coordinator, and task. Supports sync (blocking) and background (async) modes. Each sub-agent works independently with its own context.

Launch multiple sub-agents in parallel with a single call. Each agent runs independently on its own task. More efficient than calling task multiple times for independent work. Maximum 8 parallel tasks.

Get results from a background agent. Use wait=true to block until completion. Supports since_turn to get only new turns in multi-turn agents.

List all agents with their status, type, and duration. Optionally include completed/failed agents.

Inspect your own context window state: token budget usage, the live conversation estimate, and what is consuming the window. Read-only; costs almost nothing.

Switch to plan mode: read-only analysis and planning; edits are refused. Use at the start of a non-trivial task that warrants a reviewed plan.

Present your plan for user approval and wait for their decision. Blocks until the user responds. On approval, plan mode ends and you may implement. On rejection, revise the plan and call again.

Verify that the executed plan's file changes are present. Reads the plan artifact, extracts file paths, and checks each against git's working-tree changes. Reports per-file evidence and an overall verdict.

Ask the user one or more questions with optional multiple-choice options and get their answers. Supports structured questionnaires, timeout, and retry on empty responses. Blocks until user responds.

Show a notification message to the user. Supports info, warning, and error levels. Rate-limited to prevent spam (default: 10 per minute).

List available skills with their descriptions. Skills are reusable, project-specific playbooks (SKILL.md files) covering how this repo does things. Optionally filter by query.

Load a skill's instructions by name. Returns the full skill body; follow it inline for the rest of the task. Skills are re-read on every call for hot-reload support.

Execute SQL queries against the session SQLite database. Pre-built tables: todos, todo_deps, session_state. Supports SELECT, INSERT, UPDATE, DELETE. Includes SQL injection detection as defense-in-depth.

List resources exposed by connected MCP servers. Resources are addressable data (files, schemas, records) that servers publish. Returns URI, server name, and description.

Read one MCP resource by URI. Returns the resource's text content. Resources can be large; prefer narrow URIs when available.

Report a policy violation (hacking, illegal acts, harmful code, credential theft, security bypass). Triggers escalation: warn (1st) → block_imminent (2nd) → blocked (3rd). User can override with valid justification.

Block the current session due to persistent policy violations. Use after violation_detected returns 'blocked' action.

Override a violation detection with user justification (e.g., authorized security research, educational purpose). Resets violation count.