Skip to main content

AI Agent Workflows with Atomic

Atomic has built-in support for AI coding agents. When enabled, every agent turn is automatically recorded as an Atomic change with full provenance — model, provider, tokens, cost, session tracking, and a causal decision graph explaining why the agent made each change.

No manual flags. No wrapper scripts. No environment variables.

Quick Start​

1. Enable Agent Hooks​

# Auto-detect which agent is present
atomic agent enable

# Or target a specific agent
atomic agent enable --agent claude-code
atomic agent enable --agent opencode
atomic agent enable --agent gemini-cli

This installs hooks into the agent's configuration file. The hooks call back to atomic agent hooks <agent> <verb> on each lifecycle event.

2. Work Normally​

Use your agent as you always do. Atomic hooks fire automatically:

  • Session start → creates an isolated agent stack forked from your current stack
  • User prompt → records a Goal node in the provenance graph
  • Each tool call → records Exploration, Commitment, or Verification nodes
  • Turn end → runs status → add → record, saves a provenance graph
  • Session end → creates an attestation, switches back to your stack

3. Review What Happened​

# See the recorded changes with AI provenance
atomic log

# Check session and hook status
atomic agent status --verbose

# Inspect attestations (cost, tokens, model breakdown)
atomic agent attest

# View details for a specific attestation
atomic agent attest --hash XMJZ3IPF

# Generate AI reasoning summaries
atomic agent explain <session-id> --all --save

What Gets Recorded​

Every agent turn produces an Atomic change containing:

DataLocationDescription
Change headerhashed.headerMessage, author (e.g., claude+60f5 <you@dev>), timestamp
Provenancehashed.provenanceModel, provider, session ID, turn number
Session envelopehashed.metadataTurn timing, files touched, agent identity
Graph operationshashed.atomsThe actual content changes (vertices + edges)
Semantic operationshashed.file_opsLine and token-level operations for human-readable diffs
TranscriptunhashedCondensed conversation (redactable, doesn't affect hash)

Because provenance and the session envelope are in the hashed section, they're part of the change's cryptographic identity. Tampering with attribution changes the hash.

How Agent Recording Works​

You prompt Claude Code → agent reads files, makes edits, runs tests
                                          │
                         hooks fire on each tool call
                                          │
                                          ▼
                              TurnOrchestrator
                                ├── Appends nodes to ProvenanceAccumulator
                                │     (Goal, Exploration, Commitment, Verification)
                                │
                                ▼
                           Agent goes idle (turn end)
                                │
                         ┌──────┴──────┐
                         │  record_turn │
                         │  ├── status  │
                         │  ├── add     │
                         │  └── record  │
                         └──────┬──────┘
                                │
                         ┌──────┴──────────────────┐
                         │  Save ProvenanceGraph     │
                         │  ├── PatchProposal node   │
                         │  ├── Convert to postcard  │
                         │  └── Content-address hash │
                         └──────┬──────────────────┘
                                │
                                ▼
                    .atomic/changes/AB/ABC123.change
                    .atomic/changes/XM/XMJZ3I.provenance

Each hook invocation is a separate process — no daemon required. The provenance accumulator is persisted to .atomic/sessions/{session_id}/graph.json between invocations using atomic writes (temp file + rename).

Agent Isolation with Stacks​

When a session starts, Atomic automatically creates an isolated agent stack forked from the current stack:

  dev  (Shared — your working stack)
    │
    └── agent-ses_3781fc7a... (Local, parent: dev)
          ├── Turn 1: Change ABC123
          ├── Turn 2: Change DEF456
          └── Turn 3: Change GHI789

The agent stack uses the two-tier graph model:

  • Agent edges are stored in STACK_GRAPH (local, ephemeral)
  • Parent stack edges are in GRAPH (shared, permanent)
  • The agent sees the union of both — full project context with isolated changes

When the session ends, Atomic switches back to your original stack. You then decide what to promote:

# Apply specific changes from the agent stack to dev
atomic apply <change-hash> --to dev

# Or apply the most recent change
atomic apply @~1 --to dev

# Delete the agent stack — cascade-deletes its edges, zero orphans
atomic stack delete agent-ses_3781fc7a...

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)

Tool calls are classified automatically by a rule-based classifier:

ToolClassification
read, grep, glob, list_directoryExploration — read-only understanding
edit, write, edit_file, create_fileCommitment — file-modifying actions
bash with test, check, lintVerification — validation
bash with install, buildExecution — non-test commands

Causal edges are inferred automatically: explorations link to the current goal, commitments link to preceding explorations, verifications link to the last commitment.

Provenance graphs are content-addressed and pushed to remotes alongside the changes they explain. Your team can review not just the code, but the agent's reasoning.

→ Learn more about Provenance Graphs

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.27 · 3 changes covered · 20.5k tokens

Attestations are enriched with real data from the provenance entries embedded in each covered change:

  • Model name and provider from change provenance
  • Token counts (input, output, cache read/write) aggregated per model
  • Cost in USD aggregated across all models
  • Lines added/removed computed from the CRDT semantic layer
  • Wall duration from session timestamps

For resumed sessions, the new attestation chains to the previous one via previous_attestation, ensuring every change is covered exactly once.

→ Learn more about Attestations

Agent Identity​

Agent changes are attributed using Ed25519 signatures with a +tag email format:

User identity:    Lee Faus <lee@atomic.dev>
Agent author:     claude+60f5 <lee@atomic.dev>

The +tag is a short hash of the session ID — every agent turn traces back to a specific session and a specific human who initiated it.

AgentExample Author
Claude Codeclaude+60f5 <lee@atomic.dev>
Gemini CLIgemini+abcd <lee@atomic.dev>
OpenCodeopencode+9876 <lee@atomic.dev>

Supported Agents​

AgentConfig LocationHook SystemHow Hooks Are Installed
Claude Code.claude/settings.jsonNative hooksWrites hook entries into settings JSON
Gemini CLI.gemini/settings.jsonNative hooksWrites hook entries into settings JSON
OpenCode.opencode/plugins/atomic/Plugin-basedCopies TypeScript plugin to plugins directory

All three agents share the same Rust-side orchestrator (TurnOrchestrator). The only difference is how hooks are installed and how events are parsed — each agent has an AgentHook adapter that normalizes events into common TurnEvent values.

Global Installation​

For agents that support global settings (Claude Code, Gemini CLI), you can install hooks once for all projects:

atomic agent enable --global --agent claude-code

Pushing Agent Data​

When you push changes, Atomic automatically uploads attestations and provenance graphs:

$ atomic push origin

  ✓ Pushed 3 changes
  ✓ XMJZ3IPF attestation ($0.15, 3 covered)
  ✓ ABC12345 provenance (7 nodes, 1 change)
  ✓ DEF67890 provenance (12 nodes, 1 change)

Attestations are only uploaded when all their covered changes have been pushed. Provenance graphs are only uploaded when all their explained changes have been pushed. This ensures the server never references data it doesn't have.

Differences from Git​

GitAtomic
AI attributionCo-authored-by trailer (prose)Structured provenance in hashed change data
Cost trackingNot possiblePer-model token and cost breakdown in attestations
Agent reasoningNot trackedCausal provenance graph (goal → exploration → commitment)
Turn recordingManual git commit or wrapper scriptsAutomatic on each turn end
Agent isolationBranches (diverge, need merging)Stacks (views of same graph, zero-orphan cleanup)
Conflict granularityWhole linesToken-level (two agents editing different tokens on same line merge cleanly)
IdentityName + email stringEd25519 cryptographic identity with delegation

Best Practices​

Let Atomic Handle Recording​

Don't run atomic record manually during agent sessions — the hooks do this automatically on each turn end. Manual recording can interfere with the session state machine.

Review Before Promoting​

Agent changes live on an isolated stack. Review them before applying to your shared stack:

# See what the agent changed
atomic log --stack agent-ses_3781fc...

# Diff against the parent
atomic diff --stack agent-ses_3781fc...

# Apply only the changes you want
atomic apply <hash> --to dev

Use Explain for Complex Sessions​

For long or complex sessions, generate reasoning summaries:

# Generate reasoning for all turns and save to the changes
atomic agent explain <session-id> --all --save

This stores structured reasoning (intent, outcome, learnings, friction) in the change's unhashed section and appends learnings to the agent's context file (CLAUDE.md, GEMINI.md, or opencode.md).

Check Attestations Before Code Review​

Attestations give reviewers context about the AI session that produced the code:

$ atomic agent attest --hash XMJZ3IPF --verbose

# Shows: model, tokens, cost, duration, files changed, coverage per stack

This is especially useful when reviewing pull requests — you can see exactly how much AI assistance was involved and what model was used.

Troubleshooting​

Agent Hooks Not Firing​

# Check if hooks are installed
atomic agent status

# Reinstall hooks
atomic agent enable --force

Session Not Recording Changes​

The state machine requires TurnStart (user prompt) before TurnEnd (stop) will trigger recording. If you see "Turn N had no changes — skipping record" in stderr, the agent didn't modify any files during that turn. This is normal for read-only turns.

Attestation Shows Zero Cost/Tokens​

If the attestation shows $0.00 and 0 tokens, the provenance entries in the changes may not have token/cost data. This happens when the agent doesn't report usage metrics through its hook payload. The attestation will still show the correct model name, changes covered, and lines changed.

Agent Stack Not Created​

If the agent stack wasn't created (e.g., repository couldn't be opened), recording still works — it just records to the current stack instead of an isolated one. Check stderr output for warnings.

Next Steps​