Tools

Tools are the things Atomic Agent can actually do on your machine: open a web page, read a file, run a shell command, pull text out of a PDF, copy something to your clipboard, or pop a desktop notification. The model decides which tool to use; the runtime runs it and feeds the result back. Everything happens locally, and anything risky pauses for your approval first.

This page is a tour of the desktop tool surface — what each family can do, and where the safety rails are.

Developer Preview

Atomic Agent is in Developer Preview. The tool set and names below are real, but they may shift between releases. Pin a version if you’re integrating against them.

See what this agent can actually do

The fastest answer to “does it have a tool for that” comes from the agent itself. Type /tools in the TUI and it prints the live built-in catalog as plain text — no panel, no navigation.

/tools              # the whole built-in catalog, grouped by family
/tools filesystem   # only the tools matching a query

The listing is filtered through the same config gates the runtime applies, so a family you have disabled — browser, web search, vision, a memory channel — never appears. What you see is what the model sees.

/tools <query> matches on the family name, and an alias map covers the words people actually search for rather than the namespaces the tools live under. filesystem, file, files, fs, and disk all resolve to os.fs; bash, shell, and terminal to os.shell; chrome to browser; notes to memory.notes; and so on for web, http, network, git, vision, and images.

Why this exists

Users were searching /skills for “filesystem”, finding nothing, and concluding the agent could not touch files at all. It can — the file tools are built in, not skills. /tools filesystem answers that question directly instead of drawing a blank.

How a tool call works

Every turn, the model emits a JSON array of one or more tool calls. The runtime looks each one up in the tool registry by its fully-qualified name (for example os.fs.read or browser.navigate), validates the arguments, checks whether the action is dangerous, runs it, and compresses the result before handing it back to the model.

flowchart TD
    A["Model emits tool calls<br/>(JSON array)"] --> B["ToolRegistry.invoke(name, args)"]
    B --> C{Dangerous op?}
    C -->|"read-only<br/>(os.fs.read, browser.read_aria)"| D["Run immediately"]
    C -->|"dangerous<br/>(shell, fs.write, http)"| E["Approval gate"]
    E -->|approved| D
    E -->|denied| F["ApprovalDeniedError"]
    D --> G["compressToolResult()<br/>trim + summarize"]
    G --> H["Result back to model"]

Two things are worth knowing up front:

• Paths are relative to the session’s working directory. A path like ./notes/todo.md or ~/file.txt resolves against the directory you launched the agent in (--cwd), not the process CWD.
• Read-only tools run in parallel; everything else is serialized. The agent batches independent reads (like several os.fs.read calls) so they fan out at once, while writes and other side-effecting tools run one at a time.

The tool families

Browser

Navigate, click, type, scroll, read the page, and manage tabs via a real Chromium browser.

Files

Read, write, edit, search, glob, diff, patch, and hash files. Extract text from PDFs, DOCX, XLSX, and more.

Shell

Run approved commands, inspect processes, and use git — all guarded by a command rule system.

Desktop

Clipboard, desktop notifications, web search and fetch, and window controls.

Browser

The browser tools drive a real Chromium instance (via Playwright), so the agent can use sites the way you would.

Tool	What it does
browser.navigate	Open a URL
browser.click	Click an element
browser.type	Type into a field
browser.read_aria	Read a compressed accessibility snapshot of the page
browser.search	Run a search
browser.scroll	Scroll the page
browser.tabs	List and switch tabs

After a navigation or search, the agent keeps a compressed snapshot of the page’s accessibility tree so it can reason about what’s on screen without re-reading it every step.

Caution

The browser is not bundled. You need Chrome, Edge, or Chromium installed. Pick one with browser.channel in config.json (or ATOMIC_AGENT_BROWSER_CHANNEL), and enable the family with browser.enabled.

Navigating to a non-http(s) URL is treated as dangerous and goes through the approval gate.

Files and documents

The filesystem family is the agent’s workhorse. All of it lives under os.fs.* and friends:

• Read & inspect — os.fs.read, os.fs.list, os.fs.glob, os.fs.grep, os.fs.hash, os.fs.diff
• Change — os.fs.write, os.fs.edit, os.fs.patch, os.fs.trash
• Watch — os.fs.watch for file changes
• Documents — os.fs.read_document extracts readable text from a document file
• Archives — os.fs.archive.list, os.fs.archive.read_entry (read-only), os.fs.archive.extract (approval-gated)
• Orientation — os.fs.locate_project finds the project root for a path

ripgrep is not bundled in the normal install

os.fs.grep shells out to a rg binary it resolves in four steps: ATOMIC_AGENT_RG_PATH, a vendor/rg sidecar next to the executable (this is what the SEA build ships), a local node_modules/@vscode/ripgrep dev install, and finally plain rg on your $PATH. Only the SEA build carries a bundled binary — with a normal install you need ripgrep on your $PATH, and the error tells you so (brew install ripgrep, apt install ripgrep, or choco install ripgrep).

The agent can also pull readable text out of common document formats — PDF, DOCX, XLSX, PPTX, RTF, ODT, plain text, and archives — so it can work with documents, not just source files.

Tip

Read tools are batched in parallel. If the model wants to read five files, it issues five os.fs.read calls in one step and they run concurrently. Writes never batch with reads.

Write-family tools (os.fs.write, os.fs.edit, os.fs.patch, trashing files, extracting archives) are dangerous and require approval.

Shell, processes, and git

Shell

os.shell.run runs commands, but every command passes through a shell command guard first. The guard has a safe-allow list, hard blocks for destructive commands (like rm -rf targets and mkfs), and pattern checks for risky constructs (such as piped command chains). It always asks for approval before running.

Processes

os.proc.list inspects running processes (read-only) and os.proc.kill terminates one. Killing a process is a dangerous action and goes through the approval gate.

Git

os.git.* exposes six read-oriented git verbs — os.git.status, os.git.log, os.git.diff, os.git.show, os.git.blame, and os.git.branch. These run through the same bounded command runner with a tighter timeout than general shell commands, and all six are read-only, so they batch in parallel.

Web search and fetch

os.web.search and os.web.fetch let the agent reach the open internet. os.http.request makes raw HTTP requests. These are the agent’s explicit egress points — anything they touch leaves your machine.

The two families are gated differently. os.web.search and os.web.fetch are classed pure_read: they’re SSRF-guarded and don’t mutate anything, so they run without an approval prompt and batch in parallel. os.http.request is approval_gated — it can issue arbitrary methods and bodies, so it always asks first and runs solo.

These tools are also “wandering-prone”: if the agent fires a lot of distinct searches or fetches without making progress, the loop detector nudges it back on track and, if needed, ends the turn gracefully rather than looping forever.

Clipboard, notifications, and windows

These desktop tools let the agent interact with your environment beyond files and the browser:

• os.clipboard.read — read the system clipboard (read-only)
• os.clipboard.write — write to the system clipboard
• os.notify — send a desktop notification
• os.window.list — enumerate open windows (read-only)
• os.window.focus — bring a window to the front
• vision.describe — describe an image, when vision.enabled is on
• tool.view and skill.view — inspect a tool’s or skill’s full definition on demand

On Linux these depend on desktop utilities (for example xclip for clipboard, libnotify/notify-send for notifications, wmctrl for windows). Atomic Agent probes for them at startup and reports what’s available in its capabilities summary — so if a tool is missing on your box, the agent knows not to reach for it.

Safety and approvals

Atomic Agent splits tools into two buckets:

• Read-only (readonly: true) — safe to run anytime, no prompt. Reading files, reading a page, listing a directory.
• Dangerous (readonly: false) — must be approved. Shell commands, file writes/edits/trashing, HTTP requests, non-http(s) browser navigation, process kills, archive extraction, and skill scripts.

When the model calls a dangerous tool, execution pauses and an approval request goes to wherever you’re driving the agent — a TUI modal, a CLI y/n prompt, an HTTP webhook, or a Telegram button. The tool only runs if you approve; deny it and the agent gets a clear error and moves on.

# Normal run — dangerous tools prompt for approval
atomic-agent run

# Auto-approve everything (testing / trusted, autonomous contexts only)
atomic-agent run --no-approval

The approval ladder

How much gets asked is a five-step ladder, agent.approvalLevel, not an on/off switch. Level 1 is the default and asks about everything; each step up silences one broader category:

Level	Stops asking about
1 (default)	nothing — every gated action asks first
2	file writes, edits, and patches strictly inside the session working directory
3	file writes anywhere under your home directory, moves to Trash, archive extraction, HTTP requests
4	guarded shell commands, skill scripts, process kills
5	everything, including non-http(s) browser navigation and writes to the agent’s own trust config

--no-approval is level 5. The hardline shell-guard rules are not part of this ladder — they fire before the gate and block at every level, including 5.

Level 5 is blind trust

At agent.approvalLevel: 5 (or --no-approval) the gate is bypassed entirely — dangerous tools run without asking and without surfacing what they did. Use it for tests or fully trusted automation, never for an agent touching things you care about.

Note that writes to the config file holding agent.approvalLevel are deliberately pinned to level 5. Otherwise an agent at level 3 or 4 could rewrite its own config and silently escalate itself across a restart.

The older boolean agent.approvalRequired is still read for backwards compatibility: true maps to level 1, false to level 5. Prefer agent.approvalLevel in new configs.

A few honest limits worth stating plainly:

• The approval gate is a policy mechanism, not a sandbox. Shell commands and skill scripts run with the same permissions as the agent process.
• Approval-gated tools can’t run inside a parallel batch — they’re solo-only, so each one gets its own prompt. If the model tries to batch them, the runtime splits them out and asks the model to retry one at a time.
• Secrets in your config.json and .env are not auto-redacted. Treat your state directory as sensitive.

Resource classes (under the hood)

Internally, every tool is tagged with a resource class that governs how it’s scheduled in a batch:

Class	Example tools	Batching behavior
pure_read	os.fs.read, os.web.fetch, os.git.status	Run in parallel
fs_write	file-system writes	Serialized within the group
browser	browser.navigate, browser.read_aria	Serialized (one Playwright process)
memory_write	memory.notes.store, os.clipboard.write, os.notify	Serialized
tasks_write	tasks.schedule, tasks.cron, tasks.cancel	Serialized
vision	vision.describe	Serialized (bounds load on the vision slot)
approval_gated	os.shell.run, os.http.request, os.fs.write	Solo only
terminal	reply, finish	Runs last, alone
unknown	anything unlisted	Rejected from every batch (fail-closed)

You don’t configure this directly, but it explains why some calls fan out and others queue. Groups in different classes run concurrently with each other, so a step costs roughly the slowest group.

Two details are easy to get backwards. The mutating os.fs.* verbs (write, edit, patch, trash, archive.extract) are classed approval_gated, not fs_write — they require approval, which forbids them from batches entirely. And terminal tools (reply to end a turn, finish to end the session) always run after every other call in the step has settled.

Configuration quick reference

The tool surface is shaped by a handful of config keys (in config.json under your state directory):

Key	Effect
browser.enabled	Turn the browser family on/off
browser.channel	chrome | msedge | chromium
vision.enabled	Enable the vision.describe image tool
tasks.agentToolsEnabled	Expose the tasks.* scheduling tools to the agent
memory.notes.enabled	Register the memory.notes.* tools
agent.toolTimeoutMs	Per-tool execution timeout (default 60000)
agent.maxParallelToolCalls	Cap on parallel calls per batch
agent.approvalLevel	Approval ladder, 1–5 (default 1)

Tools for a disabled feature simply don’t appear in the registry — the model never sees them, rather than calling them and getting an error.

Where to go next

Memory

The memory.* tools and how the agent remembers across sessions. See Memory.

Skills

Package reusable playbooks and scripts the agent can run. See Skills.

MCP

Add tools from external MCP servers to the registry. See MCP.

Configuration

Full config and environment-variable reference. See Configuration.