Skip to content

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:

  1. bypassPermissions mode → allow
  2. alwaysDeny rules → deny
  3. acceptEdits mode → allow Write/Edit/NotebookEdit by default
  4. alwaysAllow rules → allow
  5. alwaysAsk rules → ask
  6. 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:

  1. AST scan (pkg/bashscan/) — parses via mvdan.cc/sh/v3/syntax and blocks commands invoking: sudo, doas, rm, dd, mkfs, mount, umount, chmod, chown, chroot, setuid, setgid. Parse failures are rejected (conservative fallback).
  2. 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 use ContainerExec.

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 image content block
  • OpenAI-compatible provider: {type: "image_url", image_url: {url: "data:<mime>;base64,..."}}