Atomic Agent # Atomic Agent ### A local-first AI agent that runs on your machine, with local or cloud models. Drives your browser, edits files, runs approved commands, and remembers context across sessions. Open source, running on our TurboQuant `llama.cpp` for +30-50% throughput on small local models. [![GAIA L1 · 69.8%](https://img.shields.io/badge/GAIA%20L1-69.8%25-0b63f6)](#benchmarks) [![Release](https://github.com/AtomicBot-ai/atomic-agent/actions/workflows/release.yml/badge.svg)](https://github.com/AtomicBot-ai/atomic-agent/actions/workflows/release.yml) [![Latest release](https://img.shields.io/github/v/release/AtomicBot-ai/atomic-agent?sort=semver&display_name=tag&logo=github)](https://github.com/AtomicBot-ai/atomic-agent/releases) [![Version](https://img.shields.io/github/package-json/v/AtomicBot-ai/atomic-agent?logo=npm)](package.json) [![License](https://img.shields.io/github/license/AtomicBot-ai/atomic-agent)](LICENSE) [![Node.js](https://img.shields.io/badge/node-%3E%3D25.7-339933?logo=node.js&logoColor=white)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/typescript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) ![Local first](https://img.shields.io/badge/local--first-agent-7C3AED) ![Private by default](https://img.shields.io/badge/private--by--default-local-059669) ![No per-token fees](https://img.shields.io/badge/no%20per--token%20fees-llama.cpp-111827) ![llama.cpp](https://img.shields.io/badge/llama.cpp-supported-111827) ![Tauri sidecar](https://img.shields.io/badge/Tauri-sidecar-24C8DB?logo=tauri&logoColor=white) **[Quick Install](#quick-install) · [Benchmarks](#benchmarks) · [Why Local-First](#why-local-first) · [Ways to Use It](#ways-to-use-it) · [Docs](#development)** ![atomic-agent terminal demo](assets/demo.gif)
--- A local-first AI agent that runs the control loop and all state on your machine. It drives your desktop: browse, read and edit files, run approved shell commands, inspect documents, remember context across sessions, schedule follow-ups, and call external tools over MCP. Embed it in your own apps over HTTP or a Tauri sidecar. `llama.cpp` first, so small quantized models stay useful for long, multi-step work on consumer hardware. ## Quick Install macOS / Linux: ```bash curl -fsSL https://atomicagent.io/install | sh ``` Windows (PowerShell): ```powershell irm https://atomicagent.io/install.ps1 | iex ``` The installer downloads the release archive, verifies the checksum, and installs the CLI plus support assets (`grammars/`, native prebuilds, and bundled `ripgrep`). Atomic Agent updates itself in place; after an update the TUI prompts you to restart. > [!NOTE] > Developer preview. APIs, commands, config, and behavior are still moving, so pin a release if you need a stable integration point. Current builds: macOS, Linux x64, and Windows x64. ### Run ```bash atomic-agent ``` > [!TIP] > Coming from Hermes or OpenClaw? Run `/import` in the TUI for a one-shot migration: sessions, cron jobs, and optionally your provider keys. ### Troubleshooting If something isn't working: 1. Copy your error logs and system specs. 2. Open an issue on [GitHub](https://github.com/AtomicBot-ai/atomic-agent/issues). 3. Or ask for help in our [Discord](https://discord.com/invite/Us7qXtDGw). ## 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. ![GAIA Level 1 benchmark: atomic-agent 69.8% vs Hermes 58.5%](assets/gaia-l1-benchmark.png) | 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 |
Charts (accuracy & speed) ```mermaid %%{init: {"themeVariables": {"xyChart": {"backgroundColor": "transparent", "titleColor": "#0b63f6", "plotColorPalette": "#0b63f6"}}}}%% xychart-beta title "GAIA L1 accuracy (higher is better, %)" x-axis ["Atomic Agent", "Hermes"] y-axis "Accuracy (%)" 0 --> 100 bar [69.8, 58.5] ``` ```mermaid %%{init: {"themeVariables": {"xyChart": {"backgroundColor": "transparent", "titleColor": "#0b63f6", "plotColorPalette": "#0b63f6"}}}}%% 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] ```
### Model Scaling The same loop holds up as the local model shrinks. Same GAIA L1 split, Atomic Agent alone: | Chat model | Accuracy | Avg wall / task | |---|---|---| | `qwen-3.6-35b-a3b` (UD-Q4_K_XL) | **37/53 = 69.8%** | ~217 s | | `qwen-3.5-9b` (Q4_K_M) | **28/53 = 52.8%** | ~152 s | | `gemma-4-12b` (it-qat UD-Q4_K_XL) | **24/53 = 45.3%** | ~423 s | Even a 9B model clears half of GAIA L1 through the same context-frugal loop. (Different Atomic Agent versions per row; see the write-up for provenance.) Full reproducible write-up: [`GAIA-L1-EXPERIMENT.md`](eval-agents/docs/GAIA-L1-EXPERIMENT.md) · Raw artifacts (matrices, NDJSON traces, logs): [gaia-l1-eval-2026-06-11 release](https://github.com/AtomicBot-ai/atomic-agent/releases/tag/gaia-l1-eval-2026-06-11). ## Why Local-First The control loop and all state run on your machine, not a hosted service: - **Your data never leaves.** Sessions, memory, tasks, traces, skills, browser profile, and config live under `` on disk. Nothing leaves unless you configure it to. - **No API costs.** Run quantized models locally through `llama.cpp`. Bring your own `llama-server` or let the CLI manage one. - **Nothing is hidden.** Inspect the prompt, replay trace drift, edit skills, and swap parts without waiting for a vendor. Plain local models, SQLite files, and NDJSON traces. - **Runs on your hardware.** Small quantized models run on everyday consumer GPUs and CPUs, no datacenter needed. ## Core Idea ### How the Agent Loop Works An agent is a loop: the model picks an action, something runs it, the result feeds back in, and it repeats until the job is done. The catch is cost. Every turn re-sends the growing context through the model, so a naive loop gets slower and pricier each pass, and small local models choke on it fastest. Atomic Agent keeps the loop cheap. One inference produces one JSON array of tool calls, and it runs them without re-encoding the whole world every turn: ```mermaid flowchart LR A[Prompt] --> B[Decide] B --> C[Run] C --> D[Compress] D -->|not done| A D -->|done| E[Reply] ``` 1. **Prompt:** a compact prompt goes to the local model. 2. **Decide:** the model returns one JSON array of tool calls, grammar-checked so the format is always valid. 3. **Run:** the core executes them; independent reads run in parallel, risky actions ask first. 4. **Compress:** results and state are summarized, not pasted back in full. 5. **Repeat:** loop again until reply, finish, cancel, or a max-step limit. The model chooses actions. Atomic Agent owns the loop, the state, the approvals, the traces, the stop conditions, and the failure boundaries. ### Built to Make Local Models Work We run local models on our own TurboQuant `llama.cpp` ([`AtomicBot-ai/atomic-llama-cpp-turboquant`](https://github.com/AtomicBot-ai/atomic-llama-cpp-turboquant)): - **TurboQuant KV-cache:** WHT-rotated low-bit quantization compresses the KV-cache up to ~6.4× versus F16, with a fused Metal decode kernel, so long-context sessions fit in far less memory. - **TurboQuant weights:** Lloyd-Max weight quantization with WHT rotation and fused Metal/Vulkan kernels keeps quality high while small models fit on consumer hardware. - **Custom speculative decoding:** purpose-built Gemma 4 MTP and Qwen 3.6 NextN heads reuse the loaded model (no second context, tokenizer, or model load) for +30-50% throughput. - **Curated quantized models:** hand-picked GGUF quants that keep quality high while fitting real VRAM budgets. - **Managed mode:** the CLI downloads, pins, and runs the backend and models for you, no manual `llama.cpp` setup. ### Tuned for Small Local Models Atomic Agent's prompt is engineered so a small model never wastes tokens or breaks format: - **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 instead of re-encoding the prompt every turn. - **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. ## What It Can Do Atomic Agent drives a full desktop tool surface. Dangerous actions are routed through approvals; independent read-only calls run in parallel. | Area | Capabilities | |---|---| | **Browser** | Navigate, click, type, search, manage tabs, scroll, and read compact ARIA state via `playwright-core` (Chrome / Edge / Chromium). | | **Web & HTTP** | Web search with configurable providers (Exa), fetch and extract pages (SSRF-guarded), and make arbitrary HTTP requests, separate from the browser. | | **Filesystem & shell** | Read, write, edit, patch, glob, grep, diff, watch, hash, list, archive extract, run approved shell commands, and inspect or kill processes. | | **Desktop** | Clipboard read/write, desktop notifications, and window list/focus. | | **Documents** | Extract text locally from PDF, DOC, DOCX, XLSX, PPTX, ODT, RTF, and plain text. | | **Git** | Read-only status, log, diff, show, blame, and branch inspection. | | **Memory** | Profile facts, notes with hybrid recall, links, lessons, procedures, voting, and reflection. | | **Tasks** | Durable deferred turns, cron schedules, intervals, webhooks, and agent-created reminders. | | **Skills** | View and run Markdown skill playbooks (scripts are approval-gated), install more from ClawHub. Ships with 17 starter skills (Docker, GitHub, Notion, Obsidian, PDF, and more), auto-installed on first run. | | **Vision** | Optional `vision.describe` for multimodal models with `mmproj`, kept outside the text transcript. | | **MCP** | Connect external MCP servers; their tools, resources, and prompts join the same registry. | | **Providers** | Local `llama-server` by default; OpenAI-compatible, OpenRouter-style, and AI/ML API providers when configured. | | **Telegram** | Single-user remote control with owner pairing and inline approval buttons. | ### Memory That Grows Outside the Prompt Atomic Agent's memory is not a giant chat log pasted back into the prompt. It's a local, inspectable store: durable identity, episodic notes, associations, distilled lessons, and reusable procedures. The prompt sees compact pointers, and full bodies are recalled by tool call only when the agent needs them. - **Profile facts** render into `### profile` with contextual keyword gating; facts are versioned, with queryable history. - **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. - **Dedup and eviction** merge near-duplicate memories and evict by usefulness, not age, on by default. - **Reflection** runs after turns, off the main agent slot, and writes memory without blocking the reply. ## Ways to Use It
TUI and CLI Use the CLI for simple sessions, automation, and debugging. Use the TUI for an interactive control console: approvals, logs, models, skills, tasks, memory, MCP, Telegram, and traces. ```bash 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: ```bash 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 list-embeddings atomic-agent models pull-embedding atomic-agent models use-embedding 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: ```bash export ATOMIC_AGENT_LLAMA_URL=http://127.0.0.1:8080 ./llama-server -m Qwen3.5-9B-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: ```bash 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: ```json {"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: ```json {"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: ```jsonc // /config.json { "telegram": { "enabled": true, "ownerUserId": null } } ``` ```bash # /.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. ```jsonc { "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 Everything Atomic Agent does is inspectable and interruptible: - **Approval gates:** shell, filesystem writes, patches, archive extraction, process kill, HTTP requests, skill scripts, and untrusted MCP tools are gated by policy. - **Append-only traces:** prompts, completions, tool invocations, outcomes, failure categories, votes, and lifecycle events recorded as local NDJSON. - **Prompt drift replay:** `atomic-agent trace replay ` compares current stable-prefix hashes against recorded traces. - **Failure taxonomy:** transport, grammar, model, tool, and cancellation failures classified across events, traces, metrics, TUI, sidecar, and HTTP. - **No-progress guard:** repeated identical tool calls draw a warning at 3 repeats and a hard veto at 5; after 3 consecutive vetoes the agent is forced into a graceful reply. - **Per-session FIFO:** every surface enters the same `TurnController`; one session stays ordered while different sessions run concurrently. - **Explicit state:** sessions, memory, tasks, skills, browser profile, MCP config, and traces are ordinary local files or SQLite databases. > [!IMPORTANT] > Treat traces and `/.env` as sensitive local artifacts. Secret redaction and per-tool environment filtering are not complete isolation layers. ### Privacy and Egress By default, Atomic Agent does not require a hosted agent provider. Model calls go to your configured backend, and local artifacts stay under ``. Local-first bounds where control lives, not where packets go. Network egress happens exactly when: - the browser navigates to a website; - an HTTP tool calls a requested endpoint; - a configured cloud LLM or embedding provider receives its request; - an MCP server receives a tool call you routed to it. > [!NOTE] > Skills and shell commands inherit the agent process environment, including `.env` secrets, so anything you run can itself reach the network. The promise is not magic secrecy. The promise is that the agent control plane does not need to be remote. ## Requirements & Configuration
Requirements (Node, llama-server, browser, git) + Linux notes - Node.js for development; release bundles ship as Node SEA binaries. - A reachable `llama-server`, either managed by `atomic-agent models` or launched externally. - Chrome, Microsoft Edge, or another configured Chromium-family executable. Browser binaries are not bundled. - `git` for git tools. - macOS workflows may need Accessibility, Screen Recording, Automation, or Reminders permissions. **Linux notes:** - **Desktop tools** (install via your package manager): `ripgrep` (file search; bundled binary used when present), `xclip`/`xsel` (X11) or `wl-clipboard` (Wayland) for clipboard, `libnotify-bin` for notifications, `wmctrl` for window control (X11/XWayland only), `gio` (glib2) or `trash-cli` for `fs.trash`. - **Browser:** Chromium-family sandboxing can fail under some Linux setups (containers, certain kernels). If Chrome refuses to launch, run it with `--no-sandbox`. - **GPU acceleration (managed mode):** the backend always starts and falls back to CPU when no GPU driver is available. For GPU offload install a Vulkan driver. Intel/AMD: `mesa-vulkan-drivers` (+ `vulkan-loader`/`libvulkan1`); NVIDIA: the stock proprietary driver bundles its Vulkan ICD. Device auto-selected at start; override with `atomic-agent models use-device `, inspect with `atomic-agent models devices`, or press `G` in the TUI Models tab.
Configuration and secrets (state dir, env vars, .env) User-facing configuration lives in `/config.json`. Useful environment variables: - `ATOMIC_AGENT_STATE_DIR`: state, config, skills, browser profile, memory, tasks, traces. Default: `~/.atomic-agent`. - `ATOMIC_AGENT_LLAMA_URL`: external `llama-server` URL. - `ATOMIC_AGENT_LLAMA_API_KEY`: optional bearer token for `llama-server`. - `ATOMIC_AGENT_LLAMA_MAX_TOKENS`: completion cap. - `ATOMIC_AGENT_BROWSER_CHANNEL`: `chrome`, `msedge`, or `chromium`. - `ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH`: explicit Chromium-family executable path. - `ATOMIC_AGENT_BROWSER_CDP_URL`: attach to an already-running browser via CDP. Secrets for skills and channels belong in `/.env`, not in `config.json`: ```text NOTION_API_KEY=ntn_xxxxxxxx GITHUB_TOKEN=ghp_xxxxxxxx TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token EXA_API_KEY=exa_xxxxxxxx OBSIDIAN_VAULT_PATH=/Users/me/Documents/Obsidian Vault ``` Shell-exported variables win over `.env`. The built-in parser intentionally supports only simple `KEY=VALUE` lines.
## Development ```bash npm install npm run lint npm test npm run build ``` Core docs: - [PROMPT.md](PROMPT.md): prompt anatomy - [MEMORY.md](MEMORY.md): memory and recall - [MEMORY_FABRIC_V2.md](MEMORY_FABRIC_V2.md) / [MEMORY_FABRIC_V2.5.md](MEMORY_FABRIC_V2.5.md): memory roadmap - [SKILLS.md](SKILLS.md): skill format - [BUNDLING.md](BUNDLING.md): release packaging - [AGENTS.md](AGENTS.md): contributor invariants ## Acknowledgements Built on the shoulders of giants: - [llama.cpp](https://github.com/ggml-org/llama.cpp): the local inference engine TurboQuant builds on - [Playwright](https://github.com/microsoft/playwright): browser automation the agent drives - [better-sqlite3](https://github.com/WiseLibs/better-sqlite3): embedded SQLite (FTS5) for local memory and state - [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk): external tool and resource integration - [Ink](https://github.com/vadimdemedes/ink) + [React](https://github.com/facebook/react): the terminal UI - [grammY](https://github.com/grammyjs/grammY): the Telegram channel - [pdf.js](https://github.com/mozilla/pdf.js): PDF text extraction, by Mozilla - [Tauri](https://github.com/tauri-apps/tauri): the desktop shell the agent runs inside as a sidecar