MCPcopy Create free account
hub / github.com/atomicdotdev/atomic

github.com/atomicdotdev/atomic

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.22.1 ↗ · + Follow · compare 26 versions
27,704 symbols 138,640 edges 1,159 files 7,439 documented · 27% ● updated 2mo agov0.17.1 · 2026-08-25★ 881 open issues

Browse by type

⨍ Functions 25,138◇ Types & classes 2,566
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

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.

The Git causal shim is temporarily supported on Unix only (Linux and macOS). Windows shim support is deferred while its platform contract is defined; native Atomic functionality continues to be tested on Windows. See the temporary platform policy for the CI scope and requirements for re-enabling Windows shim tests.

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

Git Atomic
Change model Line-based diffs Patch theory — composable operations on a DAG
AI attribution None — commits say "Co-authored-by" in prose Every change records model, provider, session, tokens, and cost
Provenance Not tracked Causal decision graph: goal → exploration → commitment → verification
Attestation Not tracked Session-level audit nodes with cost, token breakdown, and change coverage
Turn recording Manual commits or wrapper scripts Automatic — each agent turn is a change with full metadata
Agent isolation Branches diverge and need merging Views are filtered perspectives of the same graph — isolated agent work, zero-orphan cleanup
Conflict granularity Whole lines Token-level — two agents editing different tokens on the same line don't conflict
Identity Name + email string Ed25519 cryptographic identity with agent delegation scopes
Merge correctness Heuristic 3-way merge Mathematical — commutative when changes are independent, precise when they're not
Rename tracking Heuristic similarity matching Structural — inodes survive renames across the entire history

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 access through libatomic

CLI repository operations, including agent provenance recording, use the libatomic service handlers. The default mode (ATOMIC_SERVICE=local) runs those handlers inside the CLI process, without starting a background owner or creating a socket. Graph, views, sessions, vault, and the provenance journal share .atomic/atomic.redb.

With ATOMIC_SERVICE=reactor, the CLI calls the same handlers through the separate atomicd service over a Unix socket. Reactor mode still requires its socket and does not fall back to local execution if the service is unavailable. ATOMIC_RPC=1 is the legacy alias for Reactor mode; an explicit ATOMIC_SERVICE=local or reactor takes precedence. Use the same mode for commands accessing a repository; do not mix local access with an active Reactor service accessing that repository.

The old per-repository atomic agent database-owner command, its changes-owner.lock election, and its /tmp/atomic-owner-*.sock endpoints have been removed from the current CLI. Processes started by an older binary can still be running after an upgrade. Stop them using the steps below.

The official installer keeps complete native releases in separate versioned directories and exposes atomic through a command symlink. Its installation record keeps that command's absolute path in install_path and the complete native release directory in runtime_dir. atomic update verifies that the recorded command still resolves to the running executable, then preserves the original command directory in its upgrade instructions instead of targeting the immutable release directory. Restart editors to adopt a newly registered runtime; do not remove an older release while a process still uses its library.

Upgrading from legacy database owners (0.19.1 and earlier)

Replacing the executable does not stop existing processes. Before upgrading, pause agent hooks and let active Atomic commands finish. Keep hooks paused through cleanup and installation. These macOS/Linux steps also work when you cannot locate the original repository, including test or workshop repositories created under /tmp.

List Atomic processes belonging to your user:

pgrep -u "$(id -u)" -x atomic

Once active work has finished, stop those processes with SIGTERM:

pkill -TERM -u "$(id -u)" -x atomic

This stops all processes named exactly atomic belonging to your user, across repositories and versions. It does not match atomicd or another user's processes. Coordinate with other users if their old processes are also running. If you know the repository and still have the old executable, you can instead request its owner's shutdown with that executable:

/path/to/old/atomic agent database-owner shutdown --repository /path/to/repo

Check again and wait until no matching processes remain:

pgrep -u "$(id -u)" -x atomic

No output with exit status 1 means no matches; other errors need investigation. Do not continue while PIDs are still listed. pkill also returns 1 if there were no matching processes.

After the old processes have exited, list leftover legacy sockets owned by your user:

find /tmp/ -maxdepth 1 -type s -user "$(id -un)" -name 'atomic-owner-*.sock' -print

Then remove those leftover sockets:

find /tmp/ -maxdepth 1 -type s -user "$(id -un)" -name 'atomic-owner-*.sock' -exec rm {} +

Socket removal does not stop a running owner or release its database lock. Leave .atomic/changes-owner.lock and database files in place; the OS releases process locks when the owner exits. These commands only remove legacy socket files, not Reactor's atomicd.sock. Run them as your normal user, without sudo.

Now rerun your installer and check atomic --version before resuming hooks. For repositories using .atomic/pristine.redb and .atomic/changes.redb, the first open by the newer CLI merges them into .atomic/atomic.redb, verifies the copied tables, and archives the old files under .atomic/legacy/<timestamp>/. If you already replaced the binary, the process-stop and socket-cleanup steps still apply; the new CLI no longer has the old database-owner shutdown command.

Reclaiming unused database space

Run explicit maintenance when the repository is quiet:

atomic compact
atomic compact --repository /path/to/repo --json

The command compacts the existing .atomic/atomic.redb and reports its before/after sizes and reclaimed bytes. It preserves history, views, provenance, change files and unrecorded working files. It does not delete live data or deduplicate change objects; zero bytes reclaimed is a valid result.

Compaction runs through libatomic, in-process by default. With ATOMIC_SERVICE=reactor, it uses the same handler through the configured Reactor service; that service must advertise CompactDatabase. An older or unavailable service produces an error, with no local fallback.

Other database readers and writers must release their handles. Lock waiting uses ATOMIC_DB_LOCK_WAIT_MS (30 seconds by default); a busy database produces an error that can be retried. Once blocking maintenance starts, it finishes independently of the caller, including the bounded lock wait. Use a quiet period: other commands may time out while the database is being compacted. Persistent savepoints block compaction and are never deleted automatically.

This is manual maintenance of an existing combined database, with no implicit initialization or migration. Hosted Storage's open-handle cache requires separate maintenance coordination before online compaction can be supported.

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 or merge commits.

# 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 (prompts if any changes would be orphaned)
atomic view delete agent-ses_3781fc7a6ffet5c6r1ILy1BEbv

atomic view split <name> --last N moves changes out of the source into a new draft and asks you to acknowledge the risks. Use --dry-run to preview, or --confirm to acknowledge them non-interactively.

Deleting a draft checks for changes that would lose their last local view reference, shows their hashes, and requires confirmation. Those changes become invisible in all views; they do not automatically return to the source. Insert them elsewhere before deleting to keep them referenced. --force skips the deletion prompt.

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.
File .atomicignore expose On view switch
.opencode/, .vscode/ ✓ ✓ Left alone — persists across views
node_modules/, target/ ✓ ✗ Shelved per view (O(1) rename)
src/main.rs ✗ — Tracked — materialized from the graph

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.

Vault writes — atomic vault goal start/stop/resume, atomic vault materialize, atomic vault sync, atomic intent new/update/delete/link/attest, and atomic memory new/write/attest — create the vault on first use if it does not exist yet. Reads never mutate the checkout: on a repository without a vault they return empty/not-found, so read-only checkouts keep working. atomic vault init is only needed when you want the defaults created and recorded up front, for example after atomic init --no-vault.

# 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:

Entry Type What It Captures
Goals Work sessions — each tracks a developer/agent, linked intent, model, status, and tool results
Intents Planned work items with priority, status, assignee, and labels
Memory Persistent knowledge — architecture decisions, conventions, re

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 16,507
Method 8,631
Class 1,905
Enum 557
Interface 104

Languages

Rust99%
Python1%
TypeScript1%

Modules by API surface

atomic-cli/src/commands/git/parallel.rs252 symbols
atomic-cli/src/commands/rpc.rs170 symbols
atomic-repository/src/repository/operation.rs157 symbols
atomic-cli/src/commands/diff/tests.rs142 symbols
atomic-core/src/pristine/txn/read.rs135 symbols
atomic-agent/src/record/tests.rs123 symbols
atomic-agent/src/turn/session.rs121 symbols
atomic-core/src/change/attestation.rs120 symbols
libatomic/src/daemon/services_agent.rs119 symbols
atomic-core/src/operation/codec.rs119 symbols
atomic-repository/src/status.rs116 symbols
atomic-agent/src/provenance/classify.rs116 symbols

Dependencies from manifests, versioned

@opencode-ai/pluginlatest · 1×
@types/bunlatest · 1×
typescript5.7.0 · 1×

Datastores touched

mydbDatabase · 1 repos
appDatabase · 1 repos
atomic_storageDatabase · 1 repos

For agents

$ claude mcp add atomic \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page