atomic agent

Manage AI agent integration for automatic turn-level recording with full provenance.

Synopsis

atomic agent <SUBCOMMAND>
atomic agent enable --agent <NAME>
atomic agent disable --agent <NAME>
atomic agent status [--verbose]
atomic agent explain <SESSION_ID> [--all] [--save]
atomic agent attest [--hash <PREFIX>] [--view <NAME>] [--verbose]
atomic agent repair <SESSION> [--verify-only]
atomic agent lifecycle <SUBCOMMAND>
atomic agent identity set|unset|show

Description

The agent command is the Atomic-side control plane for AI coding integrations. atomic agent enable --agent <name> fetches an agent-specific package — atomic-agy, atomic-claude, atomic-cline, atomic-codex, atomic-copilot, atomic-cursor, atomic-devin, atomic-grok, atomic-kilo, atomic-kiro, atomic-opencode, or atomic-pi — from Atomic storage and installs its hooks, plugins, extensions, skills, and instruction files for the host agent. Those hooks call back into atomic agent hooks <agent> <verb> so Atomic can record turns and sessions with provenance.

When an integration is active, every supported turn or task is automatically recorded as an Atomic change with full provenance, and every session produces a provenance graph (causal decision DAG) and an attestation (session-level audit node).

Each hook invocation is a standalone process. Database operations use the shared service handlers: local mode runs them in-process, and reactor mode calls the daemon.

For orchestrators driving inner agents, atomic agent lifecycle declares and tracks managed runs (leases, executor pinning, run summaries) — see agent lifecycle.

For setup steps by agent, see Installing Agent Integrations.

Subcommands

`enable`

Install an agent integration for turn-level recording.

For a registered agent, enable fetches the integration package from Atomic storage (caching it under ~/.atomic/integrations/<agent>/repo), verifies the package's required CLI version, installs its files, hooks, and skills, and writes a receipt. Nothing from the package is executed. See Installing Agent Integrations for the per-agent guide.

note

The storage-based install flow is available as of Atomic 0.12.0. Earlier releases only installed built-in adapter hooks.

# Auto-detect which agent is present in this repo
atomic agent enable

# Install a specific agent's integration
atomic agent enable --agent opencode

# Refresh to the latest package contents (overwrites even modified files)
atomic agent enable --agent opencode --force

# Install from a local package checkout (development / air-gapped)
atomic agent enable --agent opencode --from /path/to/atomic-opencode

# Install for all detected agents
atomic agent enable --all

Options:

Option	Description
`--agent <NAME>`	Target a specific agent (e.g. `opencode`, `claude-code`, `agy`, `codex`, `cursor`, `cline`, `copilot`, `devin`, `kilo`, `kiro`, `pi`)
`--force`	Overwrite files even when they look user-owned or user-modified, and re-clone the package cache
`--all`	Install for all detected agents
`--from <PATH>`	Install the integration package from a local checkout instead of syncing it from Atomic storage
`--from-skills <PATH>`	Install the skills-source package (e.g. `atomic-skills`) from a local checkout instead of syncing it from Atomic storage
`--hooks <FILE>`	Install from an integration-supplied hooks manifest file directly
`--agents-md`	Also install `AGENTS.md` into the repository root so the Atomic workflow is always-on without picking a bundled agent

What it does:

Resolves the agent to a package in the embedded registry (Atomic storage URL + view)
Clones the package on first run; reuses the cache afterward so enable works offline
Installs files (never symlinks) and merges settings via the manifest engine
Skips destinations you modified — unless --force — so your edits are safe

`disable`

Remove an agent integration, guided by its receipt. Files you modified after install are kept and reported; Atomic's hook commands are stripped from shared settings files while your own hooks are preserved. Non-Atomic hooks are never touched.

# Disable for the auto-detected agent
atomic agent disable

# Disable a specific agent's integration
atomic agent disable --agent opencode

# Remove every integration that has a receipt
atomic agent disable --all

Options:

Option	Description
`--agent <NAME>`	Target a specific agent
`--all`	Remove all installed integrations
`--hooks <FILE>`	Remove hooks described by an integration-supplied manifest file

`status`

Show agent integration status, sessions, hook liveness, and failures.

# Show status
atomic agent status

# Show verbose status with session details
atomic agent status --verbose

# Inspect session-scoped hook outcomes as JSON
atomic agent status --json

Options:

Option	Description
`--verbose`, `-v`	Show detailed session information, including phase, prompt, and touched files
`--json`	Emit machine-readable installation, session, hook-health, and error data

Output includes:

Installed agents and hook status
Active and ended sessions with turn counts
The last successful hook dispatch and its age relative to the current time
Outstanding failing verbs, attributed to their sessions and parents
Grouped errors from the bounded plugin/git-shadow error-log tail

Health is derived from session-scoped operational logs. A successful child cannot clear a parent's failure, and concurrent hook processes retain their own observations.

Hook-health JSON fields:

Field	Description
`hook_health`	Per-agent liveness and outstanding failing verbs
`hook_sessions`	Per-session outcomes under `health.verbs`, including parent IDs and failure details
`hook_health_error`	Why the operational log could not be loaded
`hook_errors`	Aggregated legacy plugin/git-shadow errors and recent entries
`silent_agents`	Installed agents with no successful dispatch in the available log

With no observations, hook-health fields are omitted. During a service outage, pending observations may still be reported; hook_health_error explains the partial report, and silent_agents is omitted. See Hook Health and Troubleshooting for diagnosis, correlation, and recovery behavior.

`explain`

Generate AI reasoning summaries for recorded agent turns.

# Explain the most recent session
atomic agent explain <session-id>

# Explain a specific turn
atomic agent explain <session-id> --turn 3

# Explain all turns and save reasoning + learnings
atomic agent explain <session-id> --all --save

Options:

Option	Description
`--turn <N>`	Explain a specific turn number
`--all`	Explain all turns in the session
`--save`	Save reasoning into the change's unhashed section and append learnings to the agent's context file
`--model <MODEL>`	Claude CLI model to use for reasoning generation (default: `sonnet`)

When --save is used:

Reasoning is stored in the change (travels on push, rendered in server UI)
Repo and Workflow learnings are appended to the agent's context file (CLAUDE.md, GEMINI.md, or opencode.md)

`attest`

List and inspect attestations — graph-level audit nodes capturing AI cost, token usage, model breakdown, and code change statistics.

Attestations are created automatically at session end. They aggregate data from the provenance entries embedded in each covered change: model name, token counts (input, output, cache read/write), cost in USD, and lines added/removed from the CRDT semantic layer.

# List all attestations
atomic agent attest

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

# Show attestations for a view
atomic agent attest --view dev

# Verbose output with model breakdown
atomic agent attest --verbose

Options:

Option	Description
`--hash <PREFIX>`	Show details for a specific attestation (supports prefix matching)
`--view <NAME>`	Filter attestations covering changes in this view
`--verbose`, `-v`	Show per-model token breakdown and per-change details
`--summary`, `-s`	Show a project-level AI provenance summary instead of the attestation list
`--pending <PARENT_VIEW>`	Summarize the pending delta of `--view` relative to the given parent view (e.g. `--pending dev`). Only changes that are in `--view` but not in the parent are classified; implies `--summary` and requires `--view`

Example output:

$ 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

Detail view:

$ atomic agent attest --hash XMJZ3IPF

Attestation XMJZ3IPF

Agent:     OpenCode
Session:   agent-ses_3781fc7a6ffet5c6r1ILy1BEbv
Changes:   2 changes
Wall time: 3m 42s
Cost:      $0.15
Tokens:    12.4k
Code:      +116 -8

Model Breakdown:
  claude-sonnet-4-5: 3.2k in / 9.2k out · $0.15

Changes Covered (2):
  ABC12345
  DEF67890

Coverage:
  dev                  ████████████░░░░░░░░ 2/5 (40%)

`repair`

Resume a managed session under leases while retaining every piece of durable evidence (CB-12A AC3).

atomic agent repair <SESSION> [--verify-only]

Argument	Description
`<SESSION>`	The managed session identifier to repair

Option	Description
`--verify-only`	Verify evidence only (attestation/capture MACs); no state changes

Use repair after an orchestrator or machine crash: it resumes the managed run under its lease, validates the recorded evidence, and preserves every attestation and provenance artifact already captured. Pair it with atomic agent lifecycle stop/resume for controlled shutdowns; see agent lifecycle.

`identity`

Select or inspect the agent identity that recording hooks sign as.

atomic agent identity set <IDENTITY>   # Select the agent identity for hook recording (machine-wide)
atomic agent identity unset            # Clear the agent identity selection
atomic agent identity show             # Show the effective agent identity and where it comes from

`hooks` (internal)

atomic agent hooks <AGENT_NAME> <VERB> is the internal hook-callback entrypoint invoked by the installed agent integrations. Do not call it manually; the integrations pass lifecycle verbs (session start/stop, turn end) to it as part of atomic agent enable. There is no supported manual workflow around this subcommand.

How It Works

You prompt the agent → agent reads, edits, tests → Atomic records the turn
                                                      │
                                                      ├── Change: "Turn 3: Fix the auth bug"
                                                      ├── Provenance: anthropic/claude-sonnet-4-5, session, turn
                                                      ├── Envelope: timing, files touched, model info
                                                      ├── Provenance Graph: goal → explorations → commitment → verification
                                                      └── Transcript: conversation (unhashed, redactable)

On Each Turn End

Status — ask the repository what changed since the last recorded state
Add — track any new files the agent created
Record — create an Atomic change with AI provenance metadata
Provenance — append a PatchProposal node, convert the accumulated graph to a content-addressed ProvenanceGraph, and save it to the repository

On Session End

Attestation — aggregate model/cost/token data from all covered changes and create a session-level audit node
View restore — switch back to the user's original view

Provenance Graph Pipeline

Throughout the session, the ProvenanceAccumulator builds a causal decision DAG:

user-prompt → appends a Goal node (the user's intent)
after-tool → appends a classified tool node (Exploration, Commitment, Verification, or Execution) with causal edges inferred from context
stop → appends a PatchProposal node, converts to ProvenanceGraph, saves to .atomic/changes/

The accumulator is persisted to .atomic/sessions/{session_id}/graph.json between hook invocations (each hook is a separate process). Writes are atomic (temp file + rename) to prevent corruption.

Provenance graphs are pushed to remotes alongside changes and rendered in the web UI.

Agent Identity

Agent changes are attributed using a +tag email format:

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

Agent	Example Author
Claude Code	`claude+60f5 <lee@atomic.dev>`
Grok Build	`grok+019f <lee@atomic.dev>`
OpenCode	`opencode+9876 <lee@atomic.dev>`

The identity used for hook recording can be selected explicitly with atomic agent identity set <IDENTITY> and inspected with atomic agent identity show; atomic agent identity unset clears the selection.

Supported Integration Packages

Integration	Agent	Setup Guide
`atomic-agy`	Antigravity CLI	Installing Agent Integrations
`atomic-claude`	Claude Code	Installing Agent Integrations
`atomic-cline`	Cline	Installing Agent Integrations
`atomic-codex`	Codex	Installing Agent Integrations
`atomic-copilot`	GitHub Copilot	Installing Agent Integrations
`atomic-cursor`	Cursor	Installing Agent Integrations
`atomic-devin`	Devin	Installing Agent Integrations
`atomic-grok`	Grok Build	Installing Agent Integrations
`atomic-kilo`	Kilo Code	Installing Agent Integrations
`atomic-kiro`	Kiro	Installing Agent Integrations
`atomic-opencode`	OpenCode	Installing Agent Integrations
`atomic-pi`	Pi	Installing Agent Integrations

Examples

Enable and work with Claude Code

# Initialize repo and enable agent
atomic init
atomic agent enable --agent claude-code

# Work with Claude Code normally — turns are recorded automatically

# Check what happened
atomic log
atomic agent status --verbose

# Inspect attestations
atomic agent attest

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

Review agent work before promoting

# See what the agent changed on its isolated view
atomic log --view agent-ses_3781fc...

# Insert specific changes into your view
atomic insert <change-hash> --to dev

# Clean up the agent view (--force: uninserted changes would be orphaned,
# and there is no terminal to confirm)
atomic view delete agent-ses_3781fc... --force

Push agent data to remote

$ atomic push origin

# Changes, attestations, and provenance graphs are uploaded automatically:
#   ✓ Pushed 2 changes
#   ✓ XMJZ3IPF attestation ($0.15, 2 covered)
#   ✓ ABC12345 provenance (7 nodes, 1 change)

Rewind an agent turn

# See the turn history
atomic log

# Undo the last turn
atomic revise

Synopsis​

Description​

Subcommands​

enable​

disable​

status​

explain​

attest​

repair​

identity​

hooks (internal)​

How It Works​

On Each Turn End​

On Session End​

Provenance Graph Pipeline​

Agent Identity​

Supported Integration Packages​

Examples​

Enable and work with Claude Code​

Review agent work before promoting​

Push agent data to remote​

Rewind an agent turn​

See Also​

Synopsis

Description

Subcommands

`enable`

`disable`

`status`

`explain`

`attest`

`repair`

`identity`

`hooks` (internal)

How It Works

On Each Turn End

On Session End

Provenance Graph Pipeline

Agent Identity

Supported Integration Packages

Examples

Enable and work with Claude Code

Review agent work before promoting

Push agent data to remote

Rewind an agent turn

See Also