atomic-agent

A general-purpose AI agent that runs on your own machine: browser, files, shell, documents, memory, scheduled work, MCP, Telegram, and Tauri sidecars, powered by local models by default.

atomic-agent is built for real desktop work, not chat-window demos. It can browse, read and edit files, run approved commands, inspect documents, remember useful context, schedule follow-ups, drive tools through MCP, and embed into apps through HTTP or a Tauri sidecar.

The promise is simple: keep the agent control loop and state local, use llama.cpp first, and make small quantized models useful for long, multi-step desktop work on consumer hardware. Under the hood, atomic-agent is a compact local runtime for prompts, tool calls, approvals, state, traces, and failure boundaries. On the surface, it is a general-purpose AI agent you can run, inspect, interrupt, and embed.

Developer Preview / Active Development: APIs, commands, config, and behavior are still moving. Expect sharp edges, and pin a release if you need a stable integration point.

Platform availability: current releases are available for macOS and Linux x64. Windows builds are coming soon.

Benchmarks

On the public GAIA validation Level 1 split (53 tasks), atomic-agent and Hermes drove the same local qwen-3.6-35b-a3b (llama-server, UD-Q4_K_XL), with the same step budget and timeout. The only variable is the agent loop.

Metric	atomic-agent	Hermes
Accuracy	37/53 = 69.8%	31/53 = 58.5%
Avg wall / task	~217 s	~351 s
Head-to-head wins	+15 atomic-only	+9 Hermes-only

atomic-agent: +11.3 pp more accurate, ~1.6× faster per task — same hardware, same model, same budget.

Charts (accuracy & speed)

xychart-beta
    title "GAIA L1 accuracy — higher is better (%)"
    x-axis ["atomic-agent", "Hermes"]
    y-axis "Accuracy (%)" 0 --> 100
    bar [69.8, 58.5]

xychart-beta
    title "Avg wall time per task — lower is better (s)"
    x-axis ["atomic-agent", "Hermes"]
    y-axis "Seconds / task" 0 --> 400
    bar [217, 351]

Full reproducible write-up: eval-agents/docs/GAIA-L1-EXPERIMENT.md. Raw artifacts (matrices, NDJSON traces, logs): gaia-l1-eval-2026-06-11 release.

Built to Make Local Models Work

Local models need more than a prompt. They need a loop that spends context carefully, reuses cache aggressively, and keeps every step valid:

• turboquant llama.cpp — a purpose-built backend (AtomicBot-ai/atomic-llama-cpp-turboquant) shipped in managed mode and tuned for throughput on consumer machines.
• Curated quantized models — hand-picked GGUF quants that keep quality high while fitting real VRAM budgets.
• KV-cache reuse — a byte-stable prompt prefix plus slot affinity reuse the cache across steps instead of re-encoding the world every turn.
• Grammar + bounded prompts — GBNF tool-call grammar, small bounded prompt tails, and resource-aware parallel read batches keep every inference cheap and valid.

Quick Install/Update

curl -fsSL https://api.atomicbot.ai/agent-install | sh

The installer downloads the release archive, verifies the checksum, and installs the CLI plus support assets such as grammars/, native prebuilds, and bundled ripgrep.

Run

atomic-agent

Why Local-First Matters

Most agent products ask you to rent the control plane. Your files, browser context, prompts, traces, tool outputs, and usage patterns move through a hosted service, then the bill follows the token stream.

atomic-agent takes the local-first route:

• Run the agent loop locally.
• Bring your own llama-server, or let the CLI manage one.
• Keep sessions, memory, tasks, traces, skills, browser profile, and config under <stateDir>.
• Inspect the prompt, replay trace drift, edit skills, and replace parts without waiting for a vendor.
• Use cloud providers only when you deliberately configure them.

This is for people who want an AI agent they can actually own: local models, terminal UIs, SQLite files, trace logs, hackable tools, and software that can be understood all the way down.

The Core Idea

A local model can operate software if the agent loop stops wasting its context.

atomic-agent does not treat the model like an infinite planner. One inference produces one JSON array of tool calls. The agent core executes those calls, compresses the results, updates durable state, and asks the model for the next move.

user message
  -> compact prompt
  -> llama-server completion with tool-call grammar
  -> JSON array of 1..N tool calls
  -> resource-aware execution
  -> compressed results and durable state
  -> repeat until reply, finish, cancel, or max steps

The model chooses actions. atomic-agent owns the loop, the state, the approvals, the traces, and the failure boundaries.

What Makes It Different

Local-Model Native by Design

• Stable prefix: persona, rules, tools, skills, capabilities, and instructions stay byte-stable inside a session so cache_prompt and slot_id can reuse KV-cache.
• Bounded tail: conversation, memory, world state, recalled notes, lessons, procedures, and loaded skill bodies are clipped into a predictable prompt budget.
• Externalized state: sessions, memory, tasks, skills, traces, browser snapshots, and model config live outside the prompt.
• GBNF tool calls: completions are constrained into a JSON array of tool calls, including the solo case [{...}].
• Parallel read batches: independent read-only calls can run concurrently after a single inference; dangerous actions remain approval-gated.
• Compact browser view: ordinary web operation uses accessibility / ARIA snapshots instead of screenshot-heavy page dumps.

This is why small local models can stay useful across long, tool-heavy work.

A Real Desktop Tool Surface

atomic-agent can work across the local machine:

• Browser: navigate, click, type, inspect tabs, and read compact browser state through playwright-core against Chrome, Edge, or another Chromium-family browser.
• Filesystem and shell: read, write, patch, glob, grep, archive, hash, inspect processes, use clipboard, send notifications, and run approved commands.
• Documents: extract text from PDF, DOCX, DOC, XLSX, RTF, ODT, PPTX, archives, and plain text locally.
• Git: status, log, diff, show, blame, and branch inspection.
• Skills: Markdown playbooks with optional approved scripts; full skill bodies load only when needed.
• Memory: profile facts, notes, hybrid recall, links, lessons, procedures, voting, reflection, and bounded prompt rendering.
• Tasks: durable deferred turns, cron schedules, intervals, webhooks, and agent-created reminders.
• Vision: optional vision.describe for multimodal models with mmproj, kept outside the normal text transcript.
• Providers: local llama-server by default, plus OpenAI-compatible and OpenRouter-style providers for text or embeddings when configured.
• MCP: connect external MCP servers and expose their tools, resources, and prompts through the same tool registry.
• Telegram: single-user remote control with owner pairing and inline approval buttons.

Dangerous actions are routed through approvals. Read-heavy exploration stays fast.

Memory That Grows Outside the Prompt

atomic-agent memory is not a giant chat log pasted back into the prompt. It is a local, inspectable memory system: durable identity, episodic notes, associations, distilled lessons, reusable procedures, and feedback from experience.

The agent does not need to replay every old turn to benefit from experience. It can recall relevant facts, follow pointers into past notes, connect related memories, learn lessons from repeated outcomes, and keep procedure templates for familiar work:

• Profile facts render into ### profile with contextual keyword gating.
• Notes are stored in SQLite + FTS5, optionally paired with embeddings for hybrid recall.
• Links connect related memories into a bounded graph.
• Lessons distill repeated episodes into reusable principles.
• Procedures distill how-to templates without auto-executing them.
• Voting lets useful or harmful memories, lessons, procedures, and profile facts drift up or down.
• Reflection runs after turns, off the main agent slot, and writes memory without blocking the user-visible reply.

The prompt sees compact pointers, not the whole archive. Full bodies are recalled by tool call when the agent actually needs them, so memory can grow without turning every step into a token dump.

Ways to Use It

TUI And CLI

Use the CLI for simple sessions, automation, and debugging. Use the TUI when you want an interactive control console for approvals, logs, models, skills, tasks, memory, MCP, Telegram, and traces.

atomic-agent run --cwd /path/to/work
atomic-agent tui --cwd /path/to/work

atomic-agent skill list
atomic-agent task list
atomic-agent trace list --limit 10

Managed Local Models

The CLI can manage a paired llama.cpp setup for chat and embeddings:

atomic-agent models update
atomic-agent models list
atomic-agent models pull qwen-3.5-4b
atomic-agent models use qwen-3.5-4b
atomic-agent models start

atomic-agent tui --cwd /path/to/work

Managed mode downloads the backend, pulls GGUF models, selects the active model, and starts detached chat / embedding daemons when configured.

External llama-server

Already have your own llama.cpp process? Point atomic-agent at it:

export ATOMIC_AGENT_LLAMA_URL=http://127.0.0.1:8080

./llama-server -m Qwen2.5-9B-Instruct-Q4_K_M.gguf \
  --slots 4 \
  --parallel 4 \
  --port 8080 \
  --cache-reuse 256

atomic-agent tui --cwd /path/to/work

OpenAI-Compatible HTTP

Run atomic-agent as a local HTTP service:

atomic-agent serve \
  --host 127.0.0.1 \
  --port 8787 \
  --cwd /path/to/work \
  --api-key "$ATOMIC_AGENT_API_KEY"

POST /v1/chat/completions maps one request to one full macro-turn: user -> 0..N tool steps -> reply. Atomic-specific routes expose sessions, approvals, tasks, webhooks, events, traces, config, and capabilities.

Tauri Sidecar

The sidecar speaks newline-delimited JSON over stdio, making it easy to embed in desktop apps:

{"kind":"request","id":"r-1","type":"start_session","payload":{"workingDir":"/home/me"}}
{"kind":"request","id":"r-2","type":"send_message","payload":{"sessionId":"s-1","text":"Check the inbox and summarize urgent mail."}}

Events stream back as the turn runs:

{"kind":"event","id":"e-1","type":"turn_started","correlationId":"r-2","payload":{"sessionId":"s-1","turnIndex":0}}
{"kind":"event","id":"e-2","type":"tool_call_result","correlationId":"r-2","payload":{"sessionId":"s-1","stepIndex":0,"tool":"browser.read_aria","status":"ok","summary":"url: https://mail.google.com/ ..."}}
{"kind":"event","id":"e-3","type":"assistant_reply","correlationId":"r-2","payload":{"sessionId":"s-1","text":"You have 3 urgent threads."}}

Telegram Remote Control

Enable a personal Telegram bot and drive the same agent from your phone:

// <stateDir>/config.json
{
  "telegram": { "enabled": true, "ownerUserId": null }
}

# <stateDir>/.env
TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token

The TUI can store the token, start the channel, open pairing mode, and show status. Approvals arrive as inline buttons in your DM. Telegram is intentionally single-user.

MCP Client

Configure MCP servers in config.json, and their tools join the same registry as local tools. Trusted read-only servers can batch with other reads; untrusted servers default to approval-gated execution.

{
  "mcp": {
    "servers": [
      {
        "name": "docs",
        "enabled": true,
        "transport": {
          "kind": "stdio",
          "command": "npx",
          "args": ["-y", "@example/mcp-server"]
        },
        "trust": "pure_read"
      }
    ]
  }
}

The TUI MCP panel supports live add / remove without restarting the process.

Safety And Observability

Local does not mean opaque. atomic-agent is built to be inspected and interrupted.

• Approval gates: shell, filesystem writes, patches, archive extraction, process kill, HTTP requests,