Atomic

The verifiable coding agent runtime. Build your engineering process as explicit, checkable execution graphs.

Run verifiable engineering loops with control, alignment, and confidence.

Atomic prioritizes quality over quick responses. Complex runs can take hours, days, or weeks because Atomic researches, implements, and verifies the work that quick coding-agent passes tend to leave to you.

Engineers using Atomic tell us this means less babysitting, less code review comments, and less stress. The end result is work built and verified for production review, backed by evidence instead of another round of manual prompting.

Get started →  ·  How it works  ·  What you get  ·  FAQ  ·  Docs

_{USED BY ENGINEERS AT}

                    

If Atomic is useful to you, star the repository ⭐

Users are reporting:

• ⚡ A 1–1.5 hour reduction in manual verification per task compared to traditional coding agents, not including time saved from fewer follow-up fixes and reverts
• 🔀 ~95% merge rate on Atomic-generated PRs, with reduced follow-ups and a 0% revert rate
• 🛡️ Production incidents caught that CI did not cover

Atomic Verifiable Runtime

Every row is a real Atomic session recorded from the installed product. Open the Atomic docs for reference or follow the crash course step by step.

Create a workflow in plain English Describe inputs, parallel stages, synthesis, and outputs in prose; Atomic writes and reloads the runnable TypeScript graph. Atomic docs · Workflows Crash course · A.8 Natural-language workflow authoring
Steer and control a live run Attach to a running stage, watch it stream, and steer, pause, or abort it mid-flight. Atomic docs · Workflows Crash course · 6.2 Steer and control a live run
Durability and resume Runs checkpoint as they go, so killing the process leaves them retained and resumable instead of lost. Atomic docs · Workflows Crash course · 6.5 Durability and resume
Human-in-the-loop gates Put an approval gate anywhere in the graph and the run waits for a person before it proceeds. Atomic docs · Workflows Crash course · 6.4 Human-in-the-loop gates
Planner-worker intercom coordination Separate sessions message each other over intercom to split a job and agree on the answer. Atomic docs · Intercom Crash course · 5.3 Planner-worker intercom coordination
Verification built in Executable checks and fresh reviewers produce evidence; failures route into bounded repair until the gate passes. Atomic docs · Workflows Crash course · 6.6 Security review with a repair loop

Explore 32 more Atomic capabilities ↓

Build your process as workflows with scoped context, model choice, tools, handoffs, artifacts, retries, executable checks, review gates, and human approvals.

Atomic’s primitives are built for the software engineering lifecycle. Verification is built into the execution model.

Atomic is open so you can inspect and adapt it. You own the workflow, the evidence, and the rules for completion.

Own your intelligence. Build in the open. Question the defaults. Keep control of the process. ☠︎

Works with your engineering stack

Atomic connects through installed CLIs, MCP servers, APIs, scripts, and custom extensions; you supply the credentials and permissions.

Works with your models

See provider setup and the current catalog. Availability depends on your credentials, subscription, region, and the provider catalog; one login does not unlock every provider.

Local and open models

Atomic can run tool-capable models exposed through llama.cpp, Ollama, LM Studio, vLLM, SGLang, Hugging Face, or a compatible OpenAI, Anthropic, or Google endpoint. Actual model and tool support depends on the server and model.

The model-family badges are representative open families, not a closed allowlist. See Models and llama.cpp.

Get started

Prerequisites

• Package install: Node.js 22.19 or newer plus npm, pnpm, Yarn, or Bun. Use Bun 1.4.2+ for Bun installs or workflow-authoring examples.
• Release archive install: macOS and Linux need tar and either curl or wget. Windows uses built-in PowerShell commands. This path does not need Node.js or a package manager.
• Model-provider access — use a supported subscription login or API key.

Install

Install with npm:

npm install -g @bastani/atomic

With pnpm:

pnpm add -g @bastani/atomic

With Bun:

bun add -g @bastani/atomic

Atomic does not require package install scripts. Add --ignore-scripts to a package install command if you want to disable dependency lifecycle scripts.

Alternatively, install the self-contained release archive, which needs no Node.js or package manager.

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/bastani-inc/atomic/main/install.sh | sh

On Windows, run this in PowerShell:

irm https://raw.githubusercontent.com/bastani-inc/atomic/main/install.ps1 | iex

The archive installer verifies SHA256SUMS, keeps versioned payloads, and links its launcher from ~/.local/bin/atomic on macOS/Linux or %LOCALAPPDATA%\atomic\bin\atomic.cmd on Windows, printing PATH guidance when needed. It accepts a few environment variables:

• ATOMIC_VERSION — pin an exact release tag.
• ATOMIC_FORCE_INSTALL=1 (or --force / -Force) — reinstall even when that release is already installed. By default the installer skips the download for a healthy install of the requested or latest release.
• ATOMIC_INSTALL_DIR / ATOMIC_BIN_DIR — change the install and launcher locations. On macOS/Linux, relative directories resolve against the physical directory where the installer starts.
• GITHUB_TOKEN / GH_TOKEN — optional; raises GitHub API limits on shared networks.
• NO_COLOR — plain output with no colours, progress bar, or logo; the installer also switches to plain output when its output is not a terminal or CI is set.

Authenticate and run

Start Atomic:

atomic

/login   # then select your provider

Claude login from a third-party harness uses Anthropic extra usage billed per token rather than Claude plan limits. See Providers & Models for integration details.

Missing a provider? Open an issue or contribute an integration.

For API-key setup, export the key before starting Atomic:

export OPENROUTER_API_KEY=sk-or-...
atomic

Atomic stores provider credentials in ~/.atomic/agent/auth.json and creates the file with owner-only permissions where the platform supports them. For non-interactive use, atomic -p "" prints the response and exits.

After authenticating, type a message or run /workflow list to explore built-in workflows. A fresh install also shows a one-time workflow-engine introduction.

⚠️ Atomic has no built-in sandbox or command-level shell permission gate. Tools and extensions run with your user permissions. Run autonomous work inside a devcontainer, VM, or remote development machine—not on a host with sensitive data or credentials.

Bring your skill stack

Already have agent skills? Bring them into Atomic by pointing Atomic at their existing directories or placing them in its project or user skill locations. Atomic implements the Agent Skills standard, and configured Claude Code or Codex skill directories can be used without rewriting them. See Skills.

When a skill captures a repeatable process, ask Atomic to author it as a durable workflow. Atomic inspects the skill and writes reviewable TypeScript using the custom workflow authoring guide and its examples.

Inspect the existing skill <skill-name-or-path>—including its SKILL.md, scripts, references, and assets—and consult Atomic’s workflow docs and runnable TypeScript examples; then author a reusable TypeScript workflow({...}) that preserves the skill’s intent while turning its repeatable process into durable multi-stage execution with precise typed inputs and declared outputs, artifact-backed handoffs for substantial context, explicit validation gates, and bounded retries or stop conditions where appropriate; add and run representative tests or smoke cases for the applicable success, validation-failure, and retry/stop paths, reload and verify workflow discovery, and ask me only questions whose answers materially change the design—otherwise state sensible assumptions and proceed.

Migrating from another coding agent

Atomic publishes an agent-readable llms.txt. Ask your current coding agent to:

Install and set up Atomic by following https://docs.bastani.ai/llms.txt.

More Atomic capabilities

Explore the rest of Atomic’s real recorded capabilities, with public docs and crash-course links for each one.

Launch a workflow in plain English Ask in normal chat and Atomic routes the request through its workflow tool into a real registered run - no command syntax required. Atomic docs · Workflows Crash course · W.1 Launch a workflow in plain English
Autonomous implementation loops ralph refines, researches, implements, reviews, and repairs against a bounded loop contract. Atomic docs · Workflows Crash course · A.10 Autonomous implementation loops
Inspect and control workflows List definitions, inspect input contracts, check live status, and connect to a run graph from the same /workflow surface. Atomic docs · Workflows Crash course · W.3 Inspect and control workflows
Worktree-isolated parallel work Parallel agents each get their own git worktree, so concurrent edits cannot collide. Atomic docs · Subagents Crash course · 5.2 Worktree-isolated parallel work
Escalating to a human supervisor A delegate that hits a real product decision stops, asks the human supervising the run, and waits for the answer. Atomic docs · Intercom Crash course · 5.4 Escalating to a human supervisor
Nesting builtin workflows Compose imported workflow definitions with ctx.workflow(...); child stages flatten into one inspectable parent graph. Atomic docs · Workflows Crash course · A.9 Nesting builtin workflows
Intercom context handoff Hand a task to another session with the context attached, instead of pasting it by hand. Atomic docs · Intercom Crash course · 5.5 Intercom context handoff
Delegating to bundled specialists Fan work out to scoped subagents that do the reading, so the main context stays small. Atomic docs · Subagents Crash course · 5.1 Delegating to bundled specialists
Writing your own workflow Stages, schemas, and gates are versioned TypeScript you review, not per-run improvisation. Atomic docs · Workflows Crash course · 6.3 Writing your own workflow
Touring the builtins Bundled workflows for research, planning, implementation, and review, ready before you write one. Atomic docs · Workflows Crash course · 6.1 Touring the builtins
Run a workflow with typed inputs Use /workflow <name> key=value to validate static inputs against TypeBox before a run starts. Atomic docs · Workflows Crash course · W.2 Run a workflow with typed inputs
Verbatim compaction Compaction deletes low-value transcript lines without rewriting what survives; <keepContext> pins exact text. Atomic docs · Compaction Crash course · 2.2 Verbatim compaction
Hashline edits Edits are anchored to a 4-hex snapshot tag, so a file that changed behind the model's back fails loudly instead of being overwritten. Atomic docs · Built-in tools Crash course · 1.2 Hashline edits
The agent interviews you ask_user_question replaces the editor with a structured question UI mid-task, and your answers land in the transcript as data. Atomic docs · Built-in tools Crash course · 1.3 The agent interviews you
Permission gate extension A tool_call hook catches a risky shell call before execution and asks the operator to allow or block it. Atomic docs · Extensions Crash course · A.2 Permission gate extension
Block a dangerous command A tool-call hook inspects the arguments and rejects the call before it ever reaches your shell. Atomic docs · Extensions Crash course · 3.2 Block a dangerous command
Full-screen TUI tool An extension can take over the whole screen with its own interactive component, then hand control back. Atomic docs · TUI components Crash course · 3.3 Full-screen TUI tool
Embed the agent with the SDK Drive the same agent loop from your own TypeScript program, with your own tools and your own UI. Atomic docs · SDK Crash course · 4.3 Embed the agent with the SDK
Build an extension Drop a TypeScript file into .atomic/extensions/ and the agent gains a new tool in the running session. Atomic docs · Extensions Crash course · 3.1 Build an extension
Write a skill A SKILL.md file teaches the agent a procedure it loads on demand - the same format Claude Code and Codex use. Atomic docs · Skills Crash course · 3.4 Write a skill
Local models via models.json Point Atomic at Ollama or any OpenAI-compatible endpoint by declaring it in models.json. Atomic docs · Custom models Crash course · 4.2 Local models via models.json
Headless print and JSON mode -p prints one answer and exits; --mode json streams structured events, so Atomic drops into scripts and CI. Atomic docs · JSON event stream Crash course · 4.1 Headless print and JSON mode
Branching with tree, fork, clone Fork a session at any point and try a second approach without losing the first; /tree shows the whole shape. Atomic docs · Sessions Crash course · 2.1 Branching with tree, fork, clone
Sessions are just JSONL Every session is an append-only JSONL file on disk, so you can grep it, diff it, and script against it. Atomic docs · Session format Crash course · 2.3 Sessions are just JSONL
Your first session One editor for prompts, @ file references, and ! shell commands, with steering you can type while the agent works. Atomic docs · Using Atomic Crash course · 1.1 Your first session
File-based todos Plans are durable files under .atomic/todos/: plain text you can grep, review, and commit alongside the code. Atomic docs · Built-in tools Crash course · 1.4 File-based todos
A handoff command of your own Package a repeatable handoff as a project-local slash command your whole team can run. Atomic docs · Prompt templates Crash course · 5.6 A handoff command of your own
Intercom group isolation Sessions in different groups cannot message each other; only an explicit read-only group peek crosses the boundary. Atomic docs · Intercom Crash course · A.7 Intercom group isolation
Prompt templates with arguments Project Markdown becomes a slash command with autocomplete hints and positional argument expansion. Atomic docs · Prompt templates Crash course · A.4 Prompt templates with arguments	You finished the article! Want to go deeper or explore more stories? Full Article on GitHub Trending More Tech News Reading Mode Adjust typography and theme to your preference. Typography Serif Sans Text Scale View Original Related Stories Artifacts are the new apps. Whoever manages them best wins. Dev.to 21 hours ago 🏢 Ever Fluorescent: Project Plan and Debrief Dev.to 1 day ago The Buy Button Is the Easy Part: The Hidden World of E-Commerce in 2026 Dev.to 2 days ago Should You Build an MVP Before Your First Customer? Dev.to 2 days ago Booming in Tech, Flat Everywhere Else: The Uneven Payoff of AI Dev.to 2 days ago Related Stories Artifacts are the new apps. Whoever manages them best wins. Dev.to 21 hours ago 🏢 Ever Fluorescent: Project Plan and Debrief Dev.to 1 day ago The Buy Button Is the Easy Part: The Hidden World of E-Commerce in 202... Dev.to 2 days ago Should You Build an MVP Before Your First Customer? Dev.to 2 days ago Booming in Tech, Flat Everywhere Else: The Uneven Payoff of AI Dev.to 2 days ago Chat with me