Tool Overview
The full set of tools agentty can call, and how they render.
Each tool gets a purpose-built widget: diffs render as diffs, search results group by file with line numbers, bash shows exit codes, todos become checklists.
| Tool | Effect class | Description |
|---|---|---|
read | Read | Read a file (or a line range). Large files return a symbol outline first. symbol="name" reads exactly one function/type's definition + body (resolved to its enclosing block) — no line math or sed. |
write | Write | Create a new file with atomic write semantics. |
edit | Write | Apply targeted text substitutions to an existing file; renders a diff. |
move | Write | Move or rename a file/directory without a shell. |
remove | Write | Delete a file or directory (recursive requires an explicit flag). |
bash | Shell | Run a shell command inside the sandbox; shows exit code + output. |
process_start / process_poll / process_stop | Shell | Start, poll, and stop a long-running background process (dev servers, watchers) without blocking the turn. |
grep | Read | Regex search across files, grouped by file with line numbers. Prefers ripgrep when installed; both backends skip generated trees (build*, _deps, node_modules, vendor, .git, …) so build artifacts never pollute the hits. word=true matches whole identifiers only (no foo inside foobar); context:"block" returns each hit's whole enclosing function/block so you rarely need a follow-up read. |
glob | Read | Find files by glob pattern. |
list_dir | Read | List a directory with type, size, and name. |
repo_map | Read | Token-budgeted, PageRank-ranked skeleton of the codebase — top files with definition signatures, personalizable with focus. The walk stops at any nested repo/submodule boundary and never leaves the workspace, so sibling projects can't leak into the map. THE tool to call first in a large or unfamiliar repo. |
find_definition | Read | Locate a symbol's definition across the codebase (curated per-language patterns). To find USES, use grep with word=true; for a ranked overview use repo_map. |
search_structural | Read | Structural (AST-shape) code search on a nested-document model (like Semgrep-generic / ast-grep) — the layer between grep (text) and search_code (meaning). Never matches inside comments or string literals. Metavariables: $X matches exactly one node (an atom or a balanced (…)/[…]/{…} group) and binds it; $$$X matches many nodes (arg lists, multi-token conditions). Recurses into nested groups. Dep-free (lexer + nested-tree matcher, no tree-sitter). e.g. foo($$$), if ($$$C) return $X;, catch ($$$) {}, $X = $X. |
web_fetch | Network | Fetch a URL (capped output) for docs and APIs. |
web_search | Network | Search the web and return result snippets. |
todo | Pure | Maintain a session todo / plan list, rendered as a checklist. |
diagnostics | Shell | Run the project's build/lint and surface errors and warnings. |
test | Shell | Run focused project tests (CTest/Cargo/Go/npm/Make auto-detected) with structured pass/fail output. |
skill | Pure | Load a named skill's full instructions from .agentty/skills/ before attempting a task it covers. |
task | Network | Spawn an autonomous subagent (explorer / reviewer / tester / coder / general) with its own context and tool budget; returns one condensed report. Read-only roles (explorer, reviewer) automatically route to the cheapest capable model on the active provider — tester/coder/general keep the parent model — so fan-out exploration costs a fraction of the main turn. |
search_docs | Network | Query your knowledge base — docs, installed skills, and learned memory — with agentty's hybrid BM25 + dense retrieval engine, reranked, diversified, and expanded over the corpus's GraphRAG document graph; returns the most relevant passages, source-tagged. Works with zero docs configured (skills + memory are always indexed). |
search_code | Read | Semantic search over source code by meaning, not literal text — finds the relevant function for a conceptual query ("where is retry backoff handled") even with zero shared keywords. See Retrieval. |
git_status | Read | Show branch, staged/unstaged changes, untracked files. |
git_diff | Read | Show a diff (unstaged, staged, or a ref range). |
git_log | Read | Show commit history. |
git_show | Read | Show a commit's metadata + patch, or a file's contents at a revision. |
git_blame | Read | Annotate a file or line range with the commit/author/date that last changed it. |
git_commit | Write | Stage files and create a commit. |
remember / forget | Pure | Persist or remove durable facts across sessions. |
wipe_memory | Pure | Clear every remembered fact in a scope (confirm-gated). |
ℹNoteThe effect class determines which permission profile auto-runs the tool. Pure and Read tools run automatically in Ask and Write; Write, Shell, and Network are gated by your profile. The Minimal profile prompts on every class, reads included.
Compile-time enforcement
Each tool's effect set is declared at compile time and checked against the permission matrix via static_assert. A tool can't accidentally gain a side effect that the policy doesn't account for — the build catches it.
Parallel & speculative execution
The effect classes above aren't just for permissions — they drive a scheduler that overlaps tool work to cut wall-clock time.
- Parallel batches. When the model emits several tool calls in one turn, agentty runs the safe combinations concurrently and serializes only what genuinely conflicts. Two reads, a grep, and a web fetch all fire at once; a
writewaits for anything touching the same path, and abashwaits for exclusive access. The rule is a proven, effect- and path-aware invariant — a wide batch is never unsafe, so the model is encouraged to fan out. - Speculative reads. A pure Read tool starts the instant its arguments finish streaming — while the model is still writing the rest of the turn. Its I/O overlaps the remaining stream instead of waiting for the turn to finish, so a multi-tool turn hides seconds of file/search time inside the model's own generation. Read-only tools can't affect what the model is still saying, so this is always safe; anything that writes, executes, or hits the network waits for the normal end-of-turn scheduler.
Neither behavior changes results — only when the work happens. You'll simply notice tool-heavy turns finishing faster.
Extending the toolset
The native tools are the floor, not the ceiling. Four mechanisms extend what the agent can do:
- Plugins — add external tools via MCP servers (a browser driver, a database client, a hosted API).
- Subagents — delegate a self-contained task to an isolated agent with its own context window, via the
tasktool. - Slash commands — reusable prompt macros you invoke as
/name. - Hooks — run your own shell commands around every tool call, to block or observe.