Atomic

Ship complex features with AI agents that actually understand your codebase. Research, spec, implement — then wake up to completed code ready for review.

Key Principle

You own the decisions. Agents own the execution.

Review specs before implementation (architecture decisions)
Review code after each feature (quality gate)
The 60-80% rule: agents get you most of the way, you provide the polish
Play around with the agents and use them as your swiss army knife

Video Overview

What Engineers Use Atomic For

Ship Complex Features End-to-End

Not just bug fixes — scoped, multi-file features that require architectural understanding:

Database migrations across large codebases
Entire new services (building a complete GraphRAG service from scratch)
Features spanning dozens of files that need to understand existing patterns first
Trying different implementation approaches — spec it out, try one framework, revert, try another

The workflow: /research-codebase → review → /create-spec → review → /ralph (manual or autonomous implementation) → /gh-create-pr. Wake up to completed features ready for review.

Works on macOS, Linux, and Windows.

Deep Codebase Research & Root Cause Analysis

You know the pain:

Hours lost hunting through unfamiliar code manually and not seeing real gains in productivity with coding agents
Agents missing key files even when you know they're relevant
Repeating yourself — mentioning the same file over and over, only for the agent to ignore it
Context window blown before you've even started the real work
Files too large to paste — so you just... can't share the context you need

The /research-codebase command dispatches specialized sub-agents to do the hunting for you:

Understand how authentication flows work in an unfamiliar codebase
Track down root causes by analyzing code paths across dozens of files
Search through docs, READMEs, and inline documentation in your repo
Get up to speed on a new project in minutes instead of hours

This is the fastest path to value — install, run one command, get answers.

Explore Multiple Implementation Approaches

When you're evaluating libraries, exploring implementation approaches, or need best practices before building, Atomic's research phase pulls in external knowledge — not just your codebase — to inform the spec and implementation plan.

Example: Researching three GraphRAG implementation approaches in parallel

# Run 3 parallel research sessions in separate terminals
atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
  LangChain's graph retrieval patterns. Look up langchain-ai/langchain for \
  graph store integrations, chunking strategies, and retrieval patterns. \
  Document how this would integrate with our existing vector store."

atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
  Microsoft's GraphRAG library. Look up microsoft/graphrag for their \
  community detection, entity extraction, and summarization pipeline. \
  Document the infrastructure requirements and how it fits our data model."

atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
  LlamaIndex's property graph index. Look up run-llama/llama_index for \
  their KnowledgeGraphIndex and property graph patterns. Document trade-offs \
  vs our current RAG implementation."

What happens: Each agent spawns specialized codebase research sub-agents that query DeepWiki for the specified repos, pull external documentation, and cross-reference with your existing codebase patterns and logic. You get three research documents.

From there: Run /create-spec on each research doc in parallel terminals. Then spin up three git worktrees and run /ralph in each. Wake up to three complete implementations on separate branches — review, benchmark, and choose the winner.

Note: This workflow works identically with atomic chat -a opencode and atomic chat -a copilot.

Quick Start Guide

Prerequisites

Operating Systems: macOS, Linux, or Windows (with PowerShell)
At least one coding agent installed:

Step 1: Install Atomic

macOS / Linux:

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

Windows PowerShell:

irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex

Step 2: Initialize Your Project

cd your-awesome-project
atomic init

Select your coding agent when prompted. The CLI configures your project automatically.

Step 3: Generate Context Files

Start a chat session and run /init to generate CLAUDE.md and AGENTS.md:

atomic chat -a <claude|opencode|copilot>

/init

The /init command explores your codebase using sub-agents and generates documentation tailored to your project. These files give coding agents the context they need to work effectively.

Step 4: Ship Features

Research → Spec → Implement → (Debug) → PR

Research the codebase:

/research-codebase [Describe your feature or question]
/clear

Review: Confirm the agent understood your codebase and requirements.

Create a specification:

/create-spec [research-path]
/clear

Review (critical): This is your main decision point. The spec becomes the contract.

Implement features:

/ralph "<prompt-or-spec-path>"

Commit and ship:

/gh-commit
/gh-create-pr

Debugging: If something breaks during implementation, use the debugging agent:

Use the debugging agent to create a debugging report for [insert error message here].

Then follow the debugging report to resolve the issue.

Advanced Installation

Install a specific version

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash -s -- v1.0.0

Windows PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1) } -Version v1.0.0"

Custom install directory

macOS / Linux:

ATOMIC_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash

Windows PowerShell:

$env:ATOMIC_INSTALL_DIR = "C:\tools"; irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex

Source control selection

During atomic init, you'll be prompted to select your source control system:

SCM Type	CLI Tool	Code Review	Use Case
GitHub / Git	`git`	Pull Requests	Most open-source projects
Sapling + Phabricator	`sl`	Phabricator Diffs	Meta-style stacked workflows

The selection is saved to .atomic/settings.json and configures the appropriate commit and code review commands.

Sapling + Phabricator:

Ensure .arcconfig exists in your repository root
Use /sl-commit for commits and /sl-submit-diff for code review

Note for Windows users: Sapling templates use the full path & 'C:\Program Files\Sapling\sl.exe' to avoid conflicts with PowerShell's built-in sl alias.

The Flywheel

Research → Specs → Execution → Outcomes → Specs (persistent memory)
                ↑                                    ↓
                └────────────────────────────────────┘

Every feature follows this cycle. Specs and research become memory for future sessions.

How It Works

Commands, Agents, and Skills

CLI Commands

Top-level Atomic CLI commands.

Command	Description
`atomic init`	Interactive setup
`atomic chat`	Start TUI chat with a coding agent (default command)
`atomic config set <k> <v>`	Set CLI configuration values (example: telemetry opt-in/out)
`atomic update`	Self-update Atomic (binary installs only)
`atomic uninstall`	Remove Atomic installation (binary installs only)

`atomic chat` Flags

Flag	Default	Description
`-a, --agent <name>`	`"claude"`	Agent to chat with (`claude`, `opencode`, `copilot`)
`-w, --workflow`	`false`	Enable graph workflow mode
`-t, --theme <name>`	`"dark"`	UI theme (`dark`, `light`)
`-m, --model <name>`	(none)	Model to use for the chat session
`--max-iterations <n>`	`"100"`	Maximum iterations for workflow mode
`[prompt...]`	(none)	Initial prompt to send

`atomic init` Flags

Flag	Default	Description
`-a, --agent <name>`	(none)	Pre-select agent (skips interactive prompt)

Slash Commands

User-invocable chat commands for workflows, built-ins, and skills.

Command	Arguments	Description
`/help`		Show all available commands
`/clear`		Clear all messages and reset session
`/compact`		Compact context to reduce token usage
`/model`	`[model\|list\|select]`	View/switch active model
`/mcp`	`[enable\|disable]`	View and toggle MCP servers
`/theme`	`[dark\|light]`	Toggle between dark and light theme
`/exit`		Exit the chat application
`/init`		Generate `CLAUDE.md` and `AGENTS.md` by exploring codebase
`/research-codebase`	`"<question>"`	Analyze codebase and document findings
`/create-spec`	`"<research-path>"`	Generate technical specification
`/explain-code`	`"<path>"`	Explain code section in detail
`/gh-commit`		Create a Git commit using Git/GitHub workflow
`/gh-create-pr`		Commit, push, and open a GitHub pull request
`/sl-commit`		Create a Sapling commit
`/sl-submit-diff`		Submit Sapling changes to Phabricator
`/ralph`	`"<prompt>"`	Run autonomous implementation workflow

Agents

Sub-agents that execute specialized tasks. These are invoked automatically by commands or can be requested directly.

Agent	Purpose
`codebase-analyzer`	Analyze implementation details of specific components
`codebase-locator`	Locate files, directories, and components for a task
`codebase-pattern-finder`	Find similar implementations and usage examples
`codebase-online-researcher`	Research questions using web sources
`codebase-research-analyzer`	Deep dive on research topics
`codebase-research-locator`	Discover relevant documents in `research/` directory
`debugger`	Debug errors, test failures, and unexpected behavior

Skills

Domain knowledge applied during work. These are automatically invoked when relevant.

Skill	Purpose
`testing-anti-patterns`	Prevent common testing mistakes (mock misuse, test pollution)
`prompt-engineer`	Apply best practices when creating or improving prompts
`frontend-design`	Create distinctive, production-grade frontend interfaces with high design quality

TUI Features

The Atomic TUI chat interface includes several features for an enhanced development experience.

Keyboard Shortcuts

Shortcut	Action
`Ctrl+O`	Open transcript view
`Ctrl+C`	Interrupt current operation

Themes

Switch between dark and light themes:

# Via CLI flag
atomic chat -a claude --theme light

# Via slash command in chat
/theme dark

@Mentions

Reference files in your messages using @ mentions. The TUI provides autocomplete suggestions as you type.

Verbose Mode

Toggle verbose output to see detailed agent activity, tool calls, and token usage.

Supported Coding Agents

Agent	CLI Command	Folder	Context File
Claude Code	`atomic chat -a claude`	`.claude/`	`CLAUDE.md`
OpenCode	`atomic chat -a opencode`	`.opencode/`	`AGENTS.md`
GitHub Copilot CLI	`atomic chat -a copilot`	`.github/`	`AGENTS.md`

Autonomous Execution (Ralph)

The Ralph Wiggum Method enables multi-hour autonomous coding sessions. After approving your spec and feature list, let Ralph work in the background while you focus on other tasks.

How It Works

Create and approve your spec (/create-spec)
Start the workflow (/ralph "<prompt-or-spec-path>")
Ralph executes a 3-step process:
- Step 1 — Task Decomposition: Breaks the spec/prompt into a structured task list
- Step 2 — Implementation Loop: Dispatches worker sub-agents to implement tasks one-by-one (up to 100 iterations)
- Step 3 — Review & Fix: Spawns a reviewer sub-agent to audit the implementation, generates fix specs if needed, and re-runs implementation for any issues found

Usage

/ralph "<prompt-or-spec-path>"

Argument	Description
`"<prompt>"`	Prompt or path to a spec file (required for new runs)

Chat Interface

Ralph runs inside the Atomic TUI chat interface:

# Start chat with your preferred agent: claude, opencode, or copilot
atomic chat -a <claude|opencode|copilot>

# Or even specify agent and theme
atomic chat -a opencode --theme <light/dark>

Examples

# Start a new workflow with a prompt
/ralph "Build a REST API for user management"

# Start from a spec file
/ralph "specs/my-feature.md"

Configuration Files

`.atomic/settings.json`

Atomic stores project-level configuration in .atomic/settings.json. This file is created automatically during atomic init.

Configuration resolution for project defaults:

Local override: .atomic/settings.json
Global fallback: ~/.atomic/settings.json

Atomic no longer reads or writes .atomic.json.

Example .atomic/settings.json:

{
    "version": 1,
    "agent": "claude",
    "scm": "github",
    "lastUpdated": "2026-02-12T12:00:00.000Z"
}

Fields:

Field	Type	Description
`version`	number	Config schema version (currently `1`)
`agent`	string	Selected coding agent (`claude`, `opencode`, `copilot`)
`scm`	string	Source control type (`github`, `sapling`)
`lastUpdated`	string	ISO 8601 timestamp of last configuration update

Note: You generally don't need to edit this file manually. Use atomic init to reconfigure your project.

Agent-Specific Files

Each agent has its own configuration folder:

Agent	Folder	Skills	Context File
Claude Code	`.claude/`	`.claude/skills/`	`CLAUDE.md`
OpenCode	`.opencode/`	`.opencode/skills/`	`AGENTS.md`
GitHub Copilot	`.github/`	`.github/skills/`	`AGENTS.md`

Updating Atomic

Native installation (Recommended)

If you installed Atomic using the native install script, you can update using the built-in command:

# Update to the latest version
atomic update

bun installation

Use your package manager to update:

# Using bun
bun upgrade @bastani/atomic

Uninstalling Atomic

Native installation (CLI command)

If you installed Atomic using the native install script, you can uninstall using the built-in command:

# Preview what will be removed (no changes made)
atomic uninstall --dry-run

# Uninstall Atomic
atomic uninstall

# Keep configuration data, only remove binary
atomic uninstall --keep-config

# Skip confirmation prompt
atomic uninstall --yes  # or -y

The uninstall command will:

Remove the Atomic binary from ~/.local/bin/atomic (or your custom install directory)
Remove configuration data from ~/.local/share/atomic (unless --keep-config is used)
Remove Atomic-managed global agent configs from ~/.atomic/.claude, ~/.atomic/.opencode, and ~/.atomic/.copilot (unless --keep-config is used)
Display instructions for removing the PATH entry from your shell configuration

Native installation (manual)

If the CLI command is not available, you can manually remove the files:

macOS, Linux:

rm -f ~/.local/bin/atomic
rm -rf ~/.local/share/atomic
rm -rf ~/.atomic/.claude ~/.atomic/.opencode ~/.atomic/.copilot

If you installed to a custom directory, remove the binary from that location instead.

Windows PowerShell:

Remove-Item "$env:USERPROFILE\.local\bin\atomic.exe" -Force
Remove-Item "$env:LOCALAPPDATA\atomic" -Recurse -Force
Remove-Item "$env:USERPROFILE\.atomic\.claude" -Recurse -Force
Remove-Item "$env:USERPROFILE\.atomic\.opencode" -Recurse -Force
Remove-Item "$env:USERPROFILE\.atomic\.copilot" -Recurse -Force

bun installation

# Using bun
bun remove -g @bastani/atomic

Clean up configuration files (optional)

Warning: Removing configuration files will delete all your project-specific settings, skills, and agents configured by Atomic.

To remove Atomic configuration files from a project:

macOS, Linux:

# For Claude Code
rm -rf .claude/ CLAUDE.md

# For OpenCode
rm -rf .opencode/ AGENTS.md

# For GitHub Copilot
rm -f .github/copilot-instructions.md

Windows PowerShell:

# For Claude Code
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path "CLAUDE.md" -Force

# For OpenCode
Remove-Item -Path ".opencode" -Recurse -Force
Remove-Item -Path "AGENTS.md" -Force

# For GitHub Copilot
Remove-Item -Path ".github\copilot-instructions.md" -Force

Telemetry

Atomic collects anonymous usage telemetry to help improve the product. All data is anonymous and privacy-respecting.

What We Collect

Command names (init, help, config, etc.)
Agent type (claude, opencode, copilot)
Success/failure status
Session and workflow metrics (duration, feature count)

What We NEVER Collect

Your prompts or queries
File paths or code content
IP addresses or location data
Personal identifiable information

Privacy Features

Anonymous ID: A stable but non-identifiable ID derived from machine characteristics
Local logging: Telemetry is stored locally as JSONL files before any remote transmission
CI auto-disable: Telemetry is automatically disabled in CI environments (CI=true)
First-run consent: You're prompted to opt-in during your first use of atomic init

Data Storage

Telemetry data is stored locally before being sent:

Platform	Local Log Path
Windows	`%APPDATA%\atomic\telemetry\`
macOS	`~/Library/Application Support/atomic/telemetry/`
Linux	`~/.local/share/atomic/telemetry/` (XDG compliant)

Opt-Out Methods

You can disable telemetry at any time using any of these methods:

# Using the config command
atomic config set telemetry false

# Using environment variables (shell)
export ATOMIC_DISABLE_TELEMETRY=1

Windows PowerShell:

# Set environment variable for current session
$env:ATOMIC_DISABLE_TELEMETRY = "1"

# Or set permanently for your user
[Environment]::SetEnvironmentVariable("ATOMIC_DISABLE_TELEMETRY", "1", "User")

To re-enable telemetry:

atomic config set telemetry true
# Or remove the environment variables
unset ATOMIC_DISABLE_TELEMETRY

Programmatic Configuration

If you're integrating Atomic into your tooling:

import { loadTelemetryConfig, isTelemetryEnabled } from "@bastani/atomic";

// Check if telemetry is enabled
if (isTelemetryEnabled()) {
    // Telemetry will be collected
}

// Load full configuration
const config = loadTelemetryConfig();
console.log(config.enabled); // boolean
console.log(config.localLogPath); // platform-specific path

Troubleshooting

Git Identity Error: Configure git identity:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Windows Command Resolution: If agents fail to spawn on Windows, ensure the agent CLI is in your PATH. Atomic uses Bun.which() to resolve command paths, which handles Windows .cmd, .exe, and .bat extensions automatically.

Generating CLAUDE.md/AGENTS.md: atomic init does not create CLAUDE.md or AGENTS.md. Run /init inside a chat session to generate these files. The command explores your codebase and produces project-specific documentation for coding agents.

Shift+Enter Not Inserting Newline: Atomic uses layered newline detection in chat input.

Kitty protocol (VS Code path): In VS Code's integrated terminal, keep terminal.integrated.enableKittyKeyboardProtocol enabled so Shift+Enter is sent as a modified Enter key.
modifyOtherKeys (supported terminals): In terminals like GNOME Terminal, xterm, Alacritty, WezTerm, and iTerm2, Atomic enables modifyOtherKeys mode automatically to preserve Shift+Enter multiline behavior.
Universal fallback: Use Ctrl+J to insert a newline in any terminal.
Last resort: If your terminal does not provide modified Enter sequences, end the line with \ and press Enter to continue on a new line.

Best Practice: Run Ralph in a separate git worktree to isolate autonomous execution from your main development session:

# Create a worktree for Ralph
git worktree add ../my-project-ralph feature-branch

# Run Ralph in the worktree
cd ../my-project-ralph
atomic chat -a claude
# then type: /ralph "Build the auth module"

This keeps your main workspace free for other work while Ralph runs autonomously.

FAQ

How Atomic Differs from Spec-Kit

Spec Kit is GitHub's toolkit for "Spec-Driven Development" where specifications become executable artifacts. While both projects aim to improve AI-assisted development, they solve different problems:

Aspect	Spec-Kit	Atomic
Primary Focus	Greenfield projects - building new features from specifications	Large existing codebases and greenfield - understanding patterns before implementing
First Step	`/speckit.constitution` - define project principles	`/research-codebase` - analyze existing architecture and patterns
Memory Model	Per-feature specs in `.specify/specs/`	Flywheel of active, semantic, and procedural memory: `Research → Specs → Execution → Outcomes` with `progress.txt` tracking
Agent Architecture	Single agent executes slash commands via shell scripts	Specialized sub-agents: `codebase-analyzer`, `codebase-locator`, `codebase-pattern-finder`
Human Review	Implicit in workflow	Explicit checkpoints with "You review (CRITICAL)" markers
Debugging	Not addressed	Dedicated debugging agent workflow
Autonomous Runs	Not available	Ralph for overnight feature implementation

When to choose Atomic:

Working with an existing, large codebase where you need to discover patterns first and greenfield projects
Need session continuity, context management, and built-in memory
Want explicit human-in-the-loop checkpoints
Need debugging workflows when implementations fail
Want autonomous overnight execution (Ralph) for coding agents

Contributing Guide

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

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 966 Commits
.claude		.claude
.github		.github
.opencode		.opencode
assets		assets
docs		docs
research		research
specs		specs
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
DEV_SETUP.md		DEV_SETUP.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
install.ps1		install.ps1
install.sh		install.sh
lefthook.yml		lefthook.yml
oxlint.json		oxlint.json
package.json		package.json
tsconfig.json		tsconfig.json

License

flora131/atomic

Folders and files

Latest commit

History

Repository files navigation

Atomic

Key Principle

Video Overview

What Engineers Use Atomic For

Ship Complex Features End-to-End

Deep Codebase Research & Root Cause Analysis

Explore Multiple Implementation Approaches

Table of Contents

Quick Start Guide

Prerequisites

Step 1: Install Atomic

Step 2: Initialize Your Project

Step 3: Generate Context Files

Step 4: Ship Features

Advanced Installation

The Flywheel

How It Works

Commands, Agents, and Skills

CLI Commands

atomic chat Flags

atomic init Flags

Slash Commands

Agents

Skills

TUI Features

Keyboard Shortcuts

Themes

@Mentions

Verbose Mode

Supported Coding Agents

Autonomous Execution (Ralph)

How It Works

Usage

Chat Interface

Examples

Configuration Files

.atomic/settings.json

Agent-Specific Files

Updating Atomic

Native installation (Recommended)

bun installation

Uninstalling Atomic

Native installation (CLI command)

Native installation (manual)

bun installation

Clean up configuration files (optional)

Telemetry

What We Collect

What We NEVER Collect

Privacy Features

Data Storage

Opt-Out Methods

Programmatic Configuration

Troubleshooting

FAQ

How Atomic Differs from Spec-Kit

Contributing Guide

License

Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 23

Packages 0

Uh oh!

Contributors 6

Languages

`atomic chat` Flags

`atomic init` Flags

`.atomic/settings.json`

Packages