Run verifiable engineering loops with control, alignment, and confidence.
Build agent work as explicit execution graphs with scoped context, specialized agents, structured handoffs, bounded stages, parallel branches, executable checks, evidence artifacts, review gates, and human approvals.
Build the foundations of your own software factory without turning engineering into a black box.
Get started → · How it works · What you get · FAQ · Docs
If Atomic is useful to you, star the repository ⭐
Your engineering process should be yours, not tied to any single tool, agent, or model. A harness encodes that process: how work is scoped, divided, checked, verified, and approved.
Atomic is the first verifiable coding agent runtime for building your own harness. A set of composable, verifiable harnesses can form the foundation of your software factory.
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 exeuction 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. ☠︎
- 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/atomicWith pnpm:
pnpm add -g @bastani/atomicWith Bun:
bun add -g @bastani/atomicAtomic does not require package install scripts. Add --ignore-scripts to the install command if you want to disable dependency lifecycle scripts during installation.
Atomic supports subscription login for Codex, Claude, GitHub Copilot, xAI, and Radius, as well as API-key providers such as OpenRouter:
atomic
/login # then select your providerClaude 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-...
atomicAtomic 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.
Devcontainer, terminal, and SDK references
Atomic runs in a standard devcontainer or VM with Node.js 22.19+ installed. Install it inside the container with a package manager and pass provider credentials through environment variables.
See Terminal setup, Security, and Programmatic Usage for the SDK and RPC entry points.
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.
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.
| Workflow | What it does | Example input |
|---|---|---|
fan-out-and-synthesize |
Partitions independent slices, writes branch artifacts, and synthesizes their evidence. | /workflow fan-out-and-synthesize prompt="Map payment retries by subsystem and synthesize cited findings" |
adversarial-verification |
Challenges a candidate with fresh verifiers and bounded repair. | /workflow adversarial-verification task="Verify the rate-limit migration patch" |
loop-until-done |
Iterates with a durable ledger until explicit completion evidence or bound exhaustion. | /workflow loop-until-done prompt="Repair failures until the test suite passes" |
goal |
Runs bounded autonomous implementation with a durable ledger, receipts, parallel review, and reducer-gated completion. | /workflow goal objective="Update CLI docs and validate the docs build" |
ralph |
Runs research-first delegated implementation with bounded multi-model review and repair. | /workflow ralph prompt="Implement specs/rate-limit.md" create_pr=true |
open-claude-design |
Gathers requirements and references, discovers the design system, refines output, and exports a handoff. | /workflow open-claude-design prompt="Team activity feed prototype using ./mocks/feed.png as a reference" |
| author your own | Issue-to-PR, migration, triage, release, compliance, or another process your team needs. Start with the workflow guide. | “Create a workflow that plans, implements, runs tests and lint, reviews the diff, then stops for approval.” |
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>.
| Skill | Purpose |
|---|---|
research-codebase |
Analyze a focused area and write a dated research document. |
create-spec |
Produce a technical execution spec grounded in research and engineer feedback. |
subagent |
Delegate work through single agents, chains, parallel groups, async runs, or forked context. |
intercom |
Coordinate parent, child, and peer sessions on the same machine. |
prompt-engineer |
Refine prompts, research questions, and workflow inputs. |
skill-creator |
Create, improve, and evaluate reusable skills. |
tdd |
Apply a red-green-refactor loop and testing guidance. |
tmux |
Drive and verify terminal applications. |
playwright-cli |
Automate browser interactions and end-to-end UI checks. |
liteparse |
Extract text, tables, and values from documents and images. |
impeccable |
Design, audit, and refine frontend interfaces. |
Subagents are purpose-built agents with scoped context, tools, and termination conditions. Atomic bundles nine definitions from packages/subagents/agents/.
| Subagent | Purpose |
|---|---|
worker |
Implement a bounded task and return a concise result. |
codebase-locator |
Locate files and components relevant to a task. |
codebase-analyzer |
Analyze implementation details. |
codebase-pattern-finder |
Find similar implementations and usage examples. |
codebase-online-researcher |
Fetch current documentation and authoritative web sources. |
codebase-research-locator |
Find relevant prior research in the repository. |
codebase-research-analyzer |
Extract decisions and rationale from local research. |
code-simplifier |
Refine recent code without changing behavior. |
debugger |
Reproduce, diagnose, and verify fixes for failures. |
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.
Atomic uses tools exposed through CLIs, MCP servers, APIs, scripts, or custom extensions. These examples are not a fixed integration list.
| Need | Examples | How Atomic connects |
|---|---|---|
| Code and reviews | GitHub, GitLab, Git | CLIs such as gh and glab, MCP, or web access |
| Tickets and docs | Jira, Linear, Notion, Slack | MCP servers, APIs, or custom tools |
| Build and runtime | Docker, Kubernetes, AWS, Google Cloud, Azure | Installed CLIs such as docker, kubectl, aws, gcloud, or az |
| Observability and data | Sentry, Datadog, PostgreSQL | CLIs, MCP servers, APIs, or custom tools |
| UI validation | Playwright, Chrome | Built-in skills and browser automation |
You supply the credentials and permissions. The workflow defines how agents may use the available tools.
- A coding agent runtime and terminal application.
- A context-engineering system for scoped sessions, tools, handoffs, and verifier passes.
- A TypeScript workflow SDK for explicit execution graphs, checks, artifacts, and gates.
- A model-agnostic harness for providers, MCP, subagents, skills, and extensions.
- Infrastructure that developers can inspect, version, change, and own.
- A promise that more agents improve engineering.
- A black-box swarm.
- A claim that model output is deterministic or correct by default.
- A checklist that a model may choose to follow.
- A wrapper around Claude Code, Codex, OpenCode, or Copilot CLI.
- A replacement for engineering judgment.
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.