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 atomicOnce active work has finished, stop those processes with SIGTERM:
pkill -TERM -u "$(id -u)" -x atomicThis 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/repoCheck again and wait until no matching processes remain:
pgrep -u "$(id -u)" -x atomicNo 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' -printThen 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 --jsonThe 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 tokensAgents 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_3781fc7a6ffet5c6r1ILy1BEbvatomic 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 highThe 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, reference material |
| Skills | Reusable capability definitions for agents |
| Scratch | Temporary notes and working state |
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.
Colocated repositories that track .vault/ in Git: atomic git import preserves
your tracked vault files byte-for-byte (it hydrates the vault database from them;
default templates are only created for a repository that has no .vault/ at all).
The first import records the vault's shim policy — [git.shim] vault = "tracked"
in .atomic/config.toml — so the vault participates in Git equivalence and
publication checks exactly like any other tracked path. A repository whose Git tree
does not track .vault/ keeps the vault private and ignored by Git.
Rolling Git import (default for fresh repositories): in a fresh, checked-out
Git repository, atomic git import imports first-parent history with a live dashboard
when running in a terminal. The responsive Ratatui dashboard shows progress,
staging throughput/ETA, CPU and memory history, and the rolling window separately.
The ETA excludes final verification. Use --stream-window-mib 128 to raise the default
32 MiB limit on queued Git blob reservations and prepared batches (1–256 MiB).
This is not a limit on total process memory. Read-ahead is capped at 500 commits;
publication batches are capped at 100 commits and the byte budget. The stream
imports graph-only changes with zero FileOps and verifies the final Git tree,
not every historical graph state. Git does not capture Atomic CRDT history, so
streaming does not synthesize historical identities. Native/incremental handoff
from graph-only imports remains a separate limitation; use the ordinary importer
when you need its semantic lifecycle support.
Unsupported history is refused rather than silently falling back: use
--no-stream for the ordinary importer where supported. Streaming shares the
ordinary parser's raw-name, symlink and gitlink support; these are not rejected
merely for using the streaming route.
--all, --incremental, --with-crdt and existing-repository imports retain
their ordinary path. Explicit --stream remains available for requiring the
restricted fresh-import route.
Atomic's workflow knowledge graph connects intents, sessions, turns, provenance, attestations, changes, files, and views, alongside goals and memories. It is a deterministic, rebuildable read model: recorded changes, session ledgers, provenance sidecars, attestations, and vault objects remain authoritative.
Workflow relationships use the canonical atomic: namespace
(https://atomic.dev/ns/workflow#). For example:
Session ──atomic:hasTurn───────────▶ Turn
Turn ──atomic:hasPlan───────────▶ Intent
Turn ──atomic:generatedChange───▶ Change
Turn ──atomic:turnExplainedBy───▶ ProvenanceGraph
Change ──atomic:implements───────▶ Intent
Change ──atomic:changeExplainedBy─▶ ProvenanceGraph
Change ──atomic:attestedBy────────▶ Attestation
Attestation ──atomic:coversChange──────▶ Change
Change ──atomic:modifiesFile──────▶ File
Change ──atomic:directlyOnView────▶ View
These links reflect captured facts, not guessed historical associations. Missing
facts produce explicit gap findings. atomic:directlyOnView means a view's own
change membership, not visibility inherited from ancestors or dependencies.
Resources have canonical IRIs: local workflow resources are qualified by the
repository's stable ProjectId, while changes, provenance graphs, and session
attestations use full, algorithm-qualified content hashes. JSON nodes carry
asserted class IRIs in types, and edge kind values are absolute predicate IRIs.
Copy resource IDs from search or graph JSON rather than constructing legacy
file:…, entity:…, or abbreviated change:… IDs.
# Refresh workflow facts from recorded changes, files, and views
atomic query enrich
# Search workflow resources, with indexed source-content matches
atomic query search "replication"
# Explore a resource's asserted relationships (1–2 hops)
atomic query neighbors "<resource-iri-from-search>" --json
# Visualize a search neighborhood in an interactive HTML graph
atomic query graph "replication" -k 20 --depth 2
# Inspect an intent's lineage and dependency closure, not a generic neighborhood
atomic intent graph ATOM::alice::1 --htmlIntent graphs distinguish captured and explicitly declared implementation from changes that merely record the intent artifact, and report truncation and missing resources. Change, intent, and view nodes also expose recorded AI usage summaries, with cost/token coverage and model attribution; missing usage is not assumed to be free. See Intent semantic change graphs for scope and accounting details.
Code structure is queried live, not persisted in the workflow KG. Tree-sitter provides entities and caller relationships on demand; module, call, definition, and import edges are not stored as a parallel code graph.
# Build/update the separate syntext source-content index
atomic query index
# Search recorded source in the current view; -t filters language and -g paths
atomic query code "replication" -t rs -g atomic-core/src/
# Parse a file's functions, classes, and types with line ranges
atomic query entities atomic-core/src/kg/iri.rs
# Find callers by path-qualified symbol or bare name in the recorded view
atomic query callers "atomic-core/src/kg/iri.rs#mint_change" --jsonquery search, query callers, and query code use the current view's effective
graph filter: the view's changes, all ancestor views, and transitive dependencies.
They read recorded source bytes, not unrecorded working-copy edits or stale content
from another view. Deletions and renames follow the canonical view projection.
Vault-only results, such as memories and intents, remain shared.
Search combines KG full-text search over resource IDs, labels, and summaries
with source-content matches verified against the recorded view. Filtering precedes
ranking and limits; no working-copy content index or checkout is required. Callers
use request-scoped tree-sitter parsing, not persisted KG code edges. This
correctness-first path renders/scans the selected view per query. RPC clients can
select a view explicitly; omitting it uses the working copy's registered desired
view. Other query verbs retain their existing scope semantics. The agent tool
loop's code_search and kg_search read the same recorded view. The separate
working-copy content index remains only for its maintenance consumers — Git
import refresh and post-record index updates — and no search path consults it.
Existing ambient ignore rules still suppress ignored paths, including recorded
files; that policy is intentional and unchanged.
Recorded code search applies path/type filters before reading file contents, then scans eligible files one at a time. It keeps at most the requested number of best matches while still counting every match and directory facet—even with a zero display limit. Facet-count ties sort by directory path. Rendered files over 10 MiB are skipped, not searched as truncated files. Closure, path-claim, and inode attribute validation still precede request filtering: invalid global metadata fails closed, while content-only errors in excluded files are deliberately unread. Selected-file content errors still propagate. No persistent cache or reindex is required. See query resource diagnostics for memory bounds, costs excluded from those bounds, and a reproducible benchmark.
For query search, --kind matches an exact, case-sensitive absolute class IRI
against any asserted type, before candidate-pool truncation. An omitted or
empty kind means no filter; an unknown class matches nothing. --pool defaults
to 5000 and is a retention budget, normalized to at least the result limit—not a
cap on which eligible candidates are examined. Without a kind filter, a larger
pool enables cross-type diversity. With a kind filter, results are the highest-
ranked matching nodes without cross-type diversity, so even --pool 1 cannot hide
their top result. CLI/service search defaults to 10 results; a service request
limit of zero (including CLI --limit 0) uses that default. Direct repository
search APIs instead interpret a zero limit literally and return no nodes.
SHACL validation runs locally in the CLI using PurRDF. Builtin profiles and
enterprise-authored .atomic/shapes/*.ttl files use the same engine:
# Validate the asserted workflow snapshot (default projection profile)
atomic query validate --format json
# Apply the stricter managed-plan, provenance, and verified-attestation checks
atomic query validate --profile publication --format json
# Explicitly rebuild the complete derived workflow graph, including vault entries
atomic query reindex --fullThe projection profile permits a missing shortcut only with its matching gap finding. Reports include snapshot/profile identity, target coverage, and standard validation results. Conformance with no applicable targets is vacuous, not proof of complete history. Exit codes are 0 for conformance, 1 for violations, and 3 for shape or engine errors. Imports resolve only among explicitly loaded shape bundles, without implicit network fetching.
Phase 1 does not enable OWL inference or mandatory validation hooks on sync or publication. Signature verification remains separate from SHACL. See the KG upgrade guide for the breaking API changes and migration behavior.
Agents can use the same CLI queries directly. For interactive natural-language
questions, ask provides an LLM tool-use loop:
atomic query ask "who fixed the auth bug?"The model can search workflow facts, inspect source files, parse entities, and read
vault entries. Set ANTHROPIC_API_KEY or OPENAI_API_KEY to enable it. Answers are
model-generated interpretations, not machine-validated historical audit evidence.
No LLM API key is required for search, code, entities, callers, neighbors,
graph, enrich, index, reindex, or validate.
# 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 originChanges are composable, commutative operations on a directed graph:
- Merging
AthenBgives the same result as mergingBthenA(when no conflicts) - Every change has a well-defined inverse
- Conflicts are represented as data, not failures
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.
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
| Command | Description |
|---|---|
atomic init |
Initialize a new repository |
atomic add <paths> |
Add files to tracking |
atomic remove <paths> |
Stop tracking files (git rm semantics: untracking recorded content needs a recorded delete) |
atomic move <src> <dst> |
Move or rename tracked files |
atomic status |
Show working copy status |
atomic diff |
Show differences in working copy |
atomic record -m "msg" |
Record changes to the repository |
atomic revise |
Modify a change in-place |
atomic log |
Show change history |
atomic change [hash] |
Show details for a specific change |
| Command | Description |
|---|---|
atomic query search <query> |
Search the knowledge graph (structural + content) |
atomic query code <pattern> |
Search recorded source in the current view (-t for file type, -g for path filter) |
atomic query entities <path> |
List tree-sitter entities in a file (functions, classes, types with line ranges) |
atomic query callers <path#name|name> |
Find callers using live source parsing, without stored KG code edges |
atomic query neighbors <resource-iri> |
Explore asserted workflow relationships around a canonical resource |
atomic query graph <query> |
Visualize the workflow graph as interactive HTML (-k seeds, --depth, --kinds with class IRIs) |
atomic query ask <question> |
Natural-language Q&A with agentic tool loop (requires API key) |
atomic query enrich |
Refresh VCS workflow facts (changes, files, views) |
atomic query index |
Build/update the content search index (--rebuild for full, --stats for info) |
atomic query reindex [--full] |
Reproject vault entries; --full rebuilds the complete derived workflow graph |
atomic query validate |
Run builtin and local enterprise SHACL shapes (--profile projection|publication, --format json) |
| Command | Description |
|---|---|
atomic view create <name> |
Create a new view (--draft for isolated, --parent to set parent) |
atomic view switch <name> |
Switch to a view |
atomic view list |
List all views (--verbose for scope and parent) |
atomic view split <name> |
Move selected changes into a new draft (confirmation required; --last N, --dry-run, --confirm) |
atomic view delete <name> |
Delete a draft; confirm if changes would be orphaned (--force skips the prompt) |
atomic split <name> |
Create a new view from the current one |
atomic stash |
Temporarily save uncommitted changes |
| Command | Description |
|---|---|
atomic push [remote] |
Push changes to a remote |
atomic pull [remote] |
Pull changes from a remote |
atomic clone <url> |
Clone a remote repository |
atomic remote add <name> <url> |
Add a named remote |
atomic remote remove <name> |
Remove a named remote |
atomic remote set-url <name> <url> |
Change a remote's URL |
atomic remote default <name> |
Set the default remote |
| Command | Description |
|---|---|
atomic tag create <name> |
Create a named state snapshot |
atomic tag list |
List all tags |
atomic tag show <name> |
Show tag details |
atomic tag delete <name> |
Delete a tag |
| Command | Description |
|---|---|
atomic identity new <name> |
Create a new Ed25519 identity |
atomic identity list |
List all identities |
atomic identity whoami |
Show the current default identity |
atomic identity show <name> |
Show identity details |
atomic identity delete <name> |
Delete an identity |
| Command | Description |
|---|---|
atomic agent enable |
Install agent hooks (auto-detect or --agent claude-code) |
atomic agent disable |
Remove agent hooks |
atomic agent status |
Show sessions, hook liveness, and failures (--json for tooling) |
atomic agent explain <id> |
Generate AI reasoning summary for a session |
atomic agent attest |
List and inspect attestations |
atomic diagnostics |
Read-only support report: version, integrations, skills, hooks, Git shim, repository counts and selected redb table statistics (--json) |
Hook health is computed from session-scoped logs, so concurrent agents retain their own outcomes and a child's success cannot hide a parent's failure. See Hook Health and Session Logs for diagnosis, JSON fields, and parent-session correlation.
| Command | Description |
|---|---|
atomic vault init |
Initialize the vault in an existing repository |
atomic vault goal start |
Start a new goal (work session) |
atomic vault goal stop |
End the current goal (--promote for team review) |
atomic vault goal list |
List goals |
atomic vault intent add |
Create a planned work item |
atomic vault intent list |
List intents |
atomic vault memory add |
Add persistent project knowledge |
atomic vault memory list |
List memory entries |
atomic vault list |
List all vault entries (filter with --type) |
atomic vault show <path> |
Print a vault entry's content |
atomic vault sync |
Sync vault entries between disk and database |
| Agent | Config | Hook System |
|---|---|---|
| Claude Code | .claude/settings.json |
Native hooks |
| Codex | ~/.codex/hooks.json |
Native hooks, including terminal SessionEnd |
Antigravity CLI (agy) |
~/.gemini/config/plugins/atomic/ |
Plugin hooks |
| Gemini CLI (deprecated) | .gemini/settings.json |
Native hooks |
| OpenCode | .opencode/plugins/atomic/ |
Plugin-based |
Full documentation at docs.atomic.dev.
- Getting Started — Installation and first repository
- Concepts — How Atomic works under the hood
- Agent Integration — Setting up AI agent hooks
- Command Reference — Complete CLI reference
- AGENTS.md — Development guide for contributors and AI agents
- Portable provenance exports — Optional DSSE export and pinned-key reviewer workflow
If replacing an older binary, first follow the legacy upgrade steps.
Source builds require Rust 1.98 or newer (including the SHACL dependencies).
rust-toolchain.toml pins the supported development toolchain. Use rustup's
cargo/rustc shims, not an older standalone Homebrew Rust installation:
rustup toolchain install 1.98.0 --profile minimal --component rustfmt --component clippy
export PATH="$HOME/.cargo/bin:$PATH"
rustup show active-toolchain
rustc --version
cargo build -rIf Cargo still reports rustc 1.97.1, inspect type -a cargo rustc: a direct
/opt/homebrew/bin/cargo or rustc ahead of ~/.cargo/bin bypasses rustup and
the repository pin. Put the export above after Homebrew's PATH setup in your
shell configuration. Do not lower rust-version or use --ignore-rust-version:
the dependency itself requires the newer compiler. For a one-command build
without changing the shell configuration:
PATH="$HOME/.cargo/bin:$PATH" cargo build -rAlso check for explicit RUSTC, RUSTDOC, RUSTUP_TOOLCHAIN, or Cargo config
overrides if the shims still select the wrong compiler.
# Build all crates
cargo build --release
# Run tests
cargo test
# User-local install to ~/.cargo/bin (normally no sudo)
cargo install --path atomic-cli
# Verify installation
atomic --versionLocal builds include their source commit in the version output, for example
atomic 0.19.1 (dev 4b143dfbcad2), with -dirty appended for tracked changes.
The release workflow sets ATOMIC_BUILD_CHANNEL=release to report only the
package version. Development builds distributed later retain their embedded
commit; Git is not required to run them. When building from a source archive,
set ATOMIC_BUILD_COMMIT to the source commit, or the output shows dev unknown.
To install a locally built binary system-wide, the destination directory may require administrator privileges. On macOS, replacing the file rather than overwriting its existing inode also avoids retaining stale Gatekeeper provenance metadata:
cargo build -p atomic-cli --release
sudo rm -f /usr/local/bin/atomic
sudo cp -X target/release/atomic /usr/local/bin/atomic
sudo chmod 0755 /usr/local/bin/atomic
/usr/local/bin/atomic --versionDo not run normal Atomic commands or legacy cleanup with sudo; repository state and runtime files should remain owned by the user running Atomic.
atomic/
├── atomic-cli/ # CLI application
├── atomic-core/ # Core VCS engine (types, pristine, change, diff, CRDT)
├── atomic-agent/ # AI agent integration (hooks, turns, provenance)
├── atomic-config/ # Configuration management
├── atomic-identity/ # User identity & Ed25519 signing
└── atomic-repository/ # High-level repository operations
| Project | Location | Description |
|---|---|---|
| atomic-remote | atomic-remote/ |
HTTP client for push/pull/clone |
| atomic-docs | atomic-docs/ |
Documentation site (docs.atomic.dev) |
When several agents work a repository at once, each needs an isolated build
surface (no node_modules / target collisions) while still sharing one
history. Atomic does this with copy-on-write working trees over a single
canonical graph — no per-agent forks, no virtualized I/O.
- The working tree is cloned; the graph is not. A sandbox is a reflink
(copy-on-write) clone of the working tree — APFS
clonefile, Btrfs/XFSFICLONE, ReFS block-clone — done in-process via thereflink-copycrate. Five agents off a 200 MB base cost a few MB and run at bare-metal filesystem speed. There is exactly one pristine; a sandbox carries a small.atomic-sandboxpointer, sostatus,record,diff, andvault queryall work inside it and land in the canonical graph. - No FUSE, no virtio, no VM in the hot path. Filesystem-protocol virtualization (virtio-fs) is fatal for the metadata-heavy workloads agents run (git, cargo, npm). Copy-on-write on the real filesystem needs none of it.
# Give each agent a private, copy-on-write working tree
atomic sandbox create agent-1 --from dev # forks a per-agent draft view
atomic sandbox create agent-2 --from dev # isolated artifacts, shared graphA sandbox can be packaged as a standard OCI image (consumable by smolvm, podman, containerd — built in-process, no shelling out) for two purposes:
| Command | Shape | Purpose |
|---|---|---|
atomic sandbox stage |
layered: shared base + thin delta | inner-loop CI / circuit-breaker runs — base is pulled once and cached, only the delta ships each iteration |
atomic sandbox seal |
flattened, single self-contained layer | a deployable runtime — "run this exact version" anywhere |
# Inner-loop CI artifact: base layer (dev) + delta layer (only what changed)
atomic sandbox stage agent-1 --base dev -o ./ci-image
# Deployable runtime image of the full merged state
atomic sandbox seal dev -o ./runtime --entrypoint /app/run --env PORT=8080Both embed provenance (the view names and Merkle states) in the image annotations, so a shipped image traces back to exact graph state. The runtime is smolvm — lightweight microVMs that boot OCI images in under 200 ms — making these images the unit of work for shared-infrastructure CI and circuit-breaker workflows.
See docs/CONCURRENT-AGENT-SANDBOXES.md for the full design.
- Mathematical Soundness — Operations are well-defined transformations with provable properties
- AI-Native — Provenance, attestation, and agent identity are core concepts, not afterthoughts
- Correctness Over Speed — Validate invariants aggressively, prefer clarity over micro-optimizations
- Efficiency — O(n) file operations via inode indexing, not O(N) repository-wide scans
- Cryptographic Identity — Every change is attributable via Ed25519 signatures
Because version control should have no doubt about what changed, when, why, and who — human or machine. Every change is a well-defined, composable transformation. Atomic in the mathematical sense.
Copyright 2025-2026 Atomic Software, Co.
Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
- Website: atomic.dev
- Documentation: docs.atomic.dev
- GitHub: github.com/atomicdotdev/atomic
Atomic builds on decades of research in patch theory, drawing inspiration from academic work on categorical semantics of version control and practical implementations that explored these ideas. Thanks to the team at https://pijul.org for originating that work.