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:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗