Quickstart

Generate context files, run Ralph, and build your first workflow.

Five steps, a few minutes. Steps 1–4 use the CLI (pre-built autonomous behavior). Step 5 uses the SDK (your own workflows). Skip to step 5 if you only want the library.

Workflows run with the agent’s permission checks disabled so pipelines don’t block on prompts. Run them inside a devcontainer or a git worktree, not directly on your host. See the permissions model.

Prerequisites

Atomic gives your coding agent a workflow to follow — it doesn’t replace the agent or your terminal. Three things must exist on the host:

• A terminal multiplexer — every stage runs inside a detachable session on a dedicated atomic socket (your personal tmux is untouched). On macOS/Linux this is tmux; on Windows it’s psmux. Both are auto-installed on the first non-info atomic command via your platform’s package manager.
• At least one coding agent, installed and authenticated — Atomic spawns the agent’s own CLI at each stage:
  • Claude Code — run claude and authenticate
  • OpenCode — run opencode and authenticate
  • GitHub Copilot CLI — run copilot and authenticate
• The atomic CLI — see Installation. The bootstrap script ships a prebuilt binary with no Bun/Node prerequisite.

A devcontainer short-circuits all of this — the Atomic feature bundles the multiplexer and an agent CLI into the image.

1. Install

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

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

See Installation for npm, devcontainer, and SDK-only paths.

2. Get oriented with /atomic

Atomic ships an onboarding skill that lives inside your agent. Open a session and ask it for a tour:

atomic chat -a claude   # or: -a opencode | -a copilot

Then run /atomic for the help menu, or jump straight to a section:

Command	What you get
/atomic	Help menu — every entry point at a glance
/atomic overview	30-second summary of how Atomic fits together
/atomic example	A spec-driven walkthrough using the built-in workflows
/atomic workflows	Primer on workflows + how to author your own
/atomic what's new	Recent releases and changes
/atomic <question>	Free-form Q&A — the skill reads Atomic’s source if it doesn’t already know

Use it any time you’re unsure which workflow, skill, or subagent to reach for.

3. Generate context files

Still inside atomic chat, run /init. Atomic explores your codebase with sub-agents and writes CLAUDE.md / AGENTS.md, so every future session starts with the right context. See context files.

4. Run Ralph

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"

Run it in the background with -d / --detach and reattach later:

atomic workflow -n ralph -a claude -d "build the auth module"
atomic workflow session connect atomic-wf-claude-ralph-<id>

Atomic ships three built-in workflows — ralph, deep-research-codebase, and open-claude-design. See built-in workflows.

5. Build your own workflow

Encode your team’s process — review, CI, PR, approval, merge — as TypeScript once; everyone runs the same pipeline.

bun init && bun add @bastani/atomic-sdk

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

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

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

    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);
      }),
    ]);

    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 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 with runWorkflow — the SDK ships pure primitives, so compose with Commander, citty, yargs, or whatever you prefer:

import { Command } from "@commander-js/extra-typings";
import { getInputSchema, runWorkflow } from "@bastani/atomic-sdk/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) => {
  await runWorkflow({ workflow, inputs: rawOpts as Record<string, string> });
});
await program.parseAsync();

Run it:

bun run src/claude-worker.ts

That’s the full shape — one workflow file, one composition root. See the SDK reference for parallel stages, input schemas, headless stages, and the full API.

Next steps

Why Atomic

The problem workflows solve.

Workflows

Stages, the execution graph, and human-in-the-loop gates.

CLI commands

Every atomic subcommand.

SDK reference

defineWorkflow, runWorkflow, registries, and embedding.