Atomic 0.8.30 is out, read the release notes

The workflow layer for coding agents.

Define repeatable coding-agent workflows with steps, review gates, artifacts, and isolated execution. The agent writes the code. Atomic runs the process around it.

$ npm install -g @bastani/atomic Copied!
Star on GitHub ★ 251 Workflow docs
ATOMIC promo · loop
● live 00:00 / 38s
── the problem

Long agent runs need a repeatable process.

A one-off edit can stay interactive. A feature, migration, or refactor usually needs the same sequence every time: research the repo, write a spec, change code, run checks, review the diff, and keep the artifacts.

research

Research first.

Map the subsystem, collect file references, and save repo research before changing code.

repeat

Make the sequence explicit.

Put inputs, step order, branches, checks, reviewers, and artifacts in a workflow file.

review

Stop at review.

End long runs with the diff, check output, reviewer notes, and artifacts ready to inspect.

See a full run lifecycle
── spec-driven feature work

Large features without one long interactive session.

A typical workflow has three phases: map the repo, approve the spec, then run the implementation loop.

01 deep research workflow
query → fan out locate analyze patterns → research doc
02 spec human review
research doc → spec draft → human review → approved spec
03 ralph workflow
approved spec → loop build → review → diff + artifacts

Other workflow shapes.

Same model: explicit steps, parallel work, human gates, saved outputs.

issue to draft PR
issue → research → verify tests review → PR gate
persona feedback
feature spec → personas admin new user mobile → ranked tasks
alert to draft fix
alert → gather trace commits → cause → draft fix
── when to use it

Use Atomic when the process matters.

Use it when a coding-agent routine has become important enough to repeat, review, and save.

repeatable reviewable versioned
01

You manually run the same prompts and skills.

You keep asking agents to follow the same setup, prompts, skills, or handoff pattern.

02

You need an audit trail.

Keep prompts, steps, logs, checks, notes, and final output so you can inspect the run, not just the answer.

03

The process belongs in the repo.

Store the workflow in the repo instead of relying on prompt habits or undocumented team process.

probably not

Skip it for a quick one-file edit, a short coding question, or casual interactive pairing.

── then during a run

What Atomic records during a run.

Atomic tracks the path from goal to review gate: steps, handoffs, checks, artifacts, and status.

goal → research → spec or plan → branch/workspace → agent steps → artifacts → tests/lint → reviewer passes → review gatefinal output

Step order, inputs, handoffs, checks, gates, and artifacts are defined. The model still generates code and text. The workflow defines the sequence it has to follow.

Ask status in chat
── workflow as code

Workflow files for coding agents.

Put the process in a workflow file. Review it, version it, and run it from the repo.

Read workflow file syntax
ATOMIC CHAT workflow-creator
↵ send
describe a workflow:
›

ship-feature.workflow.ts @bastani/atomic 
import defineWorkflow  from "@bastani/workflows";

export default defineWorkflow("ship-feature")
  .input("task", { type: "text", required: true })
  .run(async (ctx) => {
    const plan = await ctx.task("planner", { prompt: ctx.inputs.task });
    await ctx.task("build",   { prompt: "Implement:\n{previous}", previous: plan });
    await ctx.parallel([
      { name: "review", task: "Review the diff" },
      { name: "tests",  task: "Run tests, report failures" },
    ]);
    if (await ctx.ui.confirm("Open PR?")) {
      await ctx.task("ship", { prompt: "Open a draft PR" });
    }
  })
  .compile();
Orchestrator ship-feature
✓ 2 ● 2 ○ 1
planner 2.1s
build 12.4s
review 8.7s
review 6.2s
ship pending
GRAPH
↑↓←→ navigate ↵ attach / stages ctrl+b d detach q quit
query status in chat

Query a running workflow.

Ask Atomic chat about any running workflow. It can report stage, completed steps, pending work, artifacts, token usage, cost, logs, failures, and anything waiting on you.

Try: what is the status?
ATOMIC CHAT status query
● running
› what is the status of the ralph workflow?
Current observable stage

It looks like the run is in a review and validation pass after iteration 4.

Two active review subagents were launched around 09:43:

  • 5efcedc0_codebase-analyzer
  • 9a7e4699_codebase-analyzer

They are reviewing the current diff for concrete docs correctness issues: broken links, inaccurate changelog claims, validator false positives or negatives, and package script issues. Their input files exist, but no output artifacts were present yet when I checked.

Progress so far

Iterations 1 through 4 are effectively complete. The implementation notes report:

  • docs audit and source extraction done
  • docs implementation done
  • link normalization done
  • subagents docs page added
  • docs link validation passing
Remaining likely next step

Wait for the two current review subagents to finish. If they approve, Ralph should proceed toward final PR prep. If they find a concrete issue, Ralph will loop again or apply a focused fix.

next step

Create a workflow in your repo.

Install Atomic, run atomic, then use /atomic to set up the repo or /workflow ralph to run a feature workflow.

Install and run atomic Open workflow list
$ npm install -g @bastani/atomic Copied!
── built-in workflows

Built-in workflows you can run or modify.

Run them as-is, or use them as templates for your team's workflow files.

start here
repeatable workflows
atomic
workspace · interactive runtime

Start in a repo, then dispatch a workflow when the process matters.

any repo+ your prompt → atomicread · write · edit · bash · 30+ providers → inline, or dispatch a workflow dispatch · workflows /workflow ralph /workflow deep-research-codebase /workflow open-claude-design

Use interactive sessions for quick work; dispatch workflows when you need steps, artifacts, checks, and a review gate. Type /atomic for guided setup.

Run: atomic
/workflow ralph
spec or goal · implementation loop

Turn a spec or goal into an implementation branch.

a spec or a research doc + your prompt → plan → plan · simplify · review loop implementagent steps → code simplify → review → done

ralph runs a plan, simplify, and review loop from a spec or goal, then stops with the branch, artifacts, check output, and final diff ready to inspect.

Run: /workflow ralph
deep-research-codebase
parallel · map it

Map a codebase before you change it.

a research query → codebase-locator → fan out · parallel sub-agents analyzers locators infra locators pattern finders online researchers → synthesize → research doc

deep-research-codebase writes durable repo research artifacts: file maps, implementation notes, prior decisions, and sources you can load before a migration or refactor.

Run: /workflow deep-research-codebase
open-claude-design
explore · pick one

Try several approaches in parallel. Keep one.

your prompt → branch · isolated contexts variant A variant B variant C → compare → you pick one → carry forwardfull history

open-claude-design explores several design directions in parallel branches, then lets you compare artifacts and carry forward the one you choose.

Run: /workflow open-claude-design
── skills + sub-agents

Reusable steps and scoped agents.

Atomic includes reusable skills and scoped sub-agents for research, specs, tests, review, debugging, and UI checks. Workflow files call them as focused steps.

skills
8 bundled

Reusable process steps the agent can load on demand.

  • research-codebase: parallel sub-agents write a dated research doc
  • create-spec: turn research into an executable spec
  • subagent: delegate scoped steps to bundled agents
  • intercom: coordinate across sessions on the same machine
  • prompt-engineer: sharpen prompts, research questions, workflow inputs
  • tdd: red→green→refactor with a testing guide
  • playwright-cli: drive a real browser for tests and scraping
  • impeccable: design, audit, and polish frontend UI
sub-agents
8 bundled

Scoped specialists for research, review, cleanup, and debugging.

  • codebase-locator: find files, dirs, and components fast
  • codebase-analyzer: deep-dive a component's implementation
  • codebase-pattern-finder: surface similar implementations and usage
  • codebase-online-researcher: fetch authoritative web docs
  • codebase-research-locator: find prior research docs in research/
  • codebase-research-analyzer: extract decisions and rationale
  • code-simplifier: clean up without changing behavior
  • debugger: chase down errors, test failures, oddities

Skills follow the Agent Skills standard. Sub-agents run with fresh, minimal context per job and only the tools they need. Add your own under .atomic/skills/ or .atomic/agents/, then call them from a workflow file. Add .atomic/skills/ Add .atomic/agents/

── extend it

Extend the runtime when you need to.

Atomic runs on Pi, the coding-agent runtime behind its TUI, providers, tools, sessions, MCP, skills, and extensions. You can use workflows without learning Pi first.

extensions

TypeScript modules that add tools, commands, hooks, providers, and UI components.

intercom

1:1 messaging between sessions on the same machine for planner-worker workflows.

prompts & themes

Reusable prompt templates and themes (Catppuccin, Tokyo Night, your own, hot-reloaded).

packages

Bundle workflows, skills, extensions, prompts, and themes. atomic install npm:… or git:….

Drop a TypeScript file under .atomic/extensions/ and it loads on next start. Package workflows, skills, extensions, prompts, and themes when your team needs to share the process. Read extension docs

── shipping
All releases
0.8.30 Bumped the bundled upstream pi runtime libraries `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui` from `^0.79.3` to `^0.79.4`, added `semver` as an explicit runtime dependency for package/version checks, and aligned companion extension peer ranges so Atomic inherits upstream provider/model metadata updates, agent-core fixes, the new terminal background-color query used by first-run theme detection, and shared TUI wrapping/keyboard compatibility fixes. 0.8.29 Added support for local `-e <dir>` extension sources to borrow project-local Atomic resources from `<dir>/.atomic`, legacy `<dir>/.pi`, and `<dir>/.agents/skills` after resolving trust for that extension source, preserving package-manager provenance and explicit-path workflow forwarding while avoiding untrusted borrowed resources ([#1354](https://github.com/bastani-inc/atomic/issues/1354)). 0.8.28 Added optional inline free-form text entry to the `ask_user_question` TUI's **Chat about this** footer row. Non-empty typed chat text now returns as a `kind: "chat"` answer surfaced to the agent without the legacy stop/wait termination envelope, while empty submissions keep the existing sentinel behavior.

Define the process. Run the agent.

Install once, run atomic in a repo, then sign in with /login or an API key. Use /atomic for setup, or /workflow ralph for feature work that needs a spec, checks, artifacts, and a review gate.

View source Open docs
── faq

Frequently asked questions.

Atomic includes a coding-agent runtime, but the focus is the workflow layer: repeatable steps, artifacts, checks, reviewer passes, and review gates for complex engineering work. Quick interactive tools are still the right fit for one-off edits.

Use those for quick interactive sessions. Use Atomic when the work needs repeatable steps, saved artifacts, tests, lint, reviewer passes, and a review gate before handoff.

Markdown documents the process. Atomic runs it: steps, inputs, artifacts, checks, approvals, and handoffs are part of the run instead of another checklist the agent has to remember.

Atomic makes the workflow explicit and repeatable. The selected model still generates the code and text, so the model output itself can vary.

Open Atomic chat and ask for the workflow status. Atomic can summarize the current stage, progress so far, artifacts, token usage, estimated cost, logs, failures, and anything waiting on you.

Atomic is built around repo workflows: specs, research, plans, branches, diffs, tests, lint, artifacts, reviewers, and workflow files instead of a generic agent graph you have to adapt to coding work.

Still evaluating? Read the workflow docs