Atomic

Turn coding agents into reliable engineering workflows. Atomic is an open-source CLI and TypeScript SDK for Claude Code, OpenCode, and GitHub Copilot CLI. Define the steps, guardrails, review gates, and execution environment your agent should follow, then run the workflow as TypeScript your whole team can review and reuse.

Build the workflow once. Run it across agents, repos, and teams — with GitHub, Azure DevOps (ADO), or Sapling.

Why Atomic

Coding agents are great inside a single session. They can inspect code, use tools, make edits, and explain their work. The trouble starts when the task is ambiguous/complex, tied to specific outcomes/exit criteria, long-running, or tied to a large codebase: you end up reminding the agent of the process, moving output between sessions, checking whether it followed the right steps, and deciding when a human needs to review the work. Atomic turns that process into code. A workflow can branch, retry, run stages in parallel, isolate sessions, pass only the right transcript forward, pause for human approval, and run inside a devcontainer so the agent is not loose on your host machine.

• Start with your own process. Automate the repetitive parts of research, product feedback, debugging, review, migrations, or PR prep. One TypeScript file, versioned with the repo.
• Scale to your team. Encode review gates, quality checks, and approvals so every teammate runs the same workflow instead of manually steering an agent.
• Keep the coding agent. Atomic adds structure around Claude Code, OpenCode, and Copilot CLI without rebuilding their file editing, tool use, MCP setup, hooks, or context handling from scratch.
• Use natural language to get started. Ask the workflow-creator skill to turn a workflow description into defineWorkflow() code, or let an agent use the skill when a complex task needs a repeatable workflow.
• Control the outer loop. Instead of trusting a black-box harness to improvise process, Atomic makes the orchestration inspectable: the agent stil uses it's harness with its native tools and context management, but the workflow, gates, handoffs, and execution graph are TypeScript you can read, edit, and version. This allows you to enhance your existing coding agent's capabilities.

Quick Start

Install, generate context, try Ralph, then write your own workflow — four steps, a few minutes. Steps 1–3 are the CLI path (pre-built autonomous behaviour). Step 4 is the SDK path (your own workflows). Skip straight to step 4 if you only want the library.

Prerequisites

Atomic doesn't replace your coding agent or terminal — it gives them a workflow to follow. Three things have to exist on the host before a workflow can run:

• Bun as the JavaScript runtime — Atomic and the SDK ship source that relies on Bun.spawn, native pty handling, and Bun-specific module resolution. They do not run on Node.js. The bootstrap installer below installs Bun for you; if you install @bastani/atomic manually, install Bun first.
• A terminal multiplexer — every stage runs inside a detachable session on a dedicated atomic socket (your personal tmux is untouched). That's how workflows survive terminal disconnects, how -d/--detach puts a run in the background, and how atomic session connect reattaches later from any shell.
  • macOS / Linux: tmux — brew install tmux or your distro's package manager
  • Windows: psmux — a PowerShell-native tmux-compatible shim, detected as psmux / pmux / tmux on PATH
• At least one coding agent installed and logged in — Atomic spawns the agent's own CLI at each stage and talks to it via its SDK, so the CLI has to be present and authenticated:
  • Claude Code — run claude and authenticate
  • OpenCode — run opencode and authenticate
  • GitHub Copilot CLI — run copilot and authenticate
• Windows only: PowerShell 7+ (install guide)

The bootstrap installer below installs Bun and Atomic but does not install tmux/psmux or the coding agents. Install those separately before running any workflow — bun run src/claude-worker.ts will fail loudly at stage spawn if either is missing. Using a devcontainer short-circuits all of this: the atomic feature bundles Bun + tmux + the agent CLI into the container image.

1. Install — CLI + SDK share the same package

@bastani/atomic ships both surfaces. A global install gives you the atomic CLI; a project-local install gives you the SDK import. Most users do both, but either stands alone.

CLI path — bootstrap script installs Bun, the atomic binary, and shell completions in one step:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash

# Windows (PowerShell 7+)
irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex

Upgrade later with bun update -g @bastani/atomic.

SDK-only path — if you only want to defineWorkflow(...) in your own TypeScript project and never need the atomic binary, skip the bootstrap and just add the library:

bun init -y                                      # new project
bun add @bastani/atomic                          # the SDK
bun add @anthropic-ai/claude-agent-sdk           # the provider SDK you target

Skip steps 2–3 below (those use the CLI) and jump straight to step 4. You'll still need tmux/psmux + an authenticated agent CLI at runtime — see Prerequisites.

bun install -g @bastani/atomic

# macOS / Linux
GITHUB_TOKEN=ghp_... curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash

# Windows PowerShell
$env:GITHUB_TOKEN='ghp_...'; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex

{
  "image": "mcr.microsoft.com/devcontainers/rust:latest",
  "features": {
    "ghcr.io/devcontainers/features/common-utils": {},
    "ghcr.io/flora131/atomic/claude:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "remoteEnv": {
    "GH_TOKEN": "${localEnv:GH_TOKEN}",
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  }
}

atomic uninstall
bun uninstall -g @bastani/atomic-workflows
rm -rf ~/.atomic ~/.copilot/skills ~/.opencode/skills
bun install -g @bastani/atomic

2. Generate context files — CLI

atomic chat -a <claude|opencode|copilot>

Then type /init. Atomic explores your codebase with sub-agents and writes CLAUDE.md / AGENTS.md so every future session starts with the right context.

3. Try Ralph — CLI (autonomous coding)

Ralph plans, implements, reviews, and debugs a task on its own — up to 10 iterations, exiting after 2 consecutive clean reviews.

atomic workflow -n ralph -a claude "Build a REST API for user management"

⚠️ Workflows run with agent permission checks disabled so pipelines don't block on prompts. Run them in a devcontainer or git worktree, not on your host. See Security.

4. Build your own workflow — SDK

Every team has a process — code review, CI checks, PR creation, approval, merge. Encode it as TypeScript once; everyone runs the same pipeline.

bun init && bun add @bastani/atomic

Author the workflow in src/workflows/review-to-merge/claude.ts:

import { defineWorkflow } from "@bastani/atomic/workflows";

export default defineWorkflow({
  name: "review-to-merge",
  description: "Review → CI → PR → Notify → Approve → Merge",
}).for("claude")
  .run(async (ctx) => {
    // 1. Review
    const review = await ctx.stage({ name: "review" }, {}, {}, async (s) => {
      await s.session.query("Review uncommitted changes for correctness, security, style.");
      s.save(s.sessionId);
    });

    // 2. Run security + CI in parallel
    await Promise.all([
      ctx.stage({ name: "security-scan" }, {}, {}, async (s) => {
        await s.session.query("Run `bun audit` and scan for leaked secrets.");
        s.save(s.sessionId);
      }),
      ctx.stage({ name: "ci-checks" }, {}, {}, async (s) => {
        await s.session.query("Run `bun lint` and `bun test`. Report failures.");
        s.save(s.sessionId);
      }),
    ]);

    // 3. Open PR, then notify Slack + wait for human approval
    await ctx.stage({ name: "notify-and-merge" }, {}, {}, async (s) => {
      const t = await s.transcript(review);
      await s.session.query(`Read ${t.path}. Open a PR summarizing the changes.`);

      await fetch("https://slack.com/api/chat.postMessage", {
        method: "POST",
        headers: { Authorization: `Bearer ${process.env.SLACK_TOKEN}` },
        body: JSON.stringify({ channel: "#code-review", text: "PR ready — please approve." }),
      });

      // Human-in-the-loop: pauses until the user responds
      await s.session.query(
        "Ask the user to confirm approval, then merge with `gh pr merge --squash`.",
        { allowedTools: ["Bash", "Read", "AskUserQuestion"] },
      );
      s.save(s.sessionId);
    });
  })
  .compile();

Wire it to a CLI in src/claude-worker.ts. The SDK ships pure
primitives — no wrapper to opt into. Compose with your CLI library of
choice (Commander, citty, yargs, …) and call runWorkflow. Catch the
SDK's typed errors (MissingDependencyError, SessionNotFoundError,
…) for friendly CLI output:

import { Command } from "@commander-js/extra-typings";
import {
  getInputSchema,
  runWorkflow,
  MissingDependencyError,
} from "@bastani/atomic/workflows";
import workflow from "./workflows/review-to-merge/claude.ts";

const program = new Command();
for (const input of getInputSchema(workflow)) {
  program.option(`--${input.name} <value>`, input.description ?? "");
}
program.action(async (rawOpts) => {
  try {
    await runWorkflow({ workflow, inputs: rawOpts as Record<string, string> });
  } catch (err) {
    if (err instanceof MissingDependencyError) {
      console.error(`Missing dependency: ${err.dependency}. Install it and retry.`);
      process.exit(1);
    }
    throw err;
  }
});
await program.parseAsync();

Run it:

bun run src/claude-worker.ts --target_branch=main

That's the full shape — one workflow file, one composition root. The
SDK exposes primitives (runWorkflow, getInputSchema, listWorkflows,
getName, getAgent, validateInputs, listSessions, …) and the
developer composes them into whatever CLI shape they prefer. See
Workflow SDK for
parallel stages, input schemas, headless stages, and the full API
reference.

Managing sessions

Every chat and workflow runs inside an isolated tmux session on a dedicated socket (your personal tmux is untouched). If your terminal disconnects, your session keeps running — reconnect anytime.

atomic session list              # all sessions
atomic session connect           # interactive fuzzy picker
atomic session connect <name>    # by name
atomic session kill <name>       # kill one (or all, with confirmation)

Session names follow atomic-chat-<id> or atomic-wf-<workflow>-<id>. Scope with atomic chat session … or atomic workflow session ….

Need a workflow to run in the background while you do something else? Pass -d / --detach:

atomic workflow -n ralph -a claude -d "build the auth module"   # returns immediately
atomic workflow session connect atomic-wf-claude-ralph-<id>      # attach later

Detached mode is what you want for scripted / CI automation and long-running tasks — the workflow keeps running on the atomic tmux socket regardless of your terminal.

Two surfaces: CLI and SDK

Atomic ships two things that share one workflow runtime. You can use either on its own or both together:

Both surfaces call the same runtime underneath (tmux/psmux session graph, provider SDKs, detach/reattach) — they're two entry points, not two products. Neither depends on the other: you can bun add @bastani/atomic in a project without ever installing the global binary, and you can use atomic chat and the built-in workflows without writing any TypeScript.

Example use cases

These are workflows you'd author with defineWorkflow and run from your own src/<agent>-worker.ts — see step 4 of Quick Start for the three-line entrypoint. Atomic ships three built-in workflows (ralph, deep-research-codebase, open-claude-design); everything else is yours to define.

• Review-to-merge pipeline. Review code, run CI in parallel, open a PR, notify Slack, wait for approval, merge.
• Support ticket to draft PR. Reproduce the issue, find the root cause, try a fix in a sandbox, run tests, pause for review.
• Production alert investigation. Pull the failing trace, inspect recent commits, rank likely causes, then draft a fix or page the on-call with evidence.
• Parallel UX testing. Run many persona-specific agents against the same feature, aggregate structured feedback, and turn selected issues into tasks.
• Large migration or refactor. Research the codebase, split the work into safe batches, run implementation and review passes, and keep artifacts for later runs.

Table of Contents

• Atomic
  • Why Atomic
  • Quick Start
    • Prerequisites
    • 1. Install — CLI + SDK share the same package
    • 2. Generate context files — CLI
    • 3. Try Ralph — CLI (autonomous coding)
    • 4. Build your own workflow — SDK
    • Managing sessions
  • Two surfaces: CLI and SDK
  • Example use cases
  • Table of Contents
  • Security: Workflow Permissions Model
  • Core Features
    • Multi-Agent Support
    • Workflow SDK — Build Reliable Engineering Workflows
      • Runnable examples shipped with the repo
      • Builder API
      • WorkflowContext (ctx) — top-level workflow context
      • SessionContext (s) — inside each session callback
      • Session Options (SessionRunOptions)
      • Saving Transcripts
      • Per-Agent Session APIs
      • Key Rules
    • Research Codebase
    • Autonomous Execution (Ralph)
    • Deep Research Codebase
    • Containerized Execution
    • Specialized Sub-Agents
    • Built-in Skills
    • Workflow Panel
  • Commands Reference
    • CLI Commands
      • Global Flags
      • atomic session Subcommands
      • atomic chat Flags
      • atomic workflow Flags
      • atomic completions — Shell Completions
    • Atomic-Provided Skills (invokable from any agent chat)
  • Building your own atomic-powered app
    • Primitives, not a wrapper
    • Programmatic invocation
    • Embedding under a parent CLI — runWorkflow inside any Commander tree
    • WorkflowPicker component
    • Registry rules
    • Input precedence
    • Builtin workflows via the atomic CLI
    • Migration from 0.x (directory-scanning) and the createWorkflowCli wrapper
  • Configuration
    • .atomic/settings.json
    • Agent-Specific Files
  • Updating & Uninstalling
    • Update
    • Uninstall
  • Troubleshooting
  • FAQ
  • Contributing
  • License
  • Credits

Security: Workflow Permissions Model

[!CAUTION]
Atomic workflows run coding agents with all permission checks disabled. The agent can read, write, and delete files, execute arbitrary shell commands, and make network requests without prompting. This is required for unattended pipelines. Run workflows in a devcontainer, not on your host machine.

Defaults live in src/services/config/definitions.ts and src/sdk/runtime/executor.ts. Override per-project via ProviderOverrides in .atomic/settings.json — chatFlags replaces defaults entirely; envVars are merged.

Core Features

Multi-Agent Support

Atomic works across three production coding agents — switch with a flag and your workflows, skills, and sub-agents carry over.

Each agent gets its own configuration directory (.claude/, .opencode/, .github/), skills, and context files — all managed by Atomic.

Workflow SDK — Build Reliable Engineering Workflows

The Workflow SDK (@bastani/atomic/workflows) lets you encode your team's process as TypeScript — spawn agent sessions dynamically with native control flow (for, if, Promise.all()), pass state explicitly, and watch each stage appear in a live graph as it runs.

Set up a workflow project (bun init && bun add @bastani/atomic), define your workflow with defineWorkflow, then call runWorkflow({ workflow, inputs }) from inside whatever CLI library you prefer (Commander, citty, yargs, an OpenTUI app, …). The SDK ships pure primitives — no opinionated wrapper:

bun run src/claude-worker.ts --prompt="describe this project"

See step 4 of Quick Start for a complete review-to-merge example. More examples and the full API reference below.

Runnable examples shipped with the repo

The examples/ directory contains small, complete user apps you can run directly. Most subdirectories ship claude/, copilot/, and opencode/ variants plus one agent-scoped worker file per agent — claude-worker.ts, copilot-worker.ts, opencode-worker.ts — each a small Commander entrypoint that calls runWorkflow({ workflow, inputs }). multi-workflow/ and commander-embed/ use a single cli.ts instead, to demonstrate multi-workflow dispatch and Commander embedding respectively.

Design principle — when does -a/--agent belong on your CLI? Each agent-scoped worker file imports a single workflow pinned to one agent (import workflow from "./claude/index.ts"), so there's nothing to disambiguate — no -a flag. Only reach for -a/--agent when one CLI dispatches across workflows that exist in multiple agent variants — e.g. a cli.ts that registers hello for claude and copilot. The atomic CLI itself uses -a for exactly that reason: its builtin registry has cross-agent variants of ralph, deep-research-codebase, and open-claude-design.

Run any of them with:

# Single-workflow workers — agent is pinned by which file you run, so no `-a` flag.
# Inputs map to `--<input>=<value>` flags; if the workflow declares no inputs,
# trailing positional tokens become the prompt.
bun run examples/hello-world/claude-worker.ts --greeting="Hello" --style=casual
bun run examples/sequential-describe-summarize/claude-worker.ts --topic="Bun"
bun run examples/review-fix-loop/claude-worker.ts --topic="adopting Bun" --max_iterations=3
bun run examples/headless-test/copilot-worker.ts --prompt="TypeScript"

# Multi-workflow CLI — one cli.ts, one Commander subcommand per registered workflow.
bun run examples/multi-workflow/cli.ts hello   --who=Alex
bun run examples/multi-workflow/cli.ts goodbye --tone=melodramatic

# Commander embedding — atomic workflow mounted as `greet` alongside plain Commander commands.
bun run examples/commander-embed/cli.ts greet --who=Alex
bun run examples/commander-embed/cli.ts status                # sibling Commander command
bun run examples/commander-embed/cli.ts --help                # all commands

Copy an example directory into your project as a starting point — swap the workflow import in each <agent>-worker.ts (or in cli.ts for the multi-workflow / commander-embed shapes) for your own definition and you're done.

import { defineWorkflow } from "@bastani/atomic/workflows";

export default defineWorkflow({
  name: "my-workflow",
  description: "Two-session pipeline: describe -> summarize",
  inputs: [{ name: "prompt", type: "text", required: true, description: "task prompt" }],
}).for("claude")
  .run(async (ctx) => {
    const prompt = ctx.inputs.prompt ?? "";

    const describe = await ctx.stage(
      { name: "describe", description: "Ask Claude to describe the project" },
      {}, {},
      async (s) => {
        await s.session.query(prompt);
        s.save(s.sessionId);
      },
    );

    await ctx.stage(
      { name: "summarize", description: "Summarize the previous session's output" },
      {}, {},
      async (s) => {
        const research = await s.transcript(describe);
        await s.session.query(`Read ${research.path} and summarize in 2-3 bullets.`);
        s.save(s.sessionId);
      },
    );
  })
  .compile();

import { defineWorkflow } from "@bastani/atomic/workflows";

export default defineWorkflow({
  name: "parallel-demo",
  description: "describe -> [summarize-a, summarize-b] -> merge",
  inputs: [{ name: "prompt", type: "text", required: true, description: "task prompt" }],
}).for("claude")
  .run(async (ctx) => {
    const prompt = ctx.inputs.prompt ?? "";

    const describe = await ctx.stage({ name: "describe" }, {}, {}, async (s) => {
      await s.session.query(prompt);
      s.save(s.sessionId);
    });

    const [summarizeA, summarizeB] = await Promise.all([
      ctx.stage({ name: "summarize-a" }, {}, {}, async (s) => {
        const research = await s.transcript(describe);
        await s.session.query(`Read ${research.path} and summarize in 2-3 bullets.`);
        s.save(s.sessionId);
      }),
      ctx.stage({ name: "summarize-b" }, {}, {}, async (s) => {
        const research = await s.transcript(describe);
        await s.session.query(`Read ${research.path} and summarize in one sentence.`);
        s.save(s.sessionId);
      }),
    ]);

    await ctx.stage({ name: "merge" }, {}, {}, async (s) => {
      const bullets = await s.transcript(summarizeA);
      const oneliner = await s.transcript(summarizeB);
      await s.session.query(
        `Combine:\n\n## Bullets\n${bullets.content}\n\n## One-liner\n${oneliner.content}`,
      );
      s.save(s.sessionId);
    });
  })
  .compile();

import { defineWorkflow } from "@bastani/atomic/workflows";

export default defineWorkflow({
  name: "gen-spec",
  description: "Convert a research doc into an execution spec",
  inputs: [
    {
      name: "research_doc",
      type: "string",
      required: true,
      description: "path to the research doc",
      placeholder: "research/docs/2026-04-11-auth.md",
    },
    {
      name: "focus",
      type: "enum",
      required: true,
      description: "how aggressively to scope the spec",
      values: ["minimal", "standard", "exhaustive"],
      default: "standard",
    },
    {
      name: "notes",
      type: "text",
      description: "extra guidance for the spec writer (optional)",
    },
  ],
}).for("claude")
  .run(async (ctx) => {
    const { research_doc, focus } = ctx.inputs;
    const notes = ctx.inputs.notes ?? "";

    await ctx.stage({ name: "write-spec" }, {}, {}, async (s) => {
      await s.session.query(
        `Read ${research_doc} and produce a ${focus} spec.` +
          (notes ? `\n\nExtra guidance:\n${notes}` : ""),
      );
      s.save(s.sessionId);
    });
  })
  .compile();

# Scriptable; CI-friendly
bun run src/claude-worker.ts \
  --research_doc=research/docs/2026-04-11-auth.md \
  --focus=standard

import { defineWorkflow, extractAssistantText } from "@bastani/atomic/workflows";

export default defineWorkflow({
  name: "headless-demo",
  description: "seed -> [3 headless background] -> merge",
  inputs: [{ name: "prompt", type: "text", required: true, description: "task prompt" }],
}).for("claude")
  .run(async (ctx) => {
    const prompt = ctx.inputs.prompt ?? "";

    const seed = await ctx.stage(
      { name: "seed", description: "Generate overview" }, {}, {},
      async (s) => {
        const result = await s.session.query(prompt);
        s.save(s.sessionId);
        return extractAssistantText(result, 0);
      },
    );

    const [pros, cons, uses] = await Promise.all([
      ctx.stage({ name: "pros", headless: true }, {}, {}, async (s) => {
        const r = await s.session.query(`List 3 pros:\n\n${seed.result}`);
        s.save(s.sessionId);
        return extractAssistantText(r, 0);
      }),
      ctx.stage({ name: "cons", headless: true }, {}, {}, async (s) => {
        const r = await s.session.query(`List 3 cons:\n\n${seed.result}`);
        s.save(s.sessionId);
        return extractAssistantText(r, 0);
      }),
      ctx.stage({ name: "uses", headless: true }, {}, {}, async (s) => {
        const r = await s.session.query(`List 3 use cases:\n\n${seed.result}`);
        s.save(s.sessionId);
        return extractAssistantText(r, 0);
      }),
    ]);

    await ctx.stage(
      { name: "merge", description: "Combine results" }, {}, {},
      async (s) => {
        await s.session.query(
          `Combine:\n\n## Pros\n${pros.result}\n\n## Cons\n${cons.result}\n\n## Uses\n${uses.result}`,
        );
        s.save(s.sessionId);
      },
    );
  })
  .compile();

Key capabilities:

Deterministic execution guarantees:

Workflows are deterministic by design — the same definition produces the same execution order with the same data flow, anywhere.

• Strict step ordering — Step 2 never starts until Step 1 finishes. Parallel sessions complete (or fail fast) before the next step begins.
• Frozen definitions — .compile() freezes the workflow. Once compiled, step order, session names, and the execution graph are immutable.
• Controlled transcript access — Sessions only read transcripts from completed upstream sessions; parallel siblings can't read each other.
• Isolated context windows — Each session runs in its own tmux pane with a fresh context. Data flows only through explicit ctx.transcript() / ctx.getMessages() calls.
• Persisted artifacts — Every session writes messages, transcript, and metadata to disk — a complete, inspectable execution record.

Variance comes from the LLM's responses, not from a changing workflow.

Ask Atomic to build workflows for you: Use your workflow-creator skill to create a workflow that plans, implements, and reviews a feature.

Research Codebase

The /research-codebase command dispatches specialized sub-agents in parallel to analyze your codebase — understand auth flows, trace root causes, query docs, and hit external sources via DeepWiki MCP. Get up to speed on a new project in minutes instead of hours.

Run parallel research sessions to compare approaches:

# Terminal 1: LangChain approach
atomic chat -a claude "/research-codebase Research GraphRAG using LangChain's graph retrieval."

# Terminal 2: Microsoft GraphRAG
atomic chat -a claude "/research-codebase Research GraphRAG using microsoft/graphrag."

# Terminal 3: LlamaIndex approach
atomic chat -a claude "/research-codebase Research GraphRAG using LlamaIndex's property graph."

Then run /create-spec on each output, spin up git worktrees, and run atomic workflow -n ralph -a <agent> in each — wake up to three complete implementations on separate branches. Research persists in research/ and specs in specs/, so every investigation compounds into future context.

Autonomous Execution (Ralph)

The Ralph Method enables multi-hour autonomous coding sessions. Approve your spec, let Ralph work in the background, focus on other things.

How Ralph works:

1. Task Decomposition — A planner sub-agent breaks your spec into a task list with dependency tracking, stored in SQLite (WAL mode for parallel access).
2. Execution — An orchestrator retrieves the task list, validates the dependency graph, and dispatches worker sub-agents for ready tasks.
3. Review & Debug — A reviewer audits the implementation with structured JSON output; if P0–P2 findings exist, a debugger investigates root causes and feeds back to the planner on the next iteration.

Loop config: Up to 10 iterations. Exits early after 2 consecutive clean reviews (zero actionable findings). P3 (minor) findings are non-actionable.

# From a prompt
atomic workflow -n ralph -a <claude|opencode|copilot> "Build a REST API for user management"

# From a spec file
atomic workflow -n ralph -a claude "specs/YYYY-MM-DD-my-feature.md"

Best practice: run Ralph in a git worktree so autonomous changes stay isolated from your working tree:

git worktree add ../my-project-ralph feature-branch
cd ../my-project-ralph
atomic workflow -n ralph -a claude "Build the auth module"

Deep Research Codebase

Atomic ships a deep-research-codebase workflow that performs multi-agent parallel research across your codebase — a full pipeline, not a single-shot command.

1. Scout — One agent scans the codebase structure and writes an architectural orientation.
2. History — A parallel agent surfaces prior research from research/docs/.
3. Explorers — Multiple parallel agents (count scaled by LOC) each investigate a partition.
4. Aggregator — A final agent synthesizes all explorer reports + history into a dated research doc at research/docs/YYYY-MM-DD-<slug>.md.

atomic workflow -n deep-research-codebase -a claude "How does the authentication system work?"

The output is a permanent research artifact that future runs, specs, and workflows can reference.

Containerized Execution

Atomic ships as devcontainer features that bundle the CLI, agent, and all dependencies into isolated containers — the recommended way to run autonomous agents safely.

Why containerize?

• Agents run rm, git reset --hard, and arbitrary shell commands — containers limit blast radius
• Reproducible environments across team members and CI
• Pre-installed dependencies: bun, playwright-cli, agent CLI, GitHub CLI
• Features versioned in sync with Atomic releases

See Quick Start → Devcontainer for a working .devcontainer.json and the .devcontainer/ directory for per-agent templates.

Specialized Sub-Agents

Atomic dispatches purpose-built sub-agents, each with scoped context, tools, and termination conditions:

Use /agents in any chat session to see all available sub-agents.

Built-in Skills

Skills are structured capability modules that give agents best practices and reusable workflows. Atomic ships 57 skills across eight categories; each lives at .agents/skills/<name>/SKILL.md and is auto-invoked when the agent detects a relevant trigger.

Skills are auto-invoked when relevant. Run ls .agents/skills/ for the complete, current list on disk.

Workflow Panel

During atomic workflow execution, Atomic renders a live workflow panel built on OpenTUI over the workflow's tmux session graph. It shows:

• Session graph — Nodes per .stage() with status (pending / running / completed / failed) and edges for sequential / parallel dependencies
• Task list tracking — Ralph's decomposed task list with dependency arrows, updated in real time
• Pane previews — Thumbnail of each tmux pane so you can see every agent without context-switching
• Transcript passing visibility — Highlights s.save() / s.transcript() handoffs as they happen

During atomic chat, there is no Atomic-owned TUI — atomic chat -a <agent> spawns the native agent CLI inside a tmux session, so chat features (streaming, @ mentions, /slash-commands, model selection, theme, keyboard shortcuts) come from the agent CLI itself. Atomic handles config sync, tmux session management, and argument passthrough.

Commands Reference

CLI Commands

Global Flags

atomic session Subcommands

Available at three levels — scoped or global:

list, connect, and kill accept -a <agent> (repeatable) to filter by agent. kill prompts for confirmation.

atomic session list                      # all sessions
atomic session list -a claude            # only Claude sessions
atomic session connect my-session        # attach by name
atomic session connect                   # interactive picker
atomic chat session list -a copilot      # chat sessions for Copilot only
atomic session kill my-session           # kill one session by name
atomic session kill                      # kill all sessions (with confirmation)
atomic workflow session kill -a claude   # kill all Claude workflow sessions

atomic chat Flags

All other arguments are forwarded directly to the native agent CLI:

atomic chat -a claude "fix the bug"          # initial prompt
atomic chat -a copilot --model gpt-5.4       # custom model
atomic chat -a claude --verbose              # forward --verbose to claude

atomic workflow Flags

Five invocation shapes:

# 1. List every workflow available, grouped by source
atomic workflow list
atomic workflow list -a claude       # filter by agent

# 2. Launch the interactive picker (no -n) — fuzzy-search, fill the form, confirm with y/n
atomic workflow -a claude

# 3. Run with a positional prompt (workflow must declare a "prompt" input)
atomic workflow -n ralph -a claude "build a REST API for user management"

# 4. Run a structured-input workflow with one --<field> flag per declared input
atomic workflow -n open-claude-design -a claude \
  --prompt="a dashboard for monitoring API latency" \
  --output-type=prototype

# 5. Run detached — workflow runs in the background; prints the session name
#    and returns immediately. Attach any time with `atomic workflow session connect`.
atomic workflow -n ralph -a claude -d "build a REST API for user management"

Workflows that declare inputs: WorkflowInput[] get CLI flag validation for free. Builtin workflows (e.g. ralph) are reserved — a local/global workflow with the same name will not shadow a builtin.

atomic completions — Shell Completions

Atomic ships tab-completion for bash, zsh, fish, and PowerShell. Cache the script once so new shells don't re-spawn the atomic binary on startup.

mkdir -p ~/.atomic/completions
atomic completions bash > ~/.atomic/completions/atomic.bash
echo '[ -f "$HOME/.atomic/completions/atomic.bash" ] && source "$HOME/.atomic/completions/atomic.bash"' >> ~/.bashrc

mkdir -p ~/.atomic/completions
atomic completions zsh > ~/.atomic/completions/atomic.zsh
echo '[ -f "$HOME/.atomic/completions/atomic.zsh" ] && source "$HOME/.atomic/completions/atomic.zsh"' >> ~/.zshrc

atomic completions fish > ~/.config/fish/completions/atomic.fish

$cache = Join-Path $HOME '.atomic\completions\atomic.ps1'
New-Item -ItemType Directory -Force -Path (Split-Path $cache) | Out-Null
atomic completions powershell | Out-File -FilePath $cache -Encoding utf8
Add-Content $PROFILE "`nif (Test-Path `"$cache`") { . `"$cache`" }"

The bootstrap installer (install.sh / install.ps1) sets this up automatically and migrates older eval "$(atomic completions …)" snippets to the cached form.

Atomic-Provided Skills (invokable from any agent chat)

Atomic ships skills — not slash commands. Skills are auto-discovered by Claude Code, OpenCode, and Copilot CLI, invoked by typing /<skill-name> (Claude Code) or by natural-language reference (OpenCode / Copilot CLI).

Native slash commands (/help, /clear, /compact, /model, /theme, /agents, /mcp, /exit) come from the underlying agent CLI, not Atomic.

Building your own atomic-powered app

@bastani/atomic/workflows is a library, not just a CLI. Use it directly to build your own TypeScript app that runs your team's workflows.

SDK-only users: you don't need the global atomic binary, but you still need the runtime prerequisites — Bun (the SDK does not run on Node.js), a terminal multiplexer (tmux on macOS/Linux, psmux on Windows), and at least one authenticated coding agent CLI (claude, opencode, or copilot). See Prerequisites for the "why" and install commands. The SDK spawns the agent CLI at each stage and wraps it in a detachable multiplexer session.

Session management primitives. The SDK exposes listSessions, getSession, stopSession, attachSession, detachSession, getSessionStatus, getSessionTranscript, plus pane-navigation verbs nextWindow / previousWindow / gotoOrchestrator — wire them into your CLI's session list, status, etc. subcommands as you see fit. Sessions live on the shared atomic tmux socket, so a worker CLI built on the primitives, the global atomic binary, and bunx atomic all see the same runtime state.

Typed errors. Every error path the SDK throws — missing tmux/psmux/bun, unknown session id, missing .compile(), invalid workflow file, minSDKVersion mismatch — is a typed class (MissingDependencyError, SessionNotFoundError, WorkflowNotCompiledError, InvalidWorkflowError, IncompatibleSDKError). Catch them with instanceof to render friendly CLI output without parsing message text. See examples/pane-navigation/cli.ts for a worked example.

Primitives, not a wrapper

The SDK ships pure functions you compose into whatever CLI shape you want:

Single workflow (most common):

// src/claude-worker.ts
import { Command } from "@commander-js/extra-typings";
import { getInputSchema, runWorkflow } from "@bastani/atomic/workflows";
import workflow from "./workflows/review-to-merge/claude.ts";

const program = new Command();
for (const input of getInputSchema(workflow)) {
  program.option(`--${input.name} <value>`, input.description ?? "");
}
program.action(async (rawOpts) => {
  const inputs = rawOpts as Record<string, string>;
  await runWorkflow({ workflow, inputs });
});
await program.parseAsync();

Run it:

bun run src/claude-worker.ts --target_branch=release/v2

Multiple workflows — iterate a registry:

// src/cli.ts
import { Command } from "@commander-js/extra-typings";
import {
  createRegistry,
  getInputSchema,
  getName,
  listWorkflows,
  runWorkflow,
} from "@bastani/atomic/workflows";
import reviewToMerge from "./workflows/review-to-merge/claude.ts";
import genSpec from "./workflows/gen-spec/claude.ts";

const registry = createRegistry().register(reviewToMerge).register(genSpec);
const program = new Command("my-app");

for (const wf of listWorkflows(registry)) {
  const sub = program.command(getName(wf)).description(wf.description);
  for (const input of getInputSchema(wf)) {
    sub.option(`--${input.name} <value>`, input.description ?? "");
  }
  sub.action(async (rawOpts) => {
    await runWorkflow({ workflow: wf, inputs: rawOpts as Record<string, string> });
  });
}

await program.parseAsync();

See examples/multi-workflow/ for a complete runnable version — two Claude workflows (hello, goodbye) registered under one cli.ts.

Programmatic invocation

runWorkflow({ workflow, inputs }) is a plain async function — you don't need a CLI at all:

import { runWorkflow } from "@bastani/atomic/workflows";
import workflow from "./workflows/review-to-merge/claude.ts";

const { id, tmuxSessionName } = await runWorkflow({
  workflow,
  inputs: { target_branch: "main" },
  detach: true,
});

Combine with getSessionStatus(tmuxSessionName) and attachSession(id) to build your own monitoring UI on top of the SDK.

Embedding under a parent CLI — runWorkflow inside any Commander tree

The SDK no longer ships a Commander adapter — it doesn't need one. Just call runWorkflow from inside any Commander action:

import { Command } from "@commander-js/extra-typings";
import { getInputSchema, runWorkflow } from "@bastani/atomic/workflows";
import workflow from "./workflows/deploy/claude.ts";

const program = new Command("my-app");

const deploy = program.command("deploy").description(workflow.description);
for (const input of getInputSchema(workflow)) {
  deploy.option(`--${input.name} <value>`, input.description ?? "");
}
deploy.action(async (rawOpts) => {
  await runWorkflow({ workflow, inputs: rawOpts as Record<string, string> });
});

program.command("hello").action(() => console.log("hi"));

await program.parseAsync();

There's no re-entry boilerplate — the SDK ships its own internal orchestrator entry script and re-execs that with positional args (workflowSource, agent, base64-encoded inputs). Your CLI is never re-imported, so there's nothing to guard against orchestrator-mode env vars.

WorkflowPicker component

The interactive picker (the same one atomic workflow -a claude opens) is exposed as a component:

import { WorkflowPicker } from "@bastani/atomic/workflows/components";

Mount it inside your own OpenTUI app or imperatively via WorkflowPickerPanel.create({ agent, registry }).

Registry rules

• createRegistry() returns an immutable registry. Each .register(wf) call returns a new registry — the original is unchanged. Chain calls to accumulate workflows.
• Each workflow is keyed by ${agent}/${name} — the (agent, name) pair must be unique. Registering a duplicate throws immediately.
• Builtin workflows (ralph, deep-research-codebase, open-claude-design) are managed by atomic's internal createBuiltinRegistry(). They are reserved — user-registered workflows with the same name will not shadow builtins when running the atomic CLI.

Input precedence

runWorkflow({ workflow, inputs }) runs validateInputs(workflow, inputs) for you, applying:

1. defineWorkflow default values (on each WorkflowInput) when no value is provided
2. The first declared enum value when required: true and no value is provided
3. Whatever you pass in inputs

CLI flags compose entirely at the calling-CLI layer — the SDK only sees the final inputs map.

Builtin workflows via the atomic CLI

The atomic workflow command runs the built-in registry via the same primitives:

atomic workflow -n ralph -a claude "Build the auth module"
atomic workflow -n deep-research-codebase -a claude "How does auth work?"
atomic workflow -n open-claude-design -a claude

These are not affected by your own createRegistry() — they are separate.

Migration from 0.x (directory-scanning) and the createWorkflowCli wrapper

Two breaking changes: workflows must declare source: import.meta.path, and the createWorkflowCli / toCommand / runCli wrappers were removed in favour of primitives.

1. Add source: import.meta.path to every defineWorkflow({ ... }) call. The SDK uses it to import the workflow module inside the orchestrator child process.
2. Replace createWorkflowCli(workflow).run() with a small Commander (or citty / yargs) entrypoint that calls runWorkflow({ workflow, inputs }) — see the snippets above. The SDK no longer ships a CLI wrapper.
3. Remove handleOrchestratorReentry / runCli calls — the SDK ships its own orchestrator entry script and the dev's CLI is never re-execed.
4. Update invocations: replace atomic workflow -n foo -a claude with bun run src/claude-worker.ts --<input>=<value> for your custom workflows. For the Atomic builtin set (ralph, deep-research-codebase, open-claude-design) keep using atomic workflow -n <name> -a <agent>.

Configuration

.atomic/settings.json

Resolution order:

1. Local: .atomic/settings.json
2. Global: ~/.atomic/settings.json

{
  "$schema": "https://raw.githubusercontent.com/flora131/atomic/main/assets/settings.schema.json",
  "version": 1,
  "scm": "github",
  "providers": {
    "claude": {
      "chatFlags": ["--model", "claude-sonnet-4-6"],
      "envVars": { "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16384" }
    }
  }
}

Model selection and reasoning effort are managed by each underlying agent CLI (e.g. Claude Code's /model), not Atomic. Atomic's chat command spawns the agent's native TUI — use the agent's own controls.

Agent-Specific Files

All three agents share the same skill set via .agents/skills/. Claude Code accesses them through a .claude/skills/ symlink.

Updating & Uninstalling

Update

bun update -g @bastani/atomic      # latest stable
bun install -g @bastani/atomic@next # prerelease

The first atomic run after upgrading auto-syncs tooling deps and global skills — no separate command needed.

Uninstall

bun remove -g @bastani/atomic

# macOS / Linux
rm -rf ~/.atomic/

# Windows PowerShell
Remove-Item -Path "$env:USERPROFILE\.atomic" -Recurse -Force

Troubleshooting

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

FAQ

Contributing

See DEV_SETUP.md for development setup, testing guidelines, and contribution workflow.

License

MIT License — see LICENSE for details.

Credits

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