Tools Reference

Every tool available to AFK agents, organized by category. Tool names use underscores. MCP access is discovery-first and on demand: agents inspect a named server with mcp_tools, then invoke one exact discovered tool with mcp_call_tool.

Tool naming rules: Do not invent tool names. The only built-in tools with an mcp_ prefix are exactly mcp_tools, mcp_call_tool, mcp_resources, mcp_resource_templates, and mcp_read_resource. Direct mcp__serverName__toolName names may appear in discovered tool lists or resumed history, but agents should not invent them.

File operations

Tool	Description
`read_file`	Read file contents. Supports `line_start` / `line_end` for partial reads. Aliases: `open_file`, `view_file`.
`write_file`	Create or overwrite a file. Supports `line_start` / `line_end` for range replacement; full overwrite when no range is given.
`edit_file`	Replace an exact string in a file. Errors if the string is not found or matches more than once. Preferred for targeted edits.
`apply_patch`	Apply a unified diff patch via `git apply`. Supports multi-hunk and multi-file patches. Accepts standard unified diffs or `*** Begin Patch` block format. Set `dry_run` to validate without modifying files.
`glob`	Find files by glob pattern. Params: `pattern`, `dir` (optional). Returns paths sorted by modification time. Alias: `find`.
`grep`	Search file contents with regex. Params: `pattern`, `path` (optional), `recursive`, `case_insensitive`. Returns `file:line` matches.
`list_dir`	List directory contents with type indicators.
`workspace_diff`	Return a git diff as raw patch text and structured hunks. Params: `path` (optional), `staged`, `context_lines`. Renders as a split diff in the UI.
`view_image`	Load a local image from the project and attach it to the conversation for visual inspection.
`show_image`	Display a local image to the user as a chat bubble. Params: `path`, `caption` (optional).
`show_artifact`	Render structured UI artifacts in chat. Supported kinds: `chart`, `table`, `mermaid`, `metric`, `json`, `text`, and `dashboard`. Charts use `xKey` plus `yKey`/`yKeys`; dashboards are grid/container artifacts whose items contain non-dashboard child artifacts.
`notebook_read`	Read a Jupyter notebook. Params: `path`, `cell_type` (optional: `code` or `markdown`). Read-only / parallel-safe.
`notebook_edit`	Edit or append a cell in a Jupyter notebook. Params: `path`, `cell_index` (0-based; `-1` to append), `new_source`, `cell_type`.

Shell execution

Tool	Description
`bash`	Blocking shell execution. Working directory persists across calls within a session.
`bash_background`	Start a shell command in the background. Returns a process ID immediately. Params: `command`, `description`.
`bash_output`	Read accumulated stdout/stderr from a background process. Non-blocking. Params: `id`.
`kill_shell`	Stop a background process (SIGTERM → SIGKILL). Params: `id`.

Web

Tool	Description
`web_fetch`	Fetch a URL and return full content as plain text. Use when you have a direct URL and need the whole page.
`web_search`	Search the web (Bing primary, DuckDuckGo fallback). No API key required. Returns titles, URLs, and snippets.
`web_open`	Fetch a page, normalize visible text, extract numbered links, and return a `page_id` for follow-up navigation.
`web_click`	Follow a numbered link from a `web_open` snapshot. Params: `page_id`, `link_id`.
`web_find`	Search within a stored page snapshot for a plain-text pattern. Params: `page_id`, `pattern`.

Parallelism

Tool	Description
`parallel`	Run multiple read-only tool calls concurrently. Params: `calls` (array of `{tool, input}`). Only safe read-only tools are permitted. Results are ordered and include `ok` + `output`.
`parallel_write`	Run multiple independent single-file write operations concurrently. Supports `write_file`, `edit_file`, `notebook_edit`. Rejects overlapping target paths. The batch requires approval in `auto` mode and is blocked during plan mode.

User interaction

Tool	Description
`ask_user`	Ask the user a question. Params: `question`, `options` (optional string array). Blocks until the user responds. Renders as a prompt card in the UI.

Todo list (session checklist)

A lightweight, session-scoped checklist distinct from background task management. Shows a structured plan in the UI as the agent works through it.

Tool	Description
`todo_write`	Replace the entire todo list atomically. Params: `todos` (array of `{id, content, status, priority}`). Status values: `pending`, `in_progress`, `completed`. Keep exactly one item `in_progress`; clear when the task is done.
`todo_read`	Return the current todo list as structured JSON. Read before writing to avoid losing items.

Background task management

Track long-running work: background agents, bash processes, and sub-tasks. Tasks are shared across agents in a session.

Tool	Description
`task_create`	Create a task. Params: `title`, `description` (optional). Returns task record with ID.
`task_update`	Update task fields or mark complete/failed. Params: `id`, `status`, `title`, `description` (all optional).
`task_get`	Get full details for a specific task. Params: `id`.
`task_list`	List all current tasks with status.
`task_stop`	Stop a task and kill its associated agent process. Params: `id`.
`task_output`	Read accumulated agent output for a task. Params: `id`. Returns `{output, status}` where status is `running` or `done`. Non-blocking.

Sub-agents & sessions

Tool	Description
`agent_spawn`	Spawn a sub-agent asynchronously. Returns `agent_id` immediately. Params: `prompt`, `agent_type`, `tools`, `description`, `isolation` (`worktree` or `none`), `lifecycle` (`persistent` or `ephemeral`).
`send_message`	Send a message to a running sub-agent. Params: `to` (agent ID), `message`, and optional `expects_response`. Omit it or set it to `true` for requests that need a reply; set it to `false` for final reports, acknowledgements, status updates, or replies to an earlier request.
`agent_stop`	Stop a running persistent sub-agent. Params: `agent_id`.
`agent_resume`	Resume a stopped persistent sub-agent. Params: `agent_id`, `include_children` (optional).
`session_spawn`	Create a new top-level AFK session. Params: `task`, plus optional `project_path`, `model`, `mode`, `agent_name`, `isolation`, and more.
`session_close`	Request a top-level session to stop. Params: `session_id`, `force` (optional).
`session_resume`	Resume a stopped top-level session. Params: `session_id`, `machine_id` (optional), `include_children` (optional).
`session_archive`	Archive a session so it is hidden from active lists while preserving history. Params: `session_id`.
`session_restore`	Restore an archived session to active lists. Params: `session_id`. Use `session_resume` separately to restart execution.

Session goals

Tool	Description
`get_goal`	Get the active session goal, including status, objective, tokens used, elapsed seconds, turn count, token budget, and continuation limit. Returns `{"status":"none"}` when no goal is active.
`update_goal`	Update the active goal status. Params: `status`, with allowed values `complete` or `blocked`. Use`complete` only after verifying the objective is achieved; use `blocked` only after the same blocker repeats for at least three consecutive turns.

Scheduled tasks (cron)

Tool	Description
`cron_create`	Schedule a recurring prompt. Params: `prompt`, `schedule` (e.g. `30s`, `5m`, `2h`, `1d`), `description` (optional).
`cron_list`	List all active cron jobs in the current session.
`cron_delete`	Cancel and remove a scheduled cron job. Params: `id`.

Plan mode

Tool	Description
`plan_start`	Enter plan mode. Write and execute tools are blocked. Agent explores with read-only tools then calls `plan_finish`.
`plan_finish`	Present the plan as a review card. Params: `plan` (markdown). Approved → tools unblocked. Denied → agent stays in plan mode. Abandoned → plan mode exits.

Git worktrees

Tool	Description
`worktree_enter`	Create a git worktree. Params: `branch` (optional, auto-generated if omitted). Rebuilds ToolRegistry with the worktree dir.
`worktree_exit`	Exit worktree. Params: `action`: `merge`, `discard`, or `pr` (push branch + open PR).

Capability suggestions

AFK can surface contextual setup suggestions as dismissible cards above the composer. Agents use suggest_capability when a reusable skill, MCP integration, or plan-mode workflow would reduce repeated manual work. Suggestions are stored with session history and locally suppressed after dismissal so they do not nag.

Tool	Description
`suggest_capability`	Suggest an AFK capability as a structured UI card. Supported kinds are `skill`, `mcp`, and `plan_mode`. Skill suggestions include a complete draft so the user can create it directly.

Skills

Tool	Description
`skill`	Invoke a skill by name. Params: `skill` (skill name). The skill body is injected into the conversation as a text block.

Context and cost

Tool	Description
`compact`	Summarize conversation history to free context window space. Params: `instructions` (optional). Agent should call this proactively above 70% context usage.
`cost`	Return accumulated token counts and costs per model for this session.
`set_session_name`	Set the session's display name. Params: `name` (empty string clears the explicit name).

LSP tools

Language server integration. Initialize a server once and reuse the server_id for all subsequent calls. Agents access LSP through the daemon's LspManager.

Tool	Description
`lsp_initialize`	Start or attach to an LSP server. Params: `language`, `root_path` (optional). Returns `server_id`.
`lsp_hover`	Type info and docs at a position. Params: `server_id`, `uri` (file URI), `line`, `character` (0-based).
`lsp_definition`	Go to the definition of a symbol.
`lsp_implementation`	Go to the implementation(s) of an interface or abstract method.
`lsp_references`	Find all references to a symbol across the workspace.
`lsp_diagnostics`	Compiler errors and warnings for a file. Run after edits to verify correctness.
`lsp_completion`	Get completion suggestions at a position.
`lsp_rename`	Safe cross-file symbol rename. Params: `server_id`, `uri`, `line`, `character`, `new_name`. Preferred over grep+sed for refactors.
`lsp_code_actions`	Quick fixes and refactoring suggestions at a position or range.
`lsp_document_symbols`	All symbols in a file.
`lsp_workspace_symbols`	Search symbols by name across the entire workspace.
`lsp_call_hierarchy`	Callers and callees of a symbol. Use before modifying a function signature.
`lsp_call`	Send any raw LSP JSON-RPC request not covered by the convenience tools.
`lsp_release`	Release the agent's reference to an LSP server. Server stops when no agents hold references.

MCP tools

Tool	Description
`mcp_tools`	List callable tools exposed by MCP servers, including descriptions and input schemas. Passing an exact `server` name starts that one configured service on demand if needed. Omitting `server` lists already-connected services only and does not start every configured MCP service.
`mcp_call_tool`	Invoke a tool returned by `mcp_tools`. Params: `server`, `tool`, and optional `arguments`. Put the discovered tool's parameters inside `arguments`.
`mcp_resources`	List readable MCP resources. Passing a `server`filter starts that one service on demand; omitting it lists already-connected services only.
`mcp_resource_templates`	List parameterized MCP resource templates.
`mcp_read_resource`	Read a specific MCP resource. Params: `server`, `uri`.
`reload`	Re-read AFK config files and refresh plugins, skills, agents, hooks, MCP servers, prompt layers, and the available tool list without restarting the session.