Tools Reference

This page lists every tool available to the agent, grouped by category. Each entry shows the tool name, a one-line description, and a table of its parameters.

Required parameters are marked with ✓. All others are optional.

File System

`read_file`

Read a file from the filesystem with line numbers. Supports partial reads via offset/limit. Binary files are rejected — use extract_document instead.

Parameter	Type	Required	Description
`file_path`	string	✓	Absolute path to the file to read.
`offset`	number		Line number to start reading from (1-based). Defaults to 1.
`limit`	number		Maximum number of lines to read. Defaults to 2000.

`write_file`

Write content to a file, creating it or overwriting if it exists. Parent directories are created automatically. Prefer edit_file for modifying existing files.

Parameter	Type	Required	Description
`file_path`	string	✓	Absolute path to the file to write.
`content`	string	✓	The full content to write.

`edit_file`

Perform an exact string replacement in a file. Fails if old_string is not found or matches multiple locations (unless replace_all is set). Always read the file first to verify exact content.

Parameter	Type	Required	Description
`file_path`	string	✓	Absolute path to the file to edit.
`old_string`	string	✓	The exact string to find and replace.
`new_string`	string	✓	The replacement string.
`replace_all`	boolean		If true, replace all occurrences. Default: fail on multiple matches.

Validate and atomically apply structured multi-file changes with content-hash verification and dry-run preview. Validation runs on all files before any write; a single failure aborts the entire patch.

Parameter	Type	Required	Description
`changes`	array	✓	Array of file changes. Each item: `path` (required), `edits` (sequential replacements) or `content` (full replacement), optional `expected_hash`.
`dry_run`	boolean		If true, return the unified diff without writing.

`glob`

Find files matching a glob pattern. Returns up to 500 matching paths. Skips node_modules, .git, .hg, .svn by default.

Parameter	Type	Required	Description
`pattern`	string	✓	Glob pattern (e.g. `"src/*/.ts"`, `"*.json"`).
`path`	string		Base directory to search from. Defaults to cwd.

`grep`

Search file contents for lines matching a pattern using ripgrep. Returns matches as file:line:content. Honors .gitignore; skips .git and binary files.

Parameter	Type	Required	Description
`pattern`	string	✓	Ripgrep regex. `\|` `+` `?` `(` `)` `{` `}` are metacharacters — escape with `\` for literal match.
`path`	string		Directory or file to search. Defaults to cwd.
`include`	string		File glob to restrict search (e.g. `"*.ts"`).

`list_directory`

List the contents of a directory. Returns filenames annotated with type (directories end with /).

Parameter	Type	Required	Description
`path`	string	✓	Absolute path to the directory to list.

`extract_document`

Extract text from binary document formats that read_file rejects. Supports .docx, .xlsx, .pptx, .pdf (requires pdftotext), and .zip. Output is capped at 512 KB.

Parameter	Type	Required	Description
`file_path`	string	✓	Absolute path to the document file.

`json_query`

Run a bounded jq-subset query on a JSON file without loading it fully into context. Returns { result, type, truncated, source_size }.

Supported syntax: . .field .field.nested .[N] .[N:M] .[] .[] | .field keys length

Parameter	Type	Required	Description
`path`	string	✓	Absolute or relative path to the JSON file.
`query`	string	✓	Query expression (e.g. `.name`, `.[0]`, `.[]
`max_results`	number		Max array elements to return (default 100).
`max_bytes`	number		Max serialized output size in bytes (default 51200).

Shell & Process

`bash`

Execute a shell command and return stdout and stderr. Commands run through /bin/sh — not bash. Output is capped to ~100 KB head+tail; commands emitting >8 MB are terminated.

Parameter	Type	Required	Description
`command`	string	✓	The shell command to execute.
`timeout_ms`	number		Timeout in milliseconds (default 120000, max 600000).

`wait_for`

Block on an external condition without consuming model turns. Returns when the condition is met, the timeout elapses (status: timed_out), or the session is cancelled.

Parameter	Type	Required	Description
`type`	string	✓	What to wait for: `url`, `file`, `process`, or `command`.
`url`	string		(`url` type) HTTP/HTTPS endpoint to poll.
`method`	string		(`url` type) HTTP method: `HEAD` or `GET`. Default: `HEAD`.
`expected_status`	number		(`url` type) Expected HTTP status code. Default: any 2xx.
`body_contains`	string		(`url` type) Substring that must appear in the response body.
`path`	string		(`file` type) Path to watch for existence.
`content_contains`	string		(`file` type) Substring the file content must contain.
`pid`	number		(`process` type) PID to wait on. Met when the process exits.
`command`	string		(`command` type) Shell command to run. Met when it exits 0.
`timeout_ms`	number		Max wait time in ms (default 120000, max 600000).
`poll_interval_ms`	number		Delay between polls in ms (default 5000, min 1000).
`backoff`	string		Backoff strategy: `none`, `linear`, or `exponential`.

`test_run`

Discover and run the project test suite. Auto-detects the test runner from project config files. Returns structured results with pass/fail counts, per-failure details, duration, and raw output.

Parameter	Type	Description
`file`	string	Narrow to a specific test file path (relative to project root).
`name`	string	Filter tests by name/pattern (runner-specific syntax applied automatically).
`timeout_ms`	number	Test timeout in ms (default 120000, max 600000).
`coverage`	boolean	Request a coverage report.

Browser

Browser tools share a single managed session per AFK process. Always start a workflow with browser_open; subsequent calls operate on the same tab.

`browser_open`

Open a URL in a managed browser tab and return an observation of the page. The observation lists actionable elements with stable IDs for follow-up browser_act calls.

Parameter	Type	Required	Description
`url`	string	✓	Absolute http(s) URL to navigate to.
`wait_for`	string		When navigation is complete: `load`, `domcontentloaded`, or `networkidle`. Default: `load`.
`screenshot`	boolean		Capture a screenshot in the observation. Default: false.
`timeout_ms`	number		Navigation timeout in ms. Default 30000, max 120000.

`browser_observe`

Refresh the observation of the current page. Use after DOM mutations or dynamic content loads. Element IDs are stable only within one observation — always use IDs from the most recent call.

Parameter	Type	Description
`screenshot`	boolean	Capture a screenshot. Default: false.
`include_hidden`	boolean	Include hidden elements. Default: false.
`max_elements`	number	Cap on the interactive elements array (default 80, max 300).

`browser_act`

Perform an action on a target element on the current page. Prefer semantic targets ({ kind: "semantic", text: "...", role: "button" }) over selectors for stability across markup changes.

Parameter	Type	Required	Description
`action`	string	✓	`click`, `fill`, `press`, `select`, `hover`, `scroll_to`, or `wait_for`.
`target`	object	✓	Element target. Required field: `kind` (`semantic`, `element_id`, or `selector`).
`value`	string		Text for `fill`, key combo for `press`, option value for `select`.
`timeout_ms`	number		Per-action timeout in ms. Default 10000.
`screenshot`	boolean		Capture a screenshot after the action. Default: false.

`browser_screenshot`

Capture a PNG screenshot of the current page or a specific element and return it as a viewable image. Also written as a sidecar under ~/.afk/state/witness/.

Parameter	Type	Required	Description
`target`	object		Element to screenshot (same shape as `browser_act.target`). Omit to capture the viewport.
`full_page`	boolean		Capture the entire scrollable page. Default: false. Mutually exclusive with `target`.

`browser_close`

Close the current browser session, freeing cookies and page state. Subsequent browser_open calls create a fresh session. Leaves the underlying browser process alive.

No parameters.

Web

`web_scrape`

Scrape a web page or run a web search. Three modes: markdown (default — fetches and extracts main content), raw (response body as text), search (web search via Exa; requires EXA_API_KEY). Output is capped at max_bytes.

Parameter	Type	Description
`mode`	string	`markdown`, `raw`, or `search`. Default: `markdown`.
`url`	string	Absolute http(s) URL. Required for `markdown` and `raw` modes.
`query`	string	Search query. Required for `search` mode.
`timeout_ms`	number	Request timeout in ms (default 30000, max 120000).
`max_bytes`	number	Max UTF-8 bytes returned (default 100000, max 1000000).

`web_request`

Make a structured HTTP request with any method. Returns { status, headers, body, timing_ms }. SSRF-guarded: private IP ranges are blocked. Credential injection via env var name keeps secrets out of the model context.

Parameter	Type	Required	Description
`url`	string	✓	Absolute http(s) URL.
`method`	string	✓	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS`.
`body`	any		Request body. Objects/arrays are JSON-serialized; strings sent as text/plain.
`headers`	object		Request headers as a string-keyed object.
`timeout_ms`	number		Request timeout in ms (default 30000, max 120000).
`max_response_bytes`	number		Max response body bytes (default 100000, max 1000000).
`credential`	string		Env var name whose value is injected as a Bearer token.

Delegation

`agent`

Dispatch an independent subagent with its own context window and tool access. Foreground mode (default) waits for the result; background mode returns a jobId immediately.

Parameter	Type	Required	Description
`prompt`	string	✓	The task for the subagent to perform.
`mode`	string		`foreground` (default) or `background`.
`model`	string		Model override. Short aliases: `haiku`, `sonnet`, `opus`. Append `_1m` for 1M-context variants.
`max_turns`	number		Max conversation turns (default 0 = unlimited).
`max_tool_use_iterations`	number		Max tool-use rounds before graceful wind-down (default 0 = unlimited).
`cwd`	string		Absolute path for the subagent to run in (e.g. a worktree).
`isolation`	string		`none` (default) or `worktree` — creates an isolated git worktree for the subagent.
`writeRoots`	array		Extra absolute write roots to pre-grant the child.
`readRoots`	array		Extra absolute read roots to pre-grant the child.
`attachments`	array		Image IDs or absolute image paths to pass as input.
`progress_events`	boolean		Grant the child the `emit_progress` tool for live parent updates.
`id_prefix`	string		Label prefix for log correlation.

`compose`

Execute multiple subagent tasks as a DAG. Nodes without dependencies run in parallel; nodes with edges wait for their upstream dependencies. Maximum 20 nodes per call.

Parameter	Type	Required	Description
`nodes`	array	✓	Subagent tasks. Each item: `id` (string), `prompt` (string), optional `model`.
`edges`	array		Dependencies between nodes. Each item: `from` (node id), `to` (node id).
`fail_fast`	boolean		Cancel downstream nodes on first failure. Default: true.
`node_timeout_ms`	number		Per-node max runtime in ms. Disabled when omitted.
`max_tool_rounds_per_node`	number		Per-node tool-use round budget. Triggers graceful wind-down when reached.

`skill`

Invoke a registered skill by name. A skill either forks an isolated subagent or loads its instructions into the current context — the mode is fixed per-skill.

Parameter	Type	Required	Description
`name`	string	✓	Skill name (e.g. `"mint"`, `"diagnose"`).
`arguments`	string		Arguments to pass to the skill.

`cancel_background_job`

Cancel a running background subagent job that the model created with agent in mode="background". Refuses to cancel user-backgrounded jobs (those are user-owned).

Parameter	Type	Required	Description
`jobId`	string	✓	Background job ID returned by an earlier `agent` call.
`reason`	string	✓	Why the job is now obsolete or should stop (recorded in the trace).

`send_message_to_agent`

Deliver a steering message to a running background subagent at its next tool-call boundary. Injects the message as a user turn so the child can adjust mid-execution.

Parameter	Type	Required	Description
`jobId`	string	✓	Background job ID returned by an earlier `agent` call.
`message`	string	✓	Steering text to inject into the child at its next tool-call boundary.

Workspace

The workspace is a session-scoped shared scratchpad for sibling agents running in a compose DAG. Entries published by one node are visible to all other nodes in the same session.

`workspace_publish`

Publish a structured finding to the shared session workspace. Entries are visible to siblings immediately via workspace_query and injected into new siblings' system prompts at fork time.

Parameter	Type	Required	Description
`type`	string	✓	Entry type: `finding`, `evidence`, `hypothesis`, `decision`, `artifact`, or `status`.
`content`	string	✓	The full text of the finding, evidence, or decision.
`subject`	string		Short label for relevance routing (e.g. `"auth refresh"`).
`evidence`	array		File:line references backing this entry (e.g. `["src/auth.ts:141"]`).
`confidence`	number		Confidence level 0–1 (default 1.0).
`relates_to`	array		IDs of related workspace entries.
`relation_type`	string		Relationship to `relates_to` entries: `supports`, `contradicts`, `depends_on`, or `supersedes`.

`workspace_query`

Query the shared session workspace for findings published by sibling agents. Returns entries matching the search keywords, ordered by recency.

Parameter	Type	Required	Description
`query`	string	✓	Keywords to match against entry subjects and content.
`type`	string		Filter results to a specific entry type.
`limit`	number		Max entries to return (default 20, max 50).

Memory

Cross-session memory persists facts and procedures across all sessions. Hot memory is injected into the system prompt; facts are stored in a searchable SQLite archive.

`memory_search`

Search cross-session memory for facts and procedures. Returns results ranked by relevance. Supports FTS5 syntax: AND, OR, NOT, "exact phrase", prefix*.

Parameter	Type	Required	Description
`query`	string	✓	Search query (FTS5 syntax).
`category`	string		Filter by category: `preference`, `convention`, `decision`, or `learning`.
`since`	string		ISO date — only return facts created after this date.
`limit`	number		Max results (default 10).

`memory_update`

Store a fact in cross-session memory or update hot memory. Hot memory (target: "hot") persists in the system prompt for all future sessions. Facts (target: "fact") go into the searchable archive.

Parameter	Type	Required	Description
`target`	string	✓	`hot` (HOT.md / system prompt) or `fact` (searchable archive).
`action`	string	✓	`set` (create/overwrite), `supersede` (replace with history), or `remove` (delete).
`content`	string		Content to store (required for `set`/`supersede`).
`category`	string		Fact category: `preference`, `convention`, `decision`, or `learning`. Required for `fact` target.
`evidence`	string		Provenance citation (file:line, commit SHA). Unlocks verified recall for `convention` facts.
`supersedes`	number		Fact ID being replaced (required for `supersede` action).
`id`	number		Fact ID to delete (required for `remove` action).

`procedure_write`

Write a reusable procedure to memory as a markdown file. Procedures persist across sessions and are searchable via memory_search.

Parameter	Type	Required	Description
`name`	string	✓	Procedure name in kebab-case (becomes the filename).
`content`	string	✓	Procedure content (markdown).

State Store

A namespaced JSON document store that persists across all surfaces and sessions. Backed by a WAL-mode SQLite file at ~/.afk/state/kv/kv.db. Documents have a version counter for optimistic concurrency and optional TTL.

`state_get`

Retrieve a document from the durable state store. Returns null if the document does not exist or has expired.

Parameter	Type	Required	Description
`namespace`	string	✓	Document namespace. Pattern: `[A-Za-z0-9_.-]+`, max 128 chars.
`key`	string	✓	Document key. Same pattern/limit as namespace.

`state_put`

Write or update a document. Creates on first write (version starts at 1) and increments the version on updates.

Parameter	Type	Required	Description
`namespace`	string	✓	Document namespace.
`key`	string	✓	Document key.
`value`	any	✓	JSON-serializable value to store.
`ttl_ms`	number		Time-to-live in milliseconds. Document is deleted after this duration.
`metadata`	any		Optional metadata object (not returned by `state_get` — for audit/tagging).

`state_cas`

Compare-and-swap write. Updates the document only when its current version matches expected_version. Returns { matched: false } on version mismatch.

Parameter	Type	Required	Description
`namespace`	string	✓	Document namespace.
`key`	string	✓	Document key.
`expected_version`	number	✓	Version the document must currently have for the update to succeed.
`value`	any	✓	New value to store if the CAS matches.
`ttl_ms`	number		Optional TTL in milliseconds from the write time.
`metadata`	any		Optional metadata object.

`state_delete`

Delete a document. Returns { deleted: true } if it existed, { deleted: false } if it did not.

Parameter	Type	Required	Description
`namespace`	string	✓	Document namespace.
`key`	string	✓	Document key.

`state_query`

List documents in a namespace sorted by key. Supports key prefix filtering and pagination. Expired documents are excluded.

Parameter	Type	Required	Description
`namespace`	string	✓	Document namespace.
`key_prefix`	string		Only return documents whose key starts with this string.
`limit`	number		Max results (default 20, max 100).

Configuration

`config_get`

Read AFK configuration from ~/.afk/config/. Secret values (API keys, tokens) are always masked.

Parameter	Type	Required	Description
`target`	string	✓	`config` (afk.config.json) or `env` (afk.env).
`key`	string		Dotted config path or env var name. Omit to list all values for the target.
`all`	boolean		(`env` only) When true, list every known env var, not just those currently set.

`config_set`

Edit AFK configuration. Changes persist for future sessions only — the current session is unchanged. Credentials and human-gated keys are refused (use afk config CLI instead).

Parameter	Type	Required	Description
`target`	string	✓	`config` (afk.config.json) or `env` (afk.env).
`key`	string	✓	Dotted config path (e.g. `"model"`) or env var name (e.g. `"AFK_EFFORT"`).
`action`	string		`set` (default — writes `value`) or `unset` (removes the key).
`value`	any		Required for `set`. String, number, boolean, or array where the schema expects one.

`terminal_font_size`

Get or set the terminal font size in VS Code and Cursor settings. Writes are atomic. Aborts on JSONC settings files to avoid corrupting comments.

Parameter	Type	Required	Description
`action`	string	✓	`get` (read current size) or `set` (write new size).
`size`	number		Font size to set (range 6–60). Required when `action` is `set`.
`editor`	string		Restrict to a specific editor: `cursor`, `vscode`, or `vscodeinsiders`.

Scheduling

`create_schedule`

Create a new scheduled task saved to ~/.afk/config/schedules.json and live-synced to the running daemon.

Parameter	Type	Required	Description
`name`	string	✓	Human-readable label (e.g. `"Nightly cleanup"`).
`command`	string	✓	Command to run (e.g. `"/my-skill --auto"`).
`cron`	string	✓	5-field cron expression (e.g. `"0 2 * * *"`).
`trigger`	string		`cron` (default), `sessionstart`, or `both`.
`notifyOn`	string		When to push Telegram notifications: `failure` (default), `always`, or `never`.
`notifyChat`	string/number		Route notifications to a specific chat (id or alias).
`enabled`	boolean		Whether to activate immediately. Default: true.

`list_schedules`

List all scheduled tasks with their IDs, cron expressions, enabled status, and notify settings. Returns a JSON array of task configs.

No parameters.

`get_schedule_history`

Retrieve recent execution history for a scheduled task. Returns records in chronological order (oldest first).

Parameter	Type	Required	Description
`taskId`	string	✓	The task ID (slug) to look up.
`limit`	number		Max records to return (default 10, max 50).

`cancel_schedule`

Disable, re-enable, or permanently remove a scheduled task. Default (no flags) sets enabled: false.

Parameter	Type	Required	Description
`taskId`	string	✓	The task ID (slug) to operate on.
`enable`	boolean		If true, re-enable a disabled task and register it with the daemon.
`permanent`	boolean		If true, remove from the store entirely (takes precedence over `enable`).

Git

`worktree`

Manage AFK-managed git worktrees under <repoRoot>/.afk-worktrees/. Prefer this over raw git worktree bash commands — it writes the .afk-worktree-meta.json the background sweep engine needs.

Parameter	Type	Required	Description
`action`	string	✓	`create`, `keep`, `release`, `list`, or `remove`.
`name`	string		(`create`) Worktree slug (kebab-case). Becomes `.afk-worktrees/<name>` and branch `afk/<name>`.
`base`	string		(`create`) Git ref to base the new branch on. Default: HEAD.
`path`	string		(`keep`/`release`/`remove`) Worktree slug or repo-relative path.
`reason`	string		(`keep`) Why this worktree must survive (stored as the git lock reason).
`force`	boolean		(`remove`) Also remove when dirty or with commits ahead of base. Branch ref is always preserved.

Communication

`ask_question`

Ask the operator a question and wait for their answer. This is a last resort — exhaust tools before calling it. On non-interactive surfaces the call returns { action: "decline" } immediately.

Parameter	Type	Required	Description
`question`	string	✓	The question to ask.
`type`	string		`text` (default), `confirm`, `choice`, `multi_choice`, or `number`.
`choices`	array		Options list. Required for `choice` and `multi_choice` types.
`context`	string		Background context to display above the question.
`default`	string/boolean/number		Default value shown as a hint.
`allow_skip`	boolean		Whether the user may skip (submit empty). Default: false.
`allow_custom`	boolean		(`choice`/`multi_choice`) Let the operator type a free-form answer.
`min_length`	number		(`text`) Minimum character length.
`max_length`	number		(`text`) Maximum character length.
`min`	number		(`number`) Minimum value (inclusive).
`max`	number		(`number`) Maximum value (inclusive).

`send_telegram`

Send a Telegram message to the operator. Use for terminal-state notifications when the user is away. Plain text only, 4096-character limit. Returns an error when Telegram is not configured.

Parameter	Type	Required	Description
`message`	string	✓	Plain-text message body. Max 4096 characters.
`chat`	string/number		Target a specific chat: numeric chat id or alias name from `telegram.chatAliases`.
`thread_id`	number		Topic thread ID for supergroups with topics enabled. Requires `chat`.

Session

`get_runtime_state`

Inspect what the runtime knows about the current session: identity, tool affordances, delegation state, and git workspace state. Read-only; does not probe the filesystem or network.

Parameter	Type	Required	Description
`view`	string		`self`, `tools`, `subagents`, `workspace`, or `all` (default). Use a narrower view to keep the response compact.

`get_facet`

Read the structured session facet — a validated, consumer-facing summary of what a session did. Includes tool call counts, error categories, subagent invocations, outcome, summary, and cost breakdown.

Parameter	Type	Required	Description
`session`	string		Session ID, name, or `"latest"` (default).
`fields`	array		Allowlist of top-level fields to include. Omit to return all non-provenance fields.

`read_witness`

Read and filter events from a session's witness trace — the durable record of everything the agent did. Returns structured trace events in chronological order.

Parameter	Type	Description
`session`	string	Session ID or `"latest"` (default).
`kinds`	array	Filter by event kind(s): `tool_call`, `subagent_lifecycle`, `session_phase`, `closure`, `abort`, `budget`, `hook_decision`, `browser_event`, `claim`, `compaction`, `background_agent`, `queued_user_message`, `session_sealed`.
`tool_name`	string	Filter `tool_call` events to one tool name.
`errors_only`	boolean	When true, show only error events. Default: false.
`limit`	number	Max events to return (default 50, max 200).

`search_witness`

Search across multiple sessions' witness traces for a text pattern. Returns matching trace events grouped by session. Does not contain full conversation text or tool arguments.

Parameter	Type	Required	Description
`query`	string	✓	Text pattern to search for (case-insensitive substring).
`sessions`	number		Number of recent sessions to scan (default 20, max 100).
`kinds`	array		Filter results to specific event kinds.
`since`	string		ISO date — only search sessions modified after this date.
`tool_name`	string		Filter `tool_call` events to one tool name.

`clipboard_read`

Read the current clipboard contents as text. Requires explicit operator confirmation on every call — the clipboard may contain sensitive data. Returned text is run through the secret-redaction pipeline.

No parameters.

`clipboard_write`

Write a string to the system clipboard. Uses pbcopy on macOS, clip on Windows, wl-copy/xclip/xsel on Linux, with an OSC 52 fallback for SSH sessions.

Parameter	Type	Required	Description
`text`	string	✓	The text to copy to the clipboard.

`emit_progress`

Push a structured progress update from a child subagent to the parent session. Only available on subagents dispatched with progress_events: true. Events are delivered to the parent's next user turn as a <child-progress> XML envelope.

Parameter	Type	Required	Description
`message`	string	✓	Free-text description of current status. Capped at 2048 bytes.
`phase`	string		Short label for the current stage (e.g. `"scanning"`, `"testing"`).
`metadata`	object		Arbitrary key/value object for structured data.

Tools Reference

On this page