Atomic

A Semantic Change Graph (SCG) to track memory, intent, provenance, and change as a single unit of work. This is the evolution of source code management in the era of agents and agentic coding.

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 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, Codex, Antigravity CLI, 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)

Repository owner locks and connection recovery

Agent hooks are short-lived processes, while redb permits only one writable process to open a database. Atomic therefore starts one long-lived database owner per canonical repository. Hooks send committed provenance requests to that owner instead of opening the repository's redb change store directly.

Each repository has an independent ownership namespace:

These runtime resources do not require sudo. The owner process runs as the current user: it creates the repository lock and database under the user-writable .atomic directory and creates its Unix socket in /tmp, which is a shared, sticky-bit-protected runtime directory. Elevated privileges are only needed when installing or replacing the atomic executable in a system-owned prefix such as /usr/local/bin; they are unrelated to socket creation or owner election.

The endpoint digest is derived from the canonical .atomic path and uses 96 bits of BLAKE3 output. Different project paths therefore get different owners, locks, databases, and endpoints. Multiple agents working in one project intentionally share that project's owner; agents working in other projects use different owners and proceed independently. Agent sandboxes and symlinked paths resolve back to the canonical repository, so they share its owner rather than creating competing databases. A clone at a different path gets its own owner.

Agent A ─┐                         Agent C ─┐
Agent B ─┴─> Project 1 owner       Agent D ─┴─> Project 2 owner
                 │                                  │
                 v                                  v
       Project 1 changes.redb             Project 2 changes.redb

The lock is the authority; the socket or named pipe is only transport. The lock file may remain on disk after normal operation, but an unlocked file does not block a new owner. If an owner crashes, the OS releases its lock automatically. Recovery then proceeds as follows:

1. A hook cannot reach the old endpoint and starts or reconnects to an owner.
2. Owner candidates race for that repository's changes-owner.lock.
3. Only the lock winner may open changes.redb.
4. On Unix, the winner removes any stale socket left by the dead owner and binds a fresh endpoint.
5. The hook retries with the same request/event ID, so a request committed before the crash is acknowledged once rather than applied twice.

Within one repository, redb write transactions are serialized by design, while reads and independent repositories can proceed concurrently. Startup, reconnect, and retry loops are bounded so a broken owner fails instead of hanging hooks indefinitely. Checkpoint attempts, event cutoffs, and fencing generations let interrupted turns resume without rewriting completed session turns.

Current operational considerations:

• Owners remain alive until explicitly shut down; an idle timeout or user-level owner registry is a future resource-management improvement for machines that touch many repositories.
• Unix endpoints use /tmp to stay below macOS Unix-socket path limits. A future hardening step should move them into a user-private runtime directory where available, enforce restrictive socket permissions, and validate peer credentials.
• A 96-bit endpoint digest makes accidental cross-project collisions extraordinarily unlikely, but the repository-local lock remains the final ownership check.

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", ".agents"]

• .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", ".agents"]

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 `