Summary

Atomic provides a programmable control plane for software engineering workflows, automating complex tasks beyond simple coding assistance. It targets developers and teams seeking to operationalize repeatable processes like research, planning, implementation, and review, offering an inspectable, model-agnostic, and extensible system for enhanced productivity and auditability.

How It Works

Atomic is built on the Pi framework, extending it with a robust workflow layer. It orchestrates coding agent sessions through explicit workflows that define stages, parallelism, artifact saving, and human review gates. The system leverages reusable "skills" and specialized "sub-agents" to decompose complex jobs, enabling context isolation and parallel execution for improved reliability and auditability compared to monolithic agent sessions.

Quick Start & Requirements

• Install: Global installation via npm install -g @bastani/atomic, pnpm add -g @bastani/atomic, or bun add -g @bastani/atomic.
• Prerequisites: Node.js 24 LTS+, a package manager (npm, pnpm, Yarn, Bun), and model-provider access (API keys or subscriptions for providers like Claude, ChatGPT, Copilot).
• Authentication: Set environment variables (e.g., export ANTHROPIC_API_KEY=sk-ant-...) and run atomic, or use atomic /login for subscription-based providers.
• Environment: Autonomous workflows are recommended to run within a devcontainer, VM, or remote dev machine for security.
• Docs: Full documentation available at docs.bastani.ai.

Highlighted Details

• Spec-Driven Development: Facilitates a loop of codebase research, spec creation, implementation workflow execution, and artifact review.
• Workflows: Includes built-in workflows like goal (focused changes), ralph (large migrations), and deep-research-codebase (repo-wide analysis), with support for authoring custom workflows.
• Skills & Sub-agents: Employs reusable skills (e.g., research-codebase, create-spec) and specialized sub-agents (e.g., codebase-analyzer) for modular task decomposition and context isolation.
• Model Agnosticism: Connects directly to various model providers via API keys or subscriptions, allowing flexibility in LLM choice.

Maintenance & Community

• Community: An active Discord community is available for support, feedback, and sharing.
• Contribution: Guidelines are detailed in CONTRIBUTING.md, with development setup in DEV_SETUP.md.
• Workflows: Additional workflows can be found in the separate atomic-workflows repository.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license permits broad commercial use and integration with closed-source projects.

Limitations & Caveats

• Autonomous workflows should not be run directly on host machines due to security considerations.
• Recent changes to workflow authoring may necessitate updates for custom workflows that rely on specific import mechanisms.
• While workflow execution is deterministic, the output of the underlying LLM models remains non-deterministic.