Tools¶
anthrogo ships 30+ built-in tools covering file I/O, shell execution, code intelligence, web access, databases, speech, containers, and background tasks. The model selects tools automatically; every call passes through the permission gate.
Tool table¶
| Tool | Read-only | Description |
|---|---|---|
Read |
yes | Read a file with optional offset/limit; cat-n style line numbers |
Write |
no | Write content to a path, creating parent directories as needed |
Edit |
no | Replace old_string with new_string (unique match required unless replace_all: true) |
Glob |
yes | doublestar glob; results sorted newest-first by mtime |
Grep |
yes | Go regexp recursive search with output_mode and glob filter |
Bash |
no | Run a shell command with timeout_ms (default 120000); pass sandbox: true for opt-in sandboxing |
TodoWrite |
no | Maintain a replace-on-write task list |
Diff |
yes | git diff wrapper; supports path, cached, context, stat, and range (commit range) |
Format |
no | Format files: gofmt / prettier / black / ruff / rustfmt; supports paths batch |
Git |
yes | Read-only git subcommands: status, log, branch, show, blame, remote |
SymbolSearch |
yes | Find a symbol's definition by name; Go via go/parser, others via regex heuristics |
References |
yes | Find all word-boundary usages of a name across the tree |
WebSearch |
yes | Search the web via brave, google, bing, or tavily |
WebFetch |
yes | GET-only HTTP fetch; HTML→markdown, 15-min LRU cache |
HTTPRequest |
no* | Full HTTP client: GET/POST/PUT/DELETE/PATCH/HEAD, arbitrary body, headers, save_to, size cap. *Read-only for GET/HEAD |
SQLQuery |
no* | Run SQL against postgres/mysql/sqlite; DSN supports env:VARNAME. SELECT/EXPLAIN/SHOW/DESCRIBE auto-allow; mutating queries ask |
SpeechToText |
yes | Transcribe audio via OpenAI Whisper CLI |
TextToSpeech |
no | Synthesize speech via platform synthesizer (say / espeak) |
ContainerExec |
no | Run a command in a docker/podman container; network=none default, --rm always |
BackgroundLaunch |
no | Start sh -c <command> in background; returns task_id immediately |
BackgroundStatus |
yes | Status of one task (pass task_id) or list all tasks (omit) |
BackgroundOutput |
yes | Fetch captured stdout + stderr for a task |
BackgroundCancel |
no | Send cancellation signal to a running task |
MCPResource |
yes | List or read resources from MCP servers; default alwaysAllow |
Skill |
yes | Invoke a named skill — loads SKILL.md into the model context |
Task |
no | Spawn a subagent engine; see Subagents |
PDFRead |
yes | Extract plain text from a local PDF file; optional page range ("1-5", "3", "10-end"); 200 KB cap; default alwaysAllow |
XlsxRead |
yes | Read a sheet of a local .xlsx file as TSV; optional sheet name and A1 range; 200 KB cap; default alwaysAllow |
BrowserAction |
no | Headless Chrome automation: get (navigate), click (CSS selector), text (extract visible text), screenshot (save PNG). Lazy Chrome init; serialised through one shared instance. Not in default alwaysAllow — goes through permission gate. |
SlackPost |
no | POST a message to a Slack channel via an Incoming Webhook URL. Supports text, Block Kit blocks, username, and icon_emoji. Falls back to SLACK_WEBHOOK_URL env var. Goes through permission gate (Ask). |
CalendarEvent |
no | Generate an .ics file for a calendar event (title, start/end RFC3339, description, location, out_path). On macOS, add_to_calendar_app: true opens the file in Calendar.app. Goes through permission gate (Ask). |
Embed |
yes | Convert text to embedding vectors via an OpenAI-compatible /embeddings endpoint. Accepts input (single) or input_list (batch). Resolves credentials from ANTHROGO_EMBED_API_KEY / OPENAI_API_KEY. out_format: summary (default) or json. |
ImageGen |
no | Generate an image from a text prompt via an OpenAI-compatible /images/generations endpoint. Saves the result as a PNG at out_path (default $TMPDIR/anthrogo-imagegen-<ts>.png). Resolves credentials from ANTHROGO_IMAGE_API_KEY / OPENAI_API_KEY. Goes through permission gate (Ask). |
NotebookEdit |
no | Edit a Jupyter notebook cell in place. Operations: replace_cell, insert_cell_before, insert_cell_after, delete_cell. Required fields: file_path, operation, cell_index. Optional: cell_type (code/markdown/raw, default code), new_source. |
EnterPlanMode |
yes | Switch the session into plan-only mode: write tools (Write/Edit/NotebookEdit, non-read-only Bash) are blocked until ExitPlanMode is called. No input fields required. |
ExitPlanMode |
yes | Exit plan mode and restore the previous permission level. No input fields required. |
AskUserQuestion |
yes | Present an interactive multiple-choice prompt to the user. Required: question (string), options (array of 2–4 objects with label and optional description). Interactive REPL mode only — unavailable in headless/serve mode. |
Permission model¶
For every tool call permissions.Decide runs through priority order:
bypassPermissionsmode → allowalwaysDenyrules → denyacceptEditsmode → allow Write/Edit/NotebookEdit by defaultalwaysAllowrules → allowalwaysAskrules → ask- Otherwise → ask (TUI modal) or deny (headless /
ShouldAvoidPrompts)
Configure rules in ~/.anthrogo/settings.yaml:
alwaysAllow:
- tool: Read
- tool: Glob
- tool: Grep
- tool: Bash
match: "git status*"
alwaysDeny:
- tool: Bash
match: "rm -rf*"
match is a glob pattern matched against the full tool input string. Omit to match all invocations of that tool.
Bash sandbox¶
Pass "sandbox": true in the Bash tool input to enable two-layer opt-in sandboxing:
- AST scan (
pkg/bashscan/) — parses viamvdan.cc/sh/v3/syntaxand blocks commands invoking:sudo,doas,rm,dd,mkfs,mount,umount,chmod,chown,chroot,setuid,setgid. Parse failures are rejected (conservative fallback). - Substring denylist — rejects commands containing:
../,~/.ssh,~/.aws,~/.gnupg,~/.kube,/etc/passwd,/etc/shadow,/private/etc/,/var/log,/proc/,/sys/.
Sandboxed commands run with PATH=/usr/bin:/bin:/usr/sbin:/sbin and have sensitive env vars stripped (AWS_*, SSH_*, ANTHROPIC_API_KEY, etc.).
Limitation:
$VAR-style indirection is not expanded by the AST scanner. For real isolation useContainerExec.
ContainerExec¶
Auto-detects docker on PATH; falls back to podman. Default network is none.
tool: ContainerExec
input:
image: alpine
command: "echo hello && uname -a"
network: none
mounts:
- /host/data:/data:ro
- /host/out:/out:rw
env:
MY_VAR: hello
timeout_ms: 30000
pull_policy: missing # always | missing (default) | never
gpu: false # true adds --gpus all (needs NVIDIA Container Toolkit)
user: "1000:1000"
workdir: /app
pull_policy values:
- always — runs docker pull before run (10-minute timeout)
- never — passes --pull never; fails if image not locally cached
- missing (default) — lets the container runtime decide
Result.Text shows stdout; stderr appended after --- stderr --- if non-empty. Programmatic callers can read Result.Data["stdout"], Result.Data["stderr"], Result.Data["exit_code"].
Background task tools¶
BackgroundLaunch({command: "make build", env: {GOOS: "linux"}})
→ {task_id: "abc123"}
BackgroundStatus({task_id: "abc123"})
→ {state: "running", started_at: "2026-05-21T10:00:00Z"}
BackgroundOutput({task_id: "abc123"})
→ {stdout: "...", stderr: "..."}
BackgroundCancel({task_id: "abc123"})
→ {ok: true}
Tasks are in-memory only — lost on process restart. Stdout/stderr are fully buffered in RAM; avoid tasks that emit very large output.
WebSearch backends¶
Configure in ~/.anthrogo/settings.yaml:
# Brave (default)
webSearch:
backend: brave
apiKey: "BSA..."
# Google Custom Search
webSearch:
backend: google
apiKey: "AIza..."
endpoint: "cse-id-here" # cx parameter
# Bing / Azure Cognitive Search
webSearch:
backend: bing
apiKey: "abc..."
# Tavily
webSearch:
backend: tavily
apiKey: "tvly-..."
# Disable
webSearch:
backend: disabled
All backends return {title, url, description} objects. Google caps at 10 results; Bing at 50; Tavily at 20. The optional url field overrides the default endpoint (useful for self-hosted proxies).
Speech tools¶
SpeechToText¶
Requires: pip install openai-whisper
| Parameter | Default | Description |
|---|---|---|
path |
required | Audio file (wav / mp3 / m4a / flac) |
model |
base |
tiny / base / small / medium / large |
binary |
whisper |
Override whisper binary path |
TextToSpeech¶
| Platform | Binary used |
|---|---|
| macOS | say (built-in) |
| Linux | espeak or espeak-ng |
| Windows | not yet supported |
| Parameter | Default | Description |
|---|---|---|
text |
required | Text to speak |
output |
(play live) | Optional output file path (AIFF on macOS, WAV on Linux) |
voice |
system default | Voice name (platform-specific) |
SQLQuery¶
Supports postgres, mysql, and sqlite via database/sql:
tool: SQLQuery
input:
dsn: "postgres://user:pass@host:5432/db"
# or: dsn: "env:DATABASE_URL"
query: "SELECT id, name FROM users LIMIT 10"
params: []
timeout_ms: 10000
max_rows: 500
HTTPRequest¶
tool: HTTPRequest
input:
method: POST
url: https://api.example.com/v1/items
headers:
Content-Type: application/json
Authorization: "Bearer env:MY_TOKEN"
body: '{"name": "test"}'
save_to: /tmp/response.json
timeout_ms: 30000
max_bytes: 10485760
BrowserAction¶
Headless Chrome automation powered by chromedp. A single Chrome instance is lazily started on first use and reused across calls; it is shut down when the engine exits.
Schema¶
| Field | Type | Required | Description |
|---|---|---|---|
mode |
string (enum) | yes | get / click / text / screenshot |
url |
string | for get |
URL to navigate to |
selector |
string | for click; optional for text / screenshot |
CSS selector |
timeout_ms |
integer | no | Per-call timeout (default 15000 ms) |
out_path |
string | for screenshot |
Absolute path to write the PNG file |
Usage examples¶
# Navigate to a page
tool: BrowserAction
input:
mode: get
url: https://example.com
# Click a button
tool: BrowserAction
input:
mode: click
selector: "button#submit"
# Extract page text (defaults to <body>)
tool: BrowserAction
input:
mode: text
url_already_navigated: true # (navigate first with get)
# Full-page screenshot
tool: BrowserAction
input:
mode: screenshot
out_path: /tmp/page.png
# Element screenshot
tool: BrowserAction
input:
mode: screenshot
selector: "#chart"
out_path: /tmp/chart.png
Permissions¶
BrowserAction has IsReadOnly: false and is not in the default alwaysAllow list. Every call goes through the permission gate (Ask by default). To auto-allow:
alwaysAllow:
- tool: BrowserAction
E2E tests¶
Set ANTHROGO_E2E_BROWSER=1 to opt-in to the live Chrome end-to-end test suite:
ANTHROGO_E2E_BROWSER=1 go test ./pkg/tool/ -run TestBrowser -v
CI runs without Chrome; only schema + input-validation tests execute.
SlackPost¶
Send a message to a Slack channel via a configured Incoming Webhook URL.
Schema¶
| Field | Type | Required | Description |
|---|---|---|---|
webhook_url |
string | no* | https://hooks.slack.com/services/… URL. Falls back to SLACK_WEBHOOK_URL env var. |
text |
string | yes | Message text (Slack mrkdwn supported). |
blocks |
string | no | Raw JSON for Slack Block Kit (array of block objects). When set, bypasses plain-text rendering. |
username |
string | no | Override the webhook's default display name. |
icon_emoji |
string | no | Override the default icon, e.g. ":robot_face:". |
* Required unless SLACK_WEBHOOK_URL env var is set.
Usage examples¶
# Plain text message
tool: SlackPost
input:
webhook_url: https://hooks.slack.com/services/T000/B000/xxxx
text: "Deploy succeeded on `main` at 14:32 UTC"
# Block Kit rich message
tool: SlackPost
input:
webhook_url: https://hooks.slack.com/services/T000/B000/xxxx
text: "Fallback: build failed"
blocks: |
[
{"type":"section","text":{"type":"mrkdwn","text":"*Build failed* on `main`"}},
{"type":"divider"},
{"type":"section","text":{"type":"mrkdwn","text":"Check <https://ci.example.com|CI dashboard>"}}
]
username: "ci-bot"
icon_emoji: ":x:"
# Use env var for URL
tool: SlackPost
input:
text: "Hello from anthrogo"
# SLACK_WEBHOOK_URL must be set in the shell environment
Permissions¶
SlackPost has IsReadOnly: false and is not in the default alwaysAllow list. Every call goes through the permission gate. To auto-allow:
alwaysAllow:
- tool: SlackPost
CalendarEvent¶
Create a calendar event as a standard .ics file (iCalendar RFC 5545). On macOS, optionally opens the file in Calendar.app.
Schema¶
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | yes | Event summary. |
start |
string | yes | RFC3339 start time, e.g. 2026-05-22T15:00:00+08:00. |
end |
string | yes | RFC3339 end time. Must be after start. |
description |
string | no | Event description body. |
location |
string | no | Location string. |
out_path |
string | no | Absolute path for the .ics file. Default: $TMPDIR/<slugified-title>.ics. |
add_to_calendar_app |
boolean | no | macOS only. If true, runs open <out_path> to hand off to Calendar.app. |
Usage examples¶
# Create a simple event
tool: CalendarEvent
input:
title: "Weekly sync"
start: "2026-05-25T10:00:00+08:00"
end: "2026-05-25T11:00:00+08:00"
description: "Team weekly standup"
location: "Zoom"
out_path: /tmp/weekly-sync.ics
# Create and open in macOS Calendar.app
tool: CalendarEvent
input:
title: "Deployment window"
start: "2026-05-28T02:00:00+00:00"
end: "2026-05-28T04:00:00+00:00"
description: "v2.3 rollout\nRollback plan: see runbook"
add_to_calendar_app: true
Permissions¶
CalendarEvent has IsReadOnly: false and is not in the default alwaysAllow list. To auto-allow:
alwaysAllow:
- tool: CalendarEvent
Vision / images¶
Use @image:<path> in any prompt to attach a local image:
@image:./screenshot.png what's wrong with this UI?
describe @image:~/photo.jpg and @image:~/chart.png
Supported MIME types: image/png, image/jpeg, image/gif, image/webp. Only local file paths are supported (no URLs in the @image: syntax).
- Anthropic provider: native
imagecontent block - OpenAI-compatible provider:
{type: "image_url", image_url: {url: "data:<mime>;base64,..."}}