{
"status": {
"type": "object",
"properties": {},
"additionalProperties": false,
"description": "Show AFT status, index health, cache usage, and runtime details"
},
"bash": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"command": {
"description": "Shell command to execute. Supports pipes, redirection, and normal shell syntax.",
"type": "string"
},
"timeout": {
"description": "Hard kill cap in milliseconds (positive integer). When omitted, the task can run up to 30 minutes. Foreground bash returns inline if the command finishes within ~8s (configurable via bash.foreground_wait_window_ms); otherwise it's automatically promoted to background and a completion reminder is delivered when the task actually finishes.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"workdir": {
"description": "Working directory for command execution. Relative paths resolve through the bridge; defaults to the current tool context/project root when omitted.",
"type": "string"
},
"description": {
"description": "Short 5-10 word human-readable summary shown in OpenCode UI metadata instead of raw shell syntax.",
"type": "string"
},
"wait": {
"description": "When true, run in the foreground without auto-promoting and wait until the command finishes or reaches its timeout. Use only when you know the result is required before doing anything else.",
"type": "boolean"
},
"background": {
"description": "When true, spawn the command in the background and return a taskId for bash_status/bash_kill instead of waiting for completion. Defaults to false.",
"type": "boolean"
},
"compressed": {
"description": "When true or omitted, return compressed output with noisy terminal control sequences reduced. Set to false for raw output.",
"type": "boolean"
},
"pty": {
"description": "When true, spawn the command in a real PTY for interactive programs (python/node/bash REPLs, vim). Implies background: true automatically. Unavailable in subagent sessions. Inspect with bash_status({ taskId, outputMode: \"screen\" }) and drive interactively with bash_write — its input accepts either a string OR an array like [ \"iHello\", { key: \"esc\" }, \":wq\", { key: \"enter\" } ] for atomic text+key sequences.",
"type": "boolean"
},
"ptyRows": {
"description": "PTY terminal height in rows — ignored when pty is false. Defaults to 24 when pty: true. Minimum 1, maximum 60.",
"type": "integer",
"minimum": 1,
"maximum": 60
},
"ptyCols": {
"description": "PTY terminal width in columns — ignored when pty is false. Defaults to 80 when pty: true. Minimum 1, maximum 140.",
"type": "integer",
"minimum": 1,
"maximum": 140
},
"foreground_orchestrate": {
"type": "boolean",
"description": "Consumer-set flag enabling server-side foreground orchestration."
},
"block_to_completion": {
"type": "boolean",
"description": "Consumer-set flag forcing foreground bash to wait until terminal instead of promoting."
}
},
"required": [
"command"
],
"description": "Execute shell commands. Output is compressed by default; pass compressed: false for raw output. Piped commands run verbatim and show the pipeline's output; for AFT's test/build summary, run the runner without | head, | tail, or | grep. Commands run in the foreground and return inline; wait: true blocks until a long command finishes instead of auto-promoting — use it when you need the result before doing anything else; keep it off otherwise so auto-promote can remind you while you work. Use background: true yourself ONLY when you have other useful work to do while it runs; then bash_watch waits on the task (sync blocks until exit/pattern, async notifies) and bash_status peeks at it — never background a command and immediately bash_watch it (that wastes a turn for what foreground returns in one), and never loop bash_status to wait. pty: true runs interactive programs (REPLs, TUIs), implies background, and is driven with bash_status({ outputMode: \"screen\" }) plus bash_write.\n\nDO NOT use bash for code search or code exploration. If you are about to run grep, rg, sed, awk, find, or cat through bash to locate or read code: STOP — use the grep tool, read, aft_outline, or aft_zoom instead."
},
"read": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"filePath": {
"description": "Path to file or directory (absolute or relative to project root)",
"type": "string"
},
"startLine": {
"description": "1-based line to start reading from",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"endLine": {
"description": "1-based line to stop reading at (inclusive)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"limit": {
"description": "Max lines to return (default: 2000)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"offset": {
"description": "1-based line number to start reading from (use with limit). Ignored if startLine is provided",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"filePath"
],
"description": "Read file contents or list directory entries.\n\nUse either startLine/endLine OR offset/limit to read a section of a file.\n\nBehavior:\n- Returns line-numbered content (e.g., \"1: const x = 1\")\n- Lines longer than 2000 characters are truncated\n- Output capped at 50KB\n- Binary files are auto-detected and return a size-only message\n- Supported images (PNG, JPEG, GIF, WebP) and PDFs are returned as tool attachments; range arguments are ignored for media\n- Directories return sorted entries with trailing / for subdirectories\n\nExamples:\n Read full file: { \"filePath\": \"src/app.ts\" }\n Read lines 50-100: { \"filePath\": \"src/app.ts\", \"startLine\": 50, \"endLine\": 100 }\n Read 30 lines from line 200: { \"filePath\": \"src/app.ts\", \"offset\": 200, \"limit\": 30 }\n List directory: { \"filePath\": \"src/\" }\n"
},
"write": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"filePath": {
"description": "Path to the file to write (absolute or relative to project root)",
"type": "string"
},
"content": {
"description": "The full content to write to the file",
"type": "string"
}
},
"required": [
"filePath",
"content"
],
"description": "Write content to a file, creating it and parent directories automatically. Existing files are backed up before overwriting (undo via aft_safety). Auto-formats when the project has a formatter configured. Use it to create files or replace whole contents; for partial edits, use the `edit` tool."
},
"edit": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"filePath": {
"description": "Path to the file to edit (absolute or relative to project root)",
"type": "string"
},
"oldString": {
"description": "Text to find (exact match, with fuzzy fallback)",
"type": "string"
},
"newString": {
"description": "Text to replace with (omit or set to empty string to delete the matched text)",
"type": "string"
},
"replaceAll": {
"description": "Replace all occurrences",
"type": "boolean"
},
"occurrence": {
"description": "0-indexed occurrence to replace when multiple matches exist",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"symbol": {
"description": "Named symbol to replace (function, class, type)",
"type": "string"
},
"content": {
"description": "Replacement content for symbol mode. For whole-file writes, use the `write` tool.",
"type": "string"
},
"appendContent": {
"description": "Text to append to the end of filePath; creates the file if needed",
"type": "string"
},
"edits": {
"description": "Batch edits — array of { oldString: string, newString: string } or { startLine: number (1-based), endLine: number (1-based, inclusive), content: string }",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"description": "Edit a file by finding and replacing text, or by targeting named symbols. To write or overwrite a whole file, use the `write` tool — `edit` requires an explicit edit mode and will not silently overwrite a file from `content` alone.\n\n**Modes** (determined by which parameters you provide):\n\nMode priority: appendContent > edits > symbol (without oldString) > oldString (find/replace). If none match, the call is rejected — there is no implicit \"write\" fallback. To edit multiple files, make parallel `edit` calls in one response.\n\n1. **Append** — pass `filePath` + `appendContent`\n Appends text to the end of a file, creating the file if it does not exist.\n Example: `{ \"filePath\": \"notes.txt\", \"appendContent\": \"new line\\n\" }`\n\n2. **Batch edits** — pass `filePath` + `edits` array\n Multiple edits in one file atomically. Each edit is either:\n - `{ \"oldString\": \"old\", \"newString\": \"new\" }` — find/replace\n - `{ \"startLine\": 5, \"endLine\": 7, \"content\": \"new lines\" }` — replace line range (1-based, both inclusive)\n Set content to empty string to delete lines.\n\n3. **Symbol replace** — pass `filePath` + `symbol` + `content`\n Replaces an entire named symbol (function, class, type) with new content.\n Includes decorators, attributes, and doc comments in the replacement range.\n **Important:** You must NOT provide `oldString` when using symbol mode — if present, the tool silently falls back to find/replace mode.\n Example: `{ \"filePath\": \"src/app.ts\", \"symbol\": \"handleRequest\", \"content\": \"function handleRequest() { ... }\" }`\n\n4. **Find and replace** — pass `filePath` + `oldString` + `newString`\n Finds the exact text in `oldString` and replaces it with `newString`.\n Supports fuzzy matching (handles whitespace differences automatically).\n If multiple matches exist, specify which one with `occurrence` or use `replaceAll: true`.\n Example: `{ \"filePath\": \"src/app.ts\", \"oldString\": \"const x = 1\", \"newString\": \"const x = 2\" }`\n\n5. **Replace all occurrences** — add `replaceAll: true`\n Replaces every occurrence of `oldString` in the file.\n Example: `{ \"filePath\": \"src/app.ts\", \"oldString\": \"oldName\", \"newString\": \"newName\", \"replaceAll\": true }`\n\n6. **Select specific occurrence** — add `occurrence: N` (0-indexed)\n When multiple matches exist, select the Nth one (0 = first, 1 = second, etc.).\n Example: `{ \"filePath\": \"src/app.ts\", \"oldString\": \"TODO\", \"newString\": \"DONE\", \"occurrence\": 0 }`\n\nNote: Modes 5 and 6 are options on mode 4 (find/replace) — they require `oldString`.\n\n**Behavior:**\n- Backs up files before editing (recoverable via aft_safety undo)\n- Auto-formats using project formatter if configured\n- Tree-sitter syntax validation on all edits\n- Symbol replace includes decorators, attributes, and doc comments in range\n- Response is a compact server-rendered summary; before/after diff details are attached as UI metadata when available."
},
"apply_patch": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"patchText": {
"description": "The full patch text including Begin/End markers",
"type": "string"
}
},
"required": [
"patchText"
],
"description": "Use the `apply_patch` tool to edit files. Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:\n\n*** Begin Patch\n[ one or more file sections ]\n*** End Patch\n\nWithin that envelope, you get a sequence of file operations.\nYou MUST include a header to specify the action you are taking.\nEach operation starts with one of three headers:\n\n*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).\n*** Delete File: <path> - remove an existing file. Nothing follows.\n*** Update File: <path> - patch an existing file in place (optionally with a rename).\n*** Move to: <path> - after update file header, renames the file.\n\n\nExample patch:\n\n```\n*** Begin Patch\n*** Add File: hello.txt\n+Hello world\n*** Update File: src/app.py\n*** Move to: src/main.py\n@@ def greet():\n-print(\"Hi\")\n+print(\"Hello, world!\")\n*** Delete File: obsolete.txt\n*** End Patch\n```\n\n**Behavior:**\n- Per-file commit: each file's edits apply independently. If a later file fails, earlier successful changes are kept. Use `aft_safety` undo if you need to revert the applied changes.\n- Files are backed up before modification\n- Parent directories are created automatically for new files\n- Fuzzy matching for context anchors (handles whitespace and Unicode differences)\n\n**It is important to remember:**\n\n- You must include a header with your intended action (Add/Delete/Update)\n- You must prefix new lines with `+` even when creating a new file\n\nEdits return as soon as the write completes unless `lsp.diagnostics_on_edit` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits."
},
"grep": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"include": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"pattern"
],
"description": "Search file contents using regular expressions. Returns matching lines with file paths and line numbers (no surrounding context lines — use `read` for that). Always case-sensitive. Capped at 100 matches; if you hit the cap, narrow with `path` or `include` and re-run."
},
"glob": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"pattern"
],
"description": "Find files matching a glob pattern. Returns matching file paths sorted by modification time."
},
"search": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"query": {
"description": "Concept, regex, literal text, filename, or capability to find. Examples: 'fuzzy match with whitespace tolerance', '^export', 'Cargo.lock'.",
"type": "string"
},
"topK": {
"description": "Number of results (default: 10, max: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"hint": {
"description": "Optional routing hint. Defaults to 'auto'.",
"type": "string",
"enum": [
"regex",
"literal",
"semantic",
"auto"
]
},
"includeTests": {
"description": "Include test files (*.test.*, *_test.rs, __tests__/, …) plus test-support, fixture, mock, snapshot, and corpus files. Defaults to false.",
"type": "boolean"
},
"path": {
"description": "Search a different project root (absolute or ~ path). Requires that project to have been indexed by AFT.",
"type": "string"
}
},
"required": [
"query"
],
"description": "Search code with one tool: concepts, identifiers, error strings, regex, literals, and filenames are auto-routed to the right engine and returned ranked. For conceptual 'how does X work' queries, phrase a full natural-language sentence — the semantic lane is NL-aware and matches intent against docstrings and comments ('how does the ORM build and execute a query', 'where is rate limiting handled'), not just keywords. Exact names, strings, and regex stay terse ('^export', 'Cargo.lock').\n\nSet hint to 'regex', 'literal', or 'semantic' to force a lane."
},
"outline": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"target": {
"description": "What to outline: a file path, directory path, URL, or array of paths. The mode is auto-detected: URLs by `http://`/`https://` prefix, directories by stat, arrays as multi-file.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"files": {
"description": "Directory-only mode: when true, target must be a directory or array of directories and the result is a flat file tree with path, language, symbol count, and byte size instead of a symbol outline.",
"type": "boolean"
},
"includeTests": {
"description": "Directory outline only: include test files. Defaults to false; tests are hidden.",
"type": "boolean"
}
},
"required": [
"target"
],
"description": "Structural outline of source code, documentation files, or remote URLs. For code, returns symbols (functions, classes, types) with line ranges. For Markdown and HTML, returns heading hierarchy. Use this to explore structure before reading specific sections with aft_zoom. Set `files: true` with a directory target for a flat indexed file tree with language, symbol count, and byte metadata.\n\nFor understanding a specific feature, prefer aft_search + aft_zoom on named symbols; use aft_outline on a whole directory only for high-level structure mapping. aft_zoom with `callgraph:true` gives one-level forward calls-out; use aft_callgraph only for reverse callers or multi-level traces.\n\nPass a single `target`:\n • file path → outline that file (with signatures)\n • directory path → outline all source files under it (recursively, up to 200 files)\n • URL (http:// or https://) → fetch and outline a remote HTML/Markdown document\n • array of paths → outline multiple files in one call; with files:true, every path must be a directory"
},
"zoom": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"filePath": {
"description": "Path to file (absolute or relative to project root)",
"type": "string"
},
"url": {
"description": "HTTP/HTTPS URL of an HTML or Markdown document to fetch and zoom into",
"type": "string"
},
"symbols": {
"description": "Symbol name for code, or heading text for Markdown/HTML. Pass a string for one lookup or an array for batched lookups in the same file/URL.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"targets": {
"description": "Cross-file batch: `{ filePath, symbol }` or an array of them. Mutually exclusive with filePath/url/symbols.",
"anyOf": [
{
"type": "object",
"properties": {
"filePath": {
"description": "Path to file (absolute or relative to project root)",
"type": "string"
},
"symbol": {
"description": "Symbol name in that file",
"type": "string"
}
},
"required": [
"filePath",
"symbol"
]
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"filePath": {
"description": "Path to file (absolute or relative to project root)",
"type": "string"
},
"symbol": {
"description": "Symbol name in that file",
"type": "string"
}
},
"required": [
"filePath",
"symbol"
]
}
}
]
},
"contextLines": {
"description": "Lines of context before/after the symbol (default: 3)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"callgraph": {
"description": "Include call-graph annotations (calls-out / called-by within the same file). Default false; off keeps zoom output minimal.",
"type": "boolean"
}
},
"description": "Inspect code symbols or documentation sections. For code, returns the full source of a symbol. Pass `callgraph: true` to also include call-graph annotations (calls-out / called-by within the same file). For Markdown and HTML, returns the section content under the given heading.\n\nUse exactly ONE mode: `{ filePath, symbols }`, `{ url, symbols }`, or `{ targets }`. `symbols` can be a string or array (one or many lookups in the same file/URL). Use `targets` for cross-file batches: `{ filePath, symbol }` or an array of them."
},
"inspect": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"sections": {
"description": "Categories to include in detailed drill-down (e.g. 'todos' or ['todos', 'dead_code', 'cycles']). Use 'all' for every active category. Omit for summary-only mode.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"scope": {
"description": "Restrict scan/results to paths under this scope (file or directory, absolute or relative to project root). Tier 1 scopes the scan; Tier 2 scans project-wide and applies scope as a result filter.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"topK": {
"description": "Max drill-down items per category. Default 20, max 100.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"description": "Codebase health snapshot. One call returns summary stats for: TODOs, diagnostics, file/symbol metrics, dead code, unused exports, code duplicates, and TS/JS import cycles. Pass `sections` for per-category drill-down details.\n\nCategories run in tiers — Tier 1 (todos, metrics) return synchronously from cache. Tier 2 (dead_code, unused_exports, duplicates, cycles) waits for a fresh reuse scan up to a short deadline; if a category is still scanning the response reports `complete: false` with `pending_categories: [...]` rather than a fabricated clean count. Rust module cycles are out of scope for `cycles`.\n\nUse when: starting work on unfamiliar code, after multi-edit batches to check diagnostics, before a refactor, before review, or to verify cleanup completeness.\n\nTreat `dead_code` as a hint, not proof: reachability is call-based, so symbols reached only via method dispatch or referenced only in type position may be false positives — verify before deleting."
},
"callgraph": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"op": {
"description": "Navigation operation",
"type": "string",
"enum": [
"call_tree",
"callers",
"trace_to",
"trace_to_symbol",
"impact",
"trace_data"
]
},
"filePath": {
"description": "Path to the source file containing the symbol (absolute or relative to project root)",
"type": "string"
},
"symbol": {
"description": "Name of the symbol to analyze",
"type": "string"
},
"depth": {
"description": "Max traversal depth (default: call_tree=5, callers=1, trace_to=10, trace_to_symbol=10 capped at 16, impact=5, trace_data=5)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"expression": {
"description": "Expression to track through data flow (required for trace_data op)",
"type": "string"
},
"toSymbol": {
"description": "Target symbol name for trace_to_symbol; the returned path ends at this symbol",
"type": "string"
},
"toFile": {
"description": "Optional target file for trace_to_symbol; required when toSymbol exists in multiple files",
"type": "string"
},
"includeTests": {
"description": "Include test files in callers/paths. Defaults to false; tests are hidden.",
"type": "boolean"
},
"includeUnresolved": {
"description": "Show every unresolved external/stdlib call individually. Defaults to false; unresolved leaf calls are collapsed into one summary per parent.",
"type": "boolean"
}
},
"required": [
"op",
"filePath",
"symbol"
],
"description": "Answer code-relationship questions from a real call graph — instead of grep + read chains. Reach for this whenever the question is about how symbols connect: who calls X, what X calls, what breaks if X changes, how execution reaches X, or how a value flows.\n\nUse aft_zoom with `callgraph:true` for one-level forward calls-out while reading source. Use aft_callgraph only for reverse callers or multi-level traces so you do not double-fetch the same relationships.\n\nOps:\n- 'callers': Find all call sites of a symbol. Use before renaming or changing a function's signature.\n- 'impact': What breaks if a symbol changes — affected callers with signatures and entry-point status (blast radius). Use before a risky edit.\n- 'call_tree': What a function calls (forward traversal). Use to understand a function's dependencies before modifying it.\n- 'trace_to': How execution reaches a function from entry points (routes, exports, main). Use to understand context around deeply-nested code.\n- 'trace_to_symbol': Shortest call path from one symbol to another. Requires 'toSymbol'. If multiple targets match, the error returns candidate files; retry with 'toFile' to disambiguate.\n- 'trace_data': Follow a value through variable assignments and function parameters across files. Requires 'symbol' (scope to trace from) and 'expression'.\n\nAll ops require both 'filePath' and 'symbol'. 'expression' is additionally required for trace_data; 'toSymbol' for trace_to_symbol.\n\nMarkers: ~ = edge resolved by name only (may point at the wrong same-named symbol); [unresolved] = callee not resolved to a definition, so the location shown is the call site. Unmarked edges are resolved exactly. By default, unresolved external/stdlib leaf calls in call_tree are collapsed into one summary per parent; pass includeUnresolved=true to show every unresolved edge individually.\n"
},
"conflicts": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"path": {
"description": "Optional path inside the git repository or worktree to inspect (absolute or relative to project root). Conflicts are discovered from that repository's top level. Defaults to the session project root.",
"type": "string"
}
},
"description": "Show all git merge conflicts across the repository — returns line-numbered conflict regions with context for every conflicted file in a single call. Conflicts are discovered from the git repository's top level. By default it inspects the session's project repository; pass `path` to inspect a different repository or git worktree (e.g. where a rebase/merge is running)."
},
"ast_search": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"pattern": {
"description": "AST pattern with meta-variables ($VAR, $$$). Must be complete AST node.",
"type": "string"
},
"lang": {
"description": "Target language",
"type": "string",
"enum": [
"typescript",
"tsx",
"javascript",
"python",
"rust",
"go",
"pascal",
"r",
"objc"
]
},
"paths": {
"description": "Paths to search (default: ['.'])",
"type": "array",
"items": {
"type": "string"
}
},
"globs": {
"description": "Include/exclude globs (prefix ! to exclude)",
"type": "array",
"items": {
"type": "string"
}
},
"contextLines": {
"description": "Number of context lines to show around each match",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"pattern",
"lang"
],
"description": "Search code patterns across filesystem using AST-aware matching. Supports 9 languages.\n\nUse meta-variables: $VAR matches a single AST node, $$$ matches multiple nodes (variadic).\nIMPORTANT: Patterns must be complete AST nodes (valid code fragments).\nFor functions, include params and body: 'export async function $NAME($$$) { $$$ }' not just 'export async function $NAME'.\n\nExamples: pattern='console.log($MSG)' lang='typescript', pattern='async function $NAME($$$) { $$$ }' lang='javascript', pattern='def $FUNC($$$): $$$' lang='python', pattern='Writeln($MSG);' lang='pascal', pattern='$X <- $Y' lang='r', pattern='[obj foo:$ARG]' lang='objc'"
},
"ast_replace": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"pattern": {
"description": "AST pattern with meta-variables ($VAR, $$$). Must be complete AST node.",
"type": "string"
},
"rewrite": {
"description": "Replacement pattern (can use $VAR from pattern)",
"type": "string"
},
"lang": {
"description": "Target language",
"type": "string",
"enum": [
"typescript",
"tsx",
"javascript",
"python",
"rust",
"go",
"pascal",
"r",
"objc"
]
},
"paths": {
"description": "Paths to search (default: ['.'])",
"type": "array",
"items": {
"type": "string"
}
},
"globs": {
"description": "Include/exclude globs (prefix ! to exclude)",
"type": "array",
"items": {
"type": "string"
}
},
"dryRun": {
"description": "Preview changes without applying (default: false)",
"type": "boolean"
}
},
"required": [
"pattern",
"rewrite",
"lang"
],
"description": "Replace code patterns across filesystem with AST-aware rewriting. Applies changes by default — set dryRun=true to preview.\n\nUse meta-variables in the rewrite pattern to preserve matched content from the pattern.\nIMPORTANT: Patterns must be complete AST nodes (valid code fragments).\n\nExample: pattern='console.log($MSG)' rewrite='logger.info($MSG)' lang='typescript' — replaces all console.log calls with logger.info across TypeScript files.\n\n**Warning: This tool modifies files directly.** Use dryRun=true to preview (shows per-file unified diff, capped at 8KB). Consider creating an aft_safety checkpoint before bulk replacements."
},
"delete": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"files": {
"description": "Paths to delete (one or more). May include directories when recursive=true.",
"minItems": 1,
"type": "array",
"items": {
"type": "string"
}
},
"recursive": {
"description": "Required to delete a directory and its contents. Defaults to false; passing a directory without this returns an error.",
"type": "boolean"
}
},
"required": [
"files"
],
"description": "Delete one or more files (or directories).\n\nEach file is backed up before deletion — use aft_safety undo to recover any of them. For directories, every file inside is individually backed up before the tree is removed. Directory deletion requires recursive: true. Without it, passing a directory returns an error.\n\nPartial success is allowed: deletable files are deleted; failed ones are reported in `skipped_files` with `complete: false`."
},
"move": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"filePath": {
"description": "Source file path to move (absolute or relative to project root)",
"type": "string"
},
"destination": {
"description": "Destination file path (absolute or relative to project root)",
"type": "string"
}
},
"required": [
"filePath",
"destination"
],
"description": "Move or rename a file. Creates an undo backup before moving. Creates parent directories for destination automatically\nNote: This moves/renames files at the OS level. To move a code symbol (function, class, type) between files while updating imports, use `aft_refactor` op='move' instead."
},
"import": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"op": {
"description": "Import operation",
"type": "string",
"enum": [
"add",
"remove",
"organize"
]
},
"filePath": {
"description": "Path to the file (absolute or relative to project root)",
"type": "string"
},
"module": {
"description": "Module path (required for add, remove — e.g. 'react', './utils', 'std::fmt')",
"type": "string"
},
"names": {
"description": "Named imports to add. Each entry uses the language's native named-import text, including per-name aliasing where the language uses `as` (e.g. ['useState', 'debounce as db'], Solidity ['ERC20', 'IERC20 as IToken']).",
"type": "array",
"items": {
"type": "string"
}
},
"defaultImport": {
"description": "Default import name, ES only (e.g. 'React')",
"type": "string"
},
"namespace": {
"description": "Namespace binding: `import * as ns from 'mod'` (ES), `import * as N from \"./X.sol\"` (Solidity).",
"type": "string"
},
"alias": {
"description": "Whole-module alias. Solidity: `import \"./X.sol\" as X` (module=path, alias=X).",
"type": "string"
},
"modifiers": {
"description": "Statement-level modifier tokens, language-validated: Java/C# 'static'; C# 'global'/'unsafe'; Java/Kotlin/Scala 'wildcard'; Swift '@testable'. Unsupported tokens for the file's language return a clear error.",
"type": "array",
"items": {
"type": "string"
}
},
"importKind": {
"description": "Symbol-kind-specific import: PHP 'function'/'const'; Swift 'struct'/'class'/'enum'/'protocol'/'func'; Scala 'given'.",
"type": "string"
},
"typeOnly": {
"description": "Type-only import (TS only, default: false)",
"type": "boolean"
},
"removeName": {
"description": "Named import to remove for 'remove' op; omit to remove entire import",
"type": "string"
},
"validate": {
"description": "Validation level: 'syntax' (default) or 'full'. Syntax = tree-sitter parse check only. Full = also runs LSP type-checking (slower, catches more errors)",
"type": "string",
"enum": [
"syntax",
"full"
]
}
},
"required": [
"op",
"filePath"
],
"description": "Language-aware import management. Supports TS, JS, TSX, Python, Rust, Go, Solidity, Java, C#, PHP, Kotlin, Scala, Swift, Ruby, Lua, C, C++, Perl, and Vue.\n\nOps:\n- 'add': Add an import. Auto-detects group (stdlib/external/internal), deduplicates. Requires 'module'. Optional 'names', 'defaultImport', 'typeOnly'.\n- 'remove': Remove an import or a specific named import. Requires 'module'. Provide 'removeName' to remove a single named import; omit to remove the entire import.\n- 'organize': Re-sort and re-group all imports by language convention, deduplicate. Requires only 'filePath'. Use aft_safety checkpoint/undo for recovery before broad cleanup."
},
"refactor": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"op": {
"description": "Refactoring operation",
"type": "string",
"enum": [
"move",
"extract",
"inline"
]
},
"filePath": {
"description": "Path to the source file (absolute or relative to project root)",
"type": "string"
},
"symbol": {
"description": "Symbol name — required for 'move' and 'inline' ops",
"type": "string"
},
"destination": {
"description": "Target file path — required for 'move' op",
"type": "string"
},
"scope": {
"description": "Disambiguation scope for 'move' op — when multiple top-level symbols share the same name, specify the containing scope to disambiguate (e.g. 'MyClass'). Does NOT enable access to nested symbols or class methods.",
"type": "string"
},
"name": {
"description": "New function name — required for 'extract' op",
"type": "string"
},
"startLine": {
"description": "1-based start line — required for 'extract' op",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"endLine": {
"description": "1-based end line (inclusive) — required for 'extract' op",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"callSiteLine": {
"description": "1-based call site line — required for 'inline' op",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"op",
"filePath"
],
"description": "Workspace-wide refactoring that updates imports and references across files.\n\nOps:\n- 'move': move a top-level symbol (not nested functions or class methods) to another file, rewriting imports workspace-wide. A checkpoint is created first. To move/rename a whole file, use aft_move.\n- 'extract': extract a line range into a new function with auto-detected parameters (TS/JS/TSX, Python).\n- 'inline': replace a function call with the function's body."
},
"safety": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"op": {
"description": "Safety operation",
"type": "string",
"enum": [
"undo",
"history",
"checkpoint",
"restore",
"list"
]
},
"filePath": {
"description": "File path (required for history, optional for undo). Absolute or relative to project root",
"type": "string"
},
"name": {
"description": "Checkpoint name (required for checkpoint, restore)",
"type": "string"
},
"files": {
"description": "Specific files to include in checkpoint (optional, defaults to all tracked files)",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"op"
],
"description": "File safety and recovery operations.\n\nPer-file undo stack is capped at 20 entries (oldest evicted).\n\nOps:\n- 'undo': Undo the entire last tool call when 'filePath' is omitted (typical), or undo the last edit to one file when 'filePath' is provided. Note: pops from the undo stack (irreversible, no redo). Use 'history' to inspect per-file history before undoing.\n- 'history': List all edit snapshots for a file. Requires 'filePath'.\n- 'checkpoint': Save a named snapshot of tracked files. Requires 'name'. Optional 'files' to snapshot specific files only.\n- 'restore': Restore files to a previously saved checkpoint. Requires 'name'.\n- 'list': List all available named checkpoints. No extra params needed.\n\nEach op requires specific parameters — see parameter descriptions for requirements.\n\nUse checkpoint before risky multi-file changes. Use undo for quick single-file rollback."
}
}