# Bastani Atomic

> An open-source, model-agnostic workflow layer for coding agents that lets developers define repeatable engineering workflows with steps, review gates, artifacts, and isolated execution.

Bastani Atomic is an open-source CLI and TypeScript SDK that adds a programmable workflow layer on top of coding agents. Built on the Pi coding-agent runtime, it lets developers define repeatable engineering processes — research, spec creation, implementation, checks, and review gates — as explicit, versioned workflow files rather than ad-hoc interactive sessions. The project is published as `@bastani/atomic` on npm and is available under the MIT license.

## What It Is

Atomic sits between a developer and a coding agent, providing a control plane for complex software engineering work. Instead of running a single long agent session and hoping the model follows the right process, Atomic turns the process itself into an executable graph: stages run in order, parallel branches fan out and converge, artifacts are saved to the repo, and human review gates pause execution before critical handoffs. The tool is model-agnostic — it connects directly to API-key and subscription providers including Claude, ChatGPT, and GitHub Copilot — and is designed to be repo-native, storing research docs, specs, logs, and workflow files alongside the code they describe.

## Core Building Blocks

Atomic ships three top-level primitives:

- **Workflows** — explicit execution graphs with inputs, steps, branches, parallelism, retries, artifact saves, and human review gates. Built-in workflows include `goal` (small-to-medium bounded changes), `ralph` (larger migrations and spec-to-PR work), `deep-research-codebase` (parallel repo-wide research), and `open-claude-design` (parallel design exploration). Developers can also author custom workflows using the `defineWorkflow()` TypeScript API.
- **Skills** — reusable expert instruction modules that auto-invoke on relevant triggers or can be called directly with `/skill:<name>`. Bundled skills cover codebase research, spec creation, sub-agent delegation, session-to-session coordination (intercom), TDD loops, Playwright browser automation, and frontend design auditing.
- **Specialized sub-agents** — eight purpose-built agents with scoped context and tools, including `codebase-locator`, `codebase-analyzer`, `code-simplifier`, and `debugger`. Each runs with fresh, minimal context to reduce attention drift and can execute concurrently.

## Spec-Driven Development Loop

The primary workflow pattern Atomic promotes is a three-phase loop: run `deep-research-codebase` to map the relevant subsystem and write durable research artifacts under `research/`; use `create-spec` to turn that research into a reviewable plan under `specs/`; then run `ralph` or `goal` to implement the spec with staged agent passes, automated checks, and a final review gate. This loop is designed to replace the common pattern of manually re-prompting an agent through the same sequence of steps on every feature or migration.

## Architecture and Extension Model

Atomic is described as a fork of Pi's coding-agent CLI, with first-party workflow, sub-agent, MCP, web-access, and intercom extensions bundled into the published package. The extension model uses TypeScript modules dropped into `.atomic/extensions/` that load on next start. Teams can package workflows, skills, extensions, prompt templates, and themes for sharing via `atomic install npm:…` or `git:…`. The tool supports 30+ model providers through API keys or subscription login, and workflow files can specify model fallback chains for resilience.

## Update: v0.8.20

The latest stable release is **v0.8.20**, published on May 29, 2026. Recent releases in the v0.8.x series have included stability promotions from prerelease to stable (v0.8.17, v0.8.18) and a rename of the SDK tool exclusion option from `excludeTools` to `excludedTools` for consistency with internal system prompt terminology while preserving backward compatibility (v0.8.19). The GitHub repository shows active development with the last push on May 29, 2026, and the project has accumulated 212 stars and 39 forks since its creation in October 2025.

## Features
- Programmable workflow layer for coding agents
- Spec-driven development loop (research → spec → implement)
- Built-in workflows: goal, ralph, deep-research-codebase, open-claude-design
- Custom workflow authoring with defineWorkflow() TypeScript API
- 8 bundled reusable skills (research-codebase, create-spec, tdd, playwright-cli, etc.)
- 8 specialized sub-agents with scoped context and tools
- Human review gates that pause execution before critical handoffs
- Parallel step execution and branching
- Artifact persistence (research docs, specs, logs, transcripts, diffs)
- Model-agnostic: supports 30+ providers via API keys or subscription login
- MCP (Model Context Protocol) support
- Pi-based extension system (TypeScript modules in .atomic/extensions/)
- Session-to-session coordination via intercom skill
- Resumable workflow runs with status querying
- Workflow status queryable via chat interface
- Devcontainer and VM support for autonomous execution
- Programmatic SDK and RPC entry points
- Package system for sharing workflows, skills, and extensions

## Integrations
Anthropic Claude (API key and Claude Pro/Max subscription), OpenAI ChatGPT (API key and ChatGPT Plus/Pro subscription), GitHub Copilot, MCP servers, Playwright (browser automation), tmux (terminal session control), npm / pnpm / Bun package managers, Node.js 24 LTS runtime, Bun runtime, Devcontainers / Docker

## Platforms
WINDOWS, LINUX, WEB, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.8.20

## Links
- Website: https://bastani.ai/
- Documentation: https://docs.bastani.ai/
- Repository: https://github.com/flora131/atomic
- EveryDev.ai: https://www.everydev.ai/tools/bastani-atomic