Atomic

A mathematically sound distributed version control system — built for the age of AI.

Why Atomic?

Git was designed for humans writing code in text editors. It tracks lines in files. That worked for 20 years.

Now AI agents write most of the code. They work in sessions and turns, use multiple models, cost money per token, and produce changes that need to be audited, attributed, and explained. Git doesn't know about any of this — you're bolting on external tools to answer basic questions like "which model wrote this?" or "how much did this session cost?"

Atomic is version control that understands AI-assisted development from the ground up.

Atomic vs Git for Agentic Workflows

How It Works

Automatic Turn Recording

Enable agent hooks once. Every turn is recorded automatically.

# Enable for your agent (auto-detects Claude Code, Gemini CLI, OpenCode)
atomic agent enable

# That's it. Every agent turn now produces an Atomic change with:
#   - Model and provider identity
#   - Session and turn number
#   - Token usage and cost
#   - Cryptographic signature
#   - Provenance graph (why the agent made each decision)

Provenance Graphs

Every agent session builds a causal decision DAG. Not just what changed, but why:

Goal: "Fix the authentication bug"
  ├── Exploration: read src/auth.rs
  ├── Exploration: grep "verify_token"
  ├── Commitment: edit src/auth.rs (fix token validation)
  ├── Verification: bash "cargo test"
  └── PatchProposal: Change XMJZ3IPF (2 files)

These graphs are content-addressed, stored alongside changes, and pushed to remotes. Your team can review not just the code, but the agent's reasoning.

Attestations

When a session ends, Atomic creates an attestation — a graph-level audit node covering the session:

$ atomic agent attest

  XMJZ3IPF OpenCode · claude-sonnet-4-5 · 12.4k tokens · 3m 42s · 2 changes
  R3KQP7YN Claude Code · claude-sonnet-4-5 · 8.1k tokens · 1m 15s · 1 change

──────────────────────────────────────────
Total: $0.12 · 3 changes covered · 20.5k tokens

Views, Not Branches

Agents work on isolated views of the same underlying graph. No branch divergence, no merge commits, no orphaned history.

# Agent session creates an isolated view automatically
# View: agent-ses_3781fc7a6ffet5c6r1ILy1BEbv (Draft, parent: dev)

# When done, insert changes into the parent view
atomic insert @~1 --to dev

# Delete the agent view — cascade-deletes its edges, zero orphans
atomic view delete agent-ses_3781fc7a6ffet5c6r1ILy1BEbv

Workspace Shelving

When you switch views, Atomic automatically isolates build artifacts per view — each view gets its own node_modules/, target/, etc. But tool configs like .opencode/, .vscode/, and .idea/ are project-wide and should persist across all views.

Atomic handles this with [workspace] expose:

# .atomic/config.toml
[workspace]
expose = [".opencode", ".vscode", ".idea", ".claude", ".gemini"]

• .atomicignore = "don't track" (same as .gitignore). By default, all ignored files are shelved per-view on switch.
• [workspace] expose = "persist across views". These paths are never shelved — they stay on disk through every view switch.

atomic init seeds a default expose list with common tool configs. Build artifacts in .atomicignore are shelved automatically — no per-language configuration needed.

You can also set expose globally in ~/.atomic/config.toml so it applies to every repository on your machine:

# ~/.atomic/config.toml
[workspace]
expose = [".opencode", ".vscode", ".idea", ".claude", ".gemini"]

Global and repo-local patterns are merged — a repo can add project-specific entries without repeating the global ones.

Token-Level Diff

Atomic's CRDT semantic layer (Trunk → Branch → Leaf) tracks changes at the token level. Two agents editing different words on the same line produce independent patches that merge cleanly — Git would flag this as a conflict.

Vault — Shared Project Brain

Every repository has a vault — a versioned knowledge store that persists what your team and your agents learn across sessions. Goals, decisions, architecture context, and working memory all live in .vault/ as structured markdown with cryptographic provenance.

# Initialize the vault in your repo
atomic vault init

# Start a goal (a focused work session — human or agent)
atomic vault goal start --intent PIMO-3 --title "Fix token validation"

# Agents and humans accumulate tool results, decisions, and context
# When done, stop the goal — optionally promote it for team review
atomic vault goal stop --promote

# Add persistent project knowledge (conventions, architecture, etc.)
atomic vault memory add "Auth tokens use Ed25519 signatures, never HMAC"

# Track planned work items
atomic vault intent add --title "Migrate to async runtime" --priority high

The vault stores five kinds of content:

Everything is content-addressed and version-controlled. When an agent starts a session, it reads the vault for context. When it finishes, its learnings go back into the vault for the next session — human or machine.

Knowledge Graph — Code Intelligence at Scale

Atomic builds a knowledge graph from your entire codebase — source code content, file structure, tree-sitter entities (functions, classes, types), module hierarchy, change history, and their relationships. Search it, traverse it, visualize it, or let an LLM explore it with tools.

# Search the knowledge graph — unified structural + content search
atomic query search "replication"

# Search source code content (powered by syntext trigram index)
atomic query code "replication" -t cpp -g src/mongo/db/repl/

# List tree-sitter entities in a file (functions, classes, types)
atomic query entities src/mongo/db/repl/replication_coordinator_impl.cpp

# Explore relationships around a node (1-2 hops)
atomic query neighbors "module:src/mongo/db/repl"

# Visualize the graph — opens interactive D3 force-directed layout
atomic query graph "replication" -k 20 --depth 2

The KG contains seven node types connected by typed edges:

module:src/mongo/db/repl          ← directory-level grouping
  ├─ PART_OF ← file:replication_coordinator.h    ← tracked files
  │              ├─ DEFINES → entity:ReplicationCoordinator (class, L42-890)
  │              └─ INCLUDES → file:replication_process.h
  ├─ PART_OF ← file:bgsync.cpp
  │              └─ MODIFIES ← change:R4YQUAS2 ("fix replication lag")
  │                              ├─ AUTHORED_BY → identity:alice
  │                              └─ DEPENDS_ON → change:XMJZ3IPF
  └─ PART_OF → module:src/mongo/db  (parent module)

Search is powered by two indexes that work together: - KG FTS — searches node labels, summaries, and metadata (structural search) - syntext — trigram-indexed content search across all source files, ~20x faster than grep

Results are ranked: src/ files above tests, modules above flat files, content match counts as a signal. A bounded min-heap ensures the top N results surface from thousands of matches without sorting the full set.

For agents (Claude Code, Gemini, etc.), the CLI commands ARE the tools. An agent calls atomic query search, atomic query neighbors, atomic query entities, and its own read_file — the same path a human follows. No grep, no find, no LLM-calling-LLM overhead.

For humans on the terminal, ask provides an agentic loop with tool use:

# LLM explores the KG with tools and answers your question
atomic query ask "who fixed the auth bug?"

The ask command gives the LLM six tools (kg_search, kg_neighbors, read_file, list_entities, code_search, vault_read) and lets it decide what to look up. Provider-agnostic — works with Anthropic or OpenAI. Set ANTHROPIC_API_KEY or OPENAI_API_KEY to enable.

No API key required for search, code, entities, neighbors, graph, or enrich.

Quick Start

# Initialize a new repository
atomic init

# Add files and record a change
atomic add src/
atomic record -m "Initial commit"

# Enable AI agent hooks
atomic agent enable

# Create a view
atomic view create feature-x

# Push to a remote
atomic push origin

Key Concepts

Patch Theory

Changes are composable, commutative operations on a directed graph:

• Merging A then B gives the same result as merging B then A (when no conflicts)
• Every change has a well-defined inverse
• Conflicts are represented as data, not failures

The Repository Graph

Files are directed acyclic graphs (DAGs) where vertices hold content chunks, edges define ordering, and changes are transformations that add or remove vertices and edges. This is not a commit graph — it's the actual file structure.

Dual-Layer Architecture

Every change stores two parallel representations:

• Graph layer — Content-addressed nodes and edges for mathematically sound merging
• Semantic layer — Files (Trunk), Lines (Branch), Tokens (Leaf) for human-readable diffs and token-level blame

CLI Reference

Core Commands

Query Commands

View Commands

Remote Commands

Tag Commands