Browse by type
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.
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?"
| 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 |
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)
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.
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.
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.
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.
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
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.
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.
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.
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 |
browse all types & interfaces →
$ claude mcp add atomic \
-- python -m otcore.mcp_server <graph>