Atomic

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

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

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

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

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 34 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. ☠︎

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

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.

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.

• Node.js 22.19 or newer — check with node --version.
• A package manager — use npm, pnpm, Yarn, or Bun. Use Bun 1.3.14+ for Bun installs or workflow-authoring examples.
• Model-provider access — use a supported subscription login or API key.

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 the install command if you want to disable dependency lifecycle scripts during installation.

Start Atomic:

atomic

Login. Atomic supports subscription login for Codex, Claude, GitHub Copilot, xAI, as well as API-key providers such as OpenRouter:

/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 "<prompt>" prints the response and exits.

After authenticating, run /atomic for workflow guides, examples, and next steps. 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.

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 workflow 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.

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.

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
Parallel review composition One command fans a real diff out to fresh-context specialists, with independent roles and live parallel tool progress. Atomic docs · Subagents Crash course · A.5 Parallel review composition
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
Background subagent runs Launch a detached specialist, keep chatting, and inspect its run status while work continues outside the parent turn. Atomic docs · Subagents Crash course · A.6 Background subagent runs
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
Runtime system-prompt mutation A live command toggles extension state, and before_agent_start rewrites the system prompt on the next turn. Atomic docs · Extensions Crash course · A.3 Runtime system-prompt mutation
Keybindings and hot reload Every TUI action is remappable in global JSON; /reload applies the map without restarting the session. Atomic docs · Keybindings Crash course · A.1 Keybindings and hot reload
Custom theme Theme the entire TUI from a project-local file and switch to it live with /theme. Atomic docs · Themes Crash course · 3.5 Custom theme

Atomic is the runtime. Workflows encode durable processes through stages, tools, prompts, checks, artifacts, gates, and approvals. Skills supply reusable expert instructions. Specialized subagents handle focused work while a parent agent or workflow controls the larger task.

Atomic is a fork of Pi, so it works with the providers, tools, MCP servers, skills, and extensions already in your Pi stack.

Workflow stage dependencies must form a directed acyclic graph. Because imperative workflow({ run }) definitions materialize topology from runtime branches, loops, and nested calls, module discovery cannot prove arbitrary acyclicity. Cyclic workflow graphs are unsupported: authored loop and repair iterations must create distinct tracked work per iteration and must never create self-edges or back-edges to ancestors. Retries within one ctx.tool(...) call remain attempts on that tool node rather than separate graph work.

issue or goal → research → plan → agent stages → artifacts → checks → review gate → final output

A stage can prompt an agent, run tools, call MCP servers, save artifacts, pass selected output forward, branch, retry, run in parallel, or pause for approval. Model output can vary. The workflow definition makes stage order, inputs, handoffs, configured checks, gates, and artifacts explicit.

Use direct chat for small, interactive work. Use a skill or bounded subagent when the parent should stay in control. Use a workflow when a delegated job needs durable stages, retries, evidence, resumability, or approval gates. Phrases such as “repeat until,” “review and fix until passing,” or “run checks until green” signal that the stop condition should be encoded and bounded.

Atomic can support:

• Engineering runs — research, plan, implement, test, review, and release.
• Debugging and migrations — reproduce, diagnose, patch, migrate in waves, and verify.
• Research and triage — gather context, fan out analysis, classify issues, and synthesize findings.
• QA, docs, and compliance — run repeatable checks with evidence and approval points.
• Custom agent products — build on Atomic's runtime, SDK, tools, and workflows.

Focused codebase research:

/skill:research-codebase how the rate limiter works in src/middleware/

Repository-wide research with durable artifacts:

/workflow fan-out-and-synthesize prompt="Partition the repository by subsystem, map every legacy auth middleware callsite, and synthesize cited migration findings"

A task-specific implementation and review loop:

Create and run a workflow that implements specs/2026-03-rate-limit.md, runs focused tests, sends the patch to fresh verifiers, and repairs findings until burst traffic returns 429 with Retry-After or the iteration bound is reached.

A reviewer-gated run with Goal:

/workflow goal objective="Update the CLI docs for --json, add one example, and validate the docs build"

A research-first implementation with Ralph:

/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate burst traffic" create_pr=true

Use Goal when a durable ledger, receipts, bounded sub-agent orchestration, and reviewer-gated completion fit the task. Use Ralph when the job benefits from prompt refinement, codebase research, delegated implementation, and iterative multi-model review. Both skip PR creation unless create_pr=true explicitly authorizes the post-approval final stage.

Atomic ships three top-level building blocks: workflows, skills, and specialized subagents.

Workflows define inputs, stages, branches, parallelism, retries, checks, artifacts, checkpoints, and human review gates. Atomic can author TypeScript workflow({...}) definitions, import reusable project or package workflows, and nest workflows with ctx.workflow(...) within a configured maxDepth.

Run /workflow list to see installed workflows and /workflow inputs <name> for input schemas. Use /workflow status <id>, /workflow connect <id>, /workflow quit <id>, and /workflow resume <id> to manage runs. Quitting pauses work so it can resume later. Runnable references live in packages/coding-agent/examples/.

Skills are reusable expert instructions and process modules. Atomic can select one from its description, or you can call it with /skill:<name>.

Subagents are purpose-built agents with scoped context, tools, and termination conditions. Atomic bundles nine definitions from packages/subagents/agents/.

Large, mixed, or growing contexts can make attention harder. Specialized agents reduce that risk through isolation, focus, tool scoping, and deliberate handoffs. Independent tasks can also run in parallel.

Full documentation lives at docs.bastani.ai. It covers the CLI and SDK, security, containerized execution, workflow authoring and monitoring, session management, configuration, troubleshooting, and provider setup.

The docs live in this repository under packages/coding-agent/docs. Open a pull request to suggest a change.

Atomic includes a coding-agent CLI. Its main product idea is the runtime around the agent session: scoped context, stages, tools, checks, artifacts, checkpoints, subagents, review gates, and human approvals.

Use any interactive coding tool that fits the job. Use Atomic when work needs an explicit process you can inspect, version, resume, and verify. Atomic connects to model providers directly rather than running those tools underneath it.

Atomic can fan work out too. The difference is not whether agents run in parallel; it is whether developers control the context, handoffs, execution graph, evidence, checks, and approval rules around that work. Parallel execution increases throughput. Assurance comes from the process you define and enforce.

The selected model can produce different output across runs. Workflow structure, stage dependencies, inputs, handoffs, configured checks, gates, and artifact paths are explicit. Deterministic reducers can apply declared approval rules to reviewer output.

Markdown helps set context, but a model still has to follow it. An Atomic workflow runs declared stages and tools, validates configured outputs, records configured artifacts, and applies defined gates.

Atomic is repo-native and focused on software engineering work: issues, research, specs, branches, diffs, tests, lint, artifacts, reviewers, approvals, and handoffs. It provides a coding-agent runtime rather than a set of generic application primitives.

Research commonly lives in research/, specs in specs/, and workflow run data in the workflow run directory. A workflow can persist plans, logs, transcripts, reviewer notes, check output, and summaries for later inspection.

Read the Workflow Playbook for practical guidance on writing objectives, constraining scope, steering long-running work, validating results, and producing engineering handoffs.

Join the Atomic Discord community for questions, help, feedback, feature ideas, and examples of what you have built.

See CONTRIBUTING.md for contribution guidelines and DEV_SETUP.md for development setup and testing.

To contribute workflows, see the atomic-workflows repository.

MIT — see LICENSE.

• Pi
• Superpowers
• Anthropic Skills
• Ralph Wiggum Method
• OpenAI Codex Cookbook
• HumanLayer
• Impeccable