Tools
Dynamo has built-in tools that the AI model uses to interact with your project. Run /tools to see the full list.
File Tools
| Tool | Description |
|---|---|
read_file | Read file contents — text (line-numbered), images (vision), PDFs, notebooks |
write_file | Create or overwrite a file |
edit_file | Find-and-replace edit within a file |
list_files | List files matching a glob pattern |
search_files | Search for patterns across files (ripgrep-backed) |
read_file
Reads any file type. Dispatches by extension:
| File Type | Behavior |
|---|---|
Text (.cs, .ts, .yaml, etc.) | Line-numbered content with offset/limit params |
Image (.png, .jpg, .gif, .webp) | Base64 sent to vision models. RGBA PNGs flattened to RGB. |
PDF (.pdf) | Text extraction with optional pages param ("1-5", "3") |
Notebook (.ipynb) | Parsed cells with code blocks, markdown, and outputs |
Binary (.fbx, .exe, .mp3, etc.) | Rejected with file info |
search_files
Powered by ripgrep (rg). Falls back to basic JS regex if rg is not installed.
| Parameter | Description |
|---|---|
pattern | Regex pattern to search for |
path | Directory to search (default: project root) |
glob | Glob filter (e.g. "*.ts", "*.{cs,shader}") |
type | File type shorthand (ts, cs, py, json, hlsl, etc.) |
output_mode | files_with_matches (default), content, count |
context | Lines of context before and after each match |
case_insensitive | Case-insensitive search |
head_limit | Max results (default: 250) |
offset | Skip first N results |
multiline | Enable multiline mode (. matches newlines) |
Shell
run_command executes shell commands with:
- Two invocation modes —
command: "string"(shell-wrapped, supports pipes/glob/redirect) orargv: ["array", "form"](direct spawn, no escaping needed for paths with spaces). Exactly one must be provided. - Persistent working directory —
cdcarries across tool calls. Reset on/clear. - Configurable timeout — default 2 minutes, max 10 minutes. Set in
dynamo.yamlunderai.shell.defaultTimeout. - Background execution — long commands can run in the background. Model gets notified when they finish.
- Middle truncation — large output keeps the first and last 25K chars, truncates the middle.
- Shell detection — uses your
$SHELL(bash or zsh), not hardcoded. - `DYNAMO=1` environment variable set so your scripts can detect they're running inside Dynamo.
Background Jobs
When the model runs a command with run_in_background: true:
- The command starts immediately and the model continues responding
- The jobs bar shows at the bottom:
Jobs: 1 Ctrl+G to focus - Press Ctrl+G to open the jobs picker with progress bars
- When the job finishes, the model auto-responds with the result
- Press Ctrl+K in the jobs picker to kill a running job
Web Tools
| Tool | Description |
|---|---|
web_fetch | Fetch a URL and return content as markdown |
web_search | Search the web (provider-native, runs on Anthropic/OpenAI servers) |
web_fetch
Fetches a URL, extracts article content with Readability, converts HTML to markdown.
- HTTPS upgrade —
http://URLs auto-upgraded tohttps:// - 15-minute cache — same URL returns cached result
- Readability extraction — strips nav, ads, sidebars, returns article content only
- 50K char cap — large pages truncated with notice
- 30s timeout — prevents hanging on slow servers
web_search
Server-side search — the provider runs the search, not Dynamo. No separate API key needed.
| Provider | How it works |
|---|---|
| Anthropic (Claude) | Server-side tool. Returns structured results with title, URL, and page age. |
| OpenAI (GPT-5.x) | Responses API with web search. Citations embedded inline in response text. |
| Ollama (local) | No web search available. Model can still use web_fetch on known URLs. |
Interactive
| Tool | Description |
|---|---|
ask_user | Ask the user a structured question with selectable options |
The model calls ask_user when it needs a decision — choosing between approaches, confirming a plan, selecting config options. Shows an interactive picker you navigate with arrow keys.
- Single or multi-question — up to 4 questions per call
- Tab navigation — switches between questions
- Option selection — arrow keys to navigate, Enter to select
- Custom input — "Other..." option opens inline text field for free-form answers
Task Management
| Tool | Description |
|---|---|
task_create | Create a task to track a unit of work |
task_list | List all tasks with status |
task_update | Update status, subject, description, or dependencies |
task_get | Get full task details |
task_stop | Stop/cancel a task |
task_clear | Clear tasks by status or all |
Tasks track multi-step work with status and dependencies:
pending → in_progress → completed
→ stoppedWhen a blocking task completes, dependent tasks auto-unblock. IDs are sequential — adding or deleting renumbers all tasks.
Use /tasks for an interactive task manager overlay, or let the model manage tasks via tool calls.
Git Tools
| Tool | Description |
|---|---|
git_status | Show branch, tracking info, staged/unstaged changes |
git_diff | Show file changes with diff rendering |
git_log | Show recent commit history |
git_commit | Stage files and create a commit |
gh_pr_create | Create a GitHub pull request |
gh_pr_view | View PR details and review status |
Permissions
Tools are classified by risk level:
| Level | Behavior | Examples |
|---|---|---|
| Safe | Auto-execute | read_file, list_files, search_files, git_status, web_search |
| Write | Prompt once per session | write_file, edit_file, web_fetch, git_commit |
| Dangerous | Always prompt | run_command |
| Blocked | Rejected immediately | sudo, git push --force to main/master, command substitution ($(), backticks, ${}) |
"Allow all" is scoped per-tool per-model. Switching models resets approvals.
Use --permissive (-y) to skip all prompts except blocked commands. Even in permissive mode, writes to protected files (.env, .git/config, .ssh/*, .bashrc, credentials.json, *.pem, *.key) still require explicit approval.
See Permissions & Security for the full security model.
Sandbox Mode
Controls filesystem access for all tools including shell commands.
| Mode | read_file | write/edit | list/search | run_command |
|---|---|---|---|---|
| project | project only | project only | project only | blocks external paths |
| full (default) | anywhere | project only | anywhere | permission gated |
| unrestricted | anywhere | anywhere | anywhere | permission gated |
Set via CLI (--sandbox project), config (ai.sandbox: project), or at runtime (/sandbox).
Checkpoints
Auto-checkpoint before file edits — snapshot the file's pre-write state so you can undo.
- Auto-checkpoint — created before every
write_file/edit_file - File-level snapshots — copies file content before modification. New files snapshot as "didn't exist"
- Rollback — restores files to pre-write state. Also rewinds conversation history.
- Disk persistence — survives restarts, stored in
~/.config/dynamo/checkpoints/ - 30-day cleanup — old checkpoints auto-purged on startup
Use /checkpoint for an interactive overlay to rollback, delete, or create manual checkpoints.
Configurable: ai.auto_checkpoint: false in dynamo.yaml to disable.
Syntax Highlighting
Tool results and model responses are syntax highlighted:
- Code blocks highlighted with Catppuccin Mocha theme (191 languages)
- File reads highlighted by file extension
- Diffs rendered with line numbers, background tints, and word-level inline diff
- Markdown rendered inline: headers, bold, inline code, links