atomic

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

The Linux musl archives bundle their C++ runtime libraries and run on stock Alpine without an apk add step; Android and Termux remain unsupported. See the Quickstart for path-resolution and Windows PATHEXT details.

Authenticate and run

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

Devcontainer, terminal, and SDK references

Atomic runs in a standard devcontainer or VM. Use the release-archive installer for an image without Node.js or npm, or install Node.js 22.19+ and use a package manager. Pass provider credentials through environment variables.

See Terminal setup, Security, and Programmatic Usage for the SDK and RPC entry points.

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 ``—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

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

How Atomic works

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.

Examples

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.

What you get

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

1. Workflows

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 for input schemas. Use /workflow status , /workflow connect , /workflow quit , and /workflow resume to manage runs. Quitting pauses work so it can resume later. Runnable references live in packages/coding-agent/examples/.

2. Skills

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

3. Specialized subagents

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.

Documentation

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.

FAQ

Is Atomic another coding agent?

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.

Why not use Claude Code, Codex, or OpenCode?

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.

How is Atomic different from products that fan out many agents?

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.

Is Atomic deterministic?

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.

Why not Markdown checklists or CLAUDE.md?

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.

Why not LangGraph or a generic agent framework?

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.

Where do artifacts live?

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.

Workflow playbook

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

Support & ideas

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

Contributing

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

To contribute workflows, see the atomic-workflows repository.

License

MIT — see LICENSE.

Sponsors

Thanks to Namespace for powering our CI/CD pipelines with fast macOS, Linux, and Windows runners.

Credits

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