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.

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)"| 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
• Change — os.fs.write, os.fs.edit, os.fs.patch, os.fs.diff
• Watch — os.fs.watch for file changes

Search is fast because it ships with a bundled ripgrep binary. If you need to point at a different one, set ATOMIC_AGENT_RG_PATH.

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 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.* lets the agent inspect and manage processes. Killing a process is a dangerous action and goes through the approval gate.

Git

os.git.* exposes read-oriented git operations (status, log, diff, show, blame, branch). These run through the same bounded command runner with a tighter timeout than general shell commands.

Web search and fetch

os.web.search and os.web.fetch let the agent reach the open internet. os.http makes raw HTTP requests. These are the agent’s explicit egress points — anything they touch leaves your machine, so os.http and non-safe os.web.fetch hosts are approval-gated.

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 from and write to the system clipboard
• os.notify — send a desktop notification
• os.window.* — query and control windows

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

—no-approval is blind trust

With --no-approval (or agent.approvalRequired: false), 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.

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, browser.read-aria	Run in parallel
fs_write	os.fs.write, os.fs.edit	Serialized
browser	browser.navigate, browser.click	Serialized
approval_gated	os.shell, os.http	Solo only
terminal	reply, finish	Runs last, alone

You don’t configure this directly, but it explains why some calls fan out and others queue. Terminal tools (reply to end a turn, finish to end the session) always run after everything else in a step.

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

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.