Agent Brain

Agent Brain is a git-backed package and profile manager for AI coding-agent setups.

It is for the moment when your Claude Code and Codex setup works, but you can no longer explain it. Skills, plugins, prompts, MCP config, hooks, profiles, app settings, generated files, symlinks, dotfiles, caches, auth state, and local overrides all end up living near each other. Dotfiles can move those paths around; they cannot tell you what is authored source, what the app owns, what is generated, what is local-only, or what should never be synced.

Agent Brain turns that pile of agent app state into portable intent: packages, profiles, provenance, exclusions, adapter targets, and rollback-aware materialization. The core promise is simple: explain the setup first, make it portable second, mutate it only after safety gates.

Why Agent Brain

AI coding agents are becoming programmable work environments. A serious setup is no longer one config file; it is a mix of human-authored capabilities, app-native state, generated target output, runtime history, auth material, machine-local assumptions, and foreign tool ownership.

That creates three recurring pains:

• You cannot see ownership. A generic merge tool can show text conflicts, but it cannot say whether a conflicted file is source, generated output, cache, auth state, or unsafe shared-root fallout.
• You cannot safely move machines. Copying full .claude and .codex folders can move secrets, caches, generated files, stale symlinks, and machine-local assumptions along with the useful parts.
• You cannot trust automation yet. An agent can help manage agent tooling only if it has a semantic model and a fail-closed apply path before it touches live roots.

Agent Brain is not a dotfiles mirror. Dotstate, chezmoi, stow, bare dotfiles repositories, and unmanaged home directories can all be import sources, but the durable product model is portable agent capability intent.

That distinction matters because coding-agent apps have their own semantics. A Claude Code skill, a Codex plugin, app-native config, generated schema, runtime cache, auth file, and local machine override should not be treated as equivalent text files just because they live under a home directory.

Agent Brain is built around three ideas:

• Explain ownership first. Every scanned artifact is classified before it can become canonical source.
• Version intent, not app folders. Packages and profiles live in the Agent Brain repo; local apps are materialization targets.
• Make live changes reversible. Apply flows are designed around dry-runs, fingerprints, snapshots, verification, and rollback.

What It Manages

The canonical model is deliberately smaller than an app home directory:

• Packages describe portable capability source such as skills, plugins, prompts, MCP definitions, or app connector intent.
• Profiles choose packages and adapter targets for a working setup.
• Provenance records where an item came from, which adapter observed it, how it was classified, and how confident the importer was.
• Exclusions explain why runtime, cache, auth, secret, local-only, app-native, foreign, or unknown files are not canonical package source.
• Materialization locks map canonical package intent to generated target paths for a specific adapter and target root.

Claude Code and Codex are the MVP adapters. Their layouts can diverge while still sharing Agent Brain's ownership vocabulary.

Open the standalone diagram gallery for larger versions of the README diagrams.

Ownership Vocabulary

Agent Brain reports diagnosis, import, verification, and conflict results using the same categories everywhere:

Category	Meaning
portable-source	Human-authored capability source that can be adopted into the Agent Brain repo.
generated-target	Output materialized from canonical Agent Brain intent into an app target.
native-owned	App-owned configuration or state that should be managed through the app's own semantics.
runtime-cache	Cache, history, generated schema, or runtime data that should not become portable source.
machine-local	Local overrides or machine-specific paths that should not be blindly synced.
secret	Auth material or secret-like content. Excluded unless explicitly classified safe.
foreign-owned	Files owned by another tool or source of truth.
unknown	Anything that requires human review before adoption or mutation.

Command Surface

agent-brain doctor
agent-brain import
agent-brain plan
agent-brain apply
agent-brain verify
agent-brain rollback
agent-brain bootstrap
agent-brain explain-conflict <path>

All commands support text output by default and structured output with --json where reports are returned.

Command	Purpose
doctor	Scan known agent-app surfaces and explain ownership risks.
import	Convert portable source candidates into canonical package/profile output.
plan	Show proposed adoption or apply changes before writing.
apply	Materialize approved Agent Brain state into target app roots.
verify	Check generated target state and remaining risks.
rollback	Restore from snapshot metadata.
bootstrap	Materialize a second-machine target from an Agent Brain repo.
explain-conflict	Classify a conflicted path and recommend a semantic resolution.

The current implementation supports both a fixture-backed rehearsal path and an explicit live path for disposable or user-approved roots. Live commands require explicit roots, adapter/profile selection, a dry-run fingerprint, a baseline snapshot, a materialization lock, verify, rollback, and bootstrap evidence before the target is considered healthy.

Safety Model

Live target mutation is treated as a transaction:

1. Start from explicit roots supplied on the command line.
2. Build a dry-run plan with every create, update, move, and symlink change.
3. Compute a dry-run fingerprint for that exact operation set.
4. Require explicit confirmation of the fingerprint.
5. Capture a baseline snapshot before mutation.
6. Apply only the paths listed in the dry-run.
7. Write a materialization lock.
8. Verify target state.
9. Keep rollback metadata.

Runtime state, caches, auth material, secret-like content, and machine-local overrides are excluded from canonical source by default.

Quick Start

Prerequisites:

• Node.js 20 or newer
• npm

Install the CLI from npm and confirm that the shell is running the installed version:

npm install -g @leonardsellem/agent-brain
agent-brain --version
agent-brain --help

If agent-brain --version does not print the new version after an install, force npm to refresh the global package:

npm install -g @leonardsellem/agent-brain@latest --prefer-online

The important mental model: every command needs to know which source it is looking at, except doctor.

Run against a disposable or explicitly approved setup first. Diagnosis and planning are read-only, but import writes a canonical Agent Brain repo and apply can mutate a target only after you confirm the dry-run fingerprint.

Command	What it expects
agent-brain doctor	Can run with no arguments. It does a read-only diagnosis of the standard local Claude Code and Codex roots it can discover.
agent-brain doctor --claude-root <path>	Diagnoses an explicit root instead of relying on default discovery. Add --codex-root or repeated --source-root values when those are part of the setup you want to inspect.
agent-brain plan	Previews what would be adopted from an input source. It needs --claude-root, --codex-root, --source-root, or --fixture. It does not write an Agent Brain repo.
agent-brain import	Converts portable candidates from an input source into canonical Agent Brain repo files. It needs an input source plus --repo <path> because that is where it writes the repo output.
agent-brain apply	Reads an Agent Brain repo and target root, then prints a dry-run fingerprint first. It mutates only when you rerun it with the exact --confirm-fingerprint value.
agent-brain verify	Checks a target root against an Agent Brain repo and adapter.
agent-brain rollback	Restores a target root from snapshot metadata created by a confirmed apply.
agent-brain bootstrap	Builds another target root from the canonical Agent Brain repo.

agent-brain doctor can run with no arguments. agent-brain plan previews adoption from an input source and therefore needs --claude-root, --codex-root, --source-root, or --fixture. agent-brain import needs one of those same input sources plus --repo <path> because it writes the canonical Agent Brain repo output.

Start with a read-only diagnosis:

agent-brain doctor

That command should print a summary of scanned paths and findings. Findings are not automatic changes; they are labels that explain ownership, portability, caches, secrets, unknown files, or roots that need review.

For the first full workflow, use disposable roots. This creates a tiny Claude Code-like source root, previews it, imports it into an Agent Brain repo, dry-runs materialization into a separate target, confirms that exact dry-run, verifies the result, rolls it back, and bootstraps another target from the canonical repo:

AB_DEMO="$(pwd)/tmp/agent-brain-demo"
rm -rf "$AB_DEMO"
mkdir -p "$AB_DEMO/live-claude/skills/review" "$AB_DEMO/live-codex"
printf '# Review\n\nPortable disposable skill.\n' > "$AB_DEMO/live-claude/skills/review/SKILL.md"

# Diagnose explicit roots. This is read-only.
agent-brain doctor --claude-root "$AB_DEMO/live-claude" --codex-root "$AB_DEMO/live-codex" --json

# Preview adoption from an input root. This is read-only and does not require --repo.
agent-brain plan --claude-root "$AB_DEMO/live-claude" --json

# Import portable candidates into a canonical Agent Brain repo.
agent-brain import --claude-root "$AB_DEMO/live-claude" --repo "$AB_DEMO/agent-brain-live" --json

# Dry-run apply from the Agent Brain repo into a target root. This does not mutate yet.
DRY_RUN_JSON=$(agent-brain apply --repo "$AB_DEMO/agent-brain-live" --target-root "$AB_DEMO/live-target" --adapter claude-code --profile profile.default --json)
printf '%s\n' "$DRY_RUN_JSON"
FINGERPRINT=$(printf '%s' "$DRY_RUN_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).findings.find(f=>f.id==="apply.dry-run").provenance.fingerprint))')

# Confirm only the exact dry-run fingerprint you just reviewed.
APPLY_JSON=$(agent-brain apply --repo "$AB_DEMO/agent-brain-live" --target-root "$AB_DEMO/live-target" --adapter claude-code --profile profile.default --confirm-fingerprint "$FINGERPRINT" --json)
printf '%s\n' "$APPLY_JSON"
SNAPSHOT=$(printf '%s' "$APPLY_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).findings.find(f=>f.id==="apply.snapshot-created").provenance.snapshotPath))')

# Verify, rollback, and prove a second target can be bootstrapped from canonical intent.
agent-brain verify --repo "$AB_DEMO/agent-brain-live" --target-root "$AB_DEMO/live-target" --adapter claude-code --json
agent-brain rollback --snapshot "$SNAPSHOT" --target-root "$AB_DEMO/live-target" --json
agent-brain bootstrap --repo "$AB_DEMO/agent-brain-live" --target-root "$AB_DEMO/live-target-b" --adapter claude-code --profile profile.default --json

When you are ready to inspect real local state, keep the first pass non-mutating:

agent-brain doctor --claude-root ~/.claude --codex-root ~/.codex
agent-brain plan --claude-root ~/.claude --json

Only import or apply real roots after reviewing the diagnosis. Use --repo to choose where the canonical Agent Brain repo output should be written:

agent-brain import --claude-root ~/.claude --repo ~/agent-brain-live --json

For real tracked .codex, .claude, and .dotstate folders, use the personal live npm E2E protocol before any mutation. It keeps the npm-installed, Computer Use-visible pass non-mutating until a fresh Ring 2 approval names the exact dry-run fingerprint and recovery evidence.

Live mutation is intentionally slower than diagnosis. The same safety gates apply to real app roots and disposable roots: explicit roots, dry-run fingerprint, baseline snapshot, materialization lock, verify, rollback, and bootstrap from canonical intent rather than copying full app homes.

Contributor Setup

Install dependencies and run the full local verification loop from a source checkout:

npm install
npm test
npm run typecheck
npm run build

Run the compiled CLI against the synthetic release fixture:

npm run build
node dist/cli.js --help
node dist/cli.js doctor --fixture tests/fixtures/e2e-persona/scannable.json
node dist/cli.js plan --fixture tests/fixtures/e2e-persona/scannable.json --json
node dist/cli.js import --fixture tests/fixtures/e2e-persona/scannable.json --repo tmp/agent-brain-preview
node dist/cli.js apply --fixture tests/fixtures/e2e-persona/scannable.json --target-root /synthetic/target --json
node dist/cli.js verify --fixture tests/fixtures/e2e-persona/scannable.json --target-root /synthetic/target --json
node dist/cli.js rollback --json
node dist/cli.js explain-conflict '~/.codex/history.jsonl'
node dist/cli.js explain-conflict '~/.claude/skills/review/SKILL.md' --json

apply reports a dry-run fingerprint unless you pass the exact --confirm-fingerprint value from that dry-run. rollback fails until snapshot metadata is supplied; that is intentional and prevents a missing rollback record from looking successful.

Contributing

Agent Brain is open to contributors who want agent workspaces to become more legible, portable, and safe. The most helpful contributions improve ownership classification, adapter behavior, CLI safety gates, synthetic fixtures, documentation, release evidence, or the contributor experience around guarded live use.

Start with the Contributing guide. It covers project boundaries, good first contributions, local setup, TDD expectations, safety rules, pull request checks, and release/security boundaries.

Development

This repository is optimized for agent-native development:

• Plan before coding.
• Write or update a failing test before behavior changes.
• Keep filesystem, git, and process effects behind ports so tests can run against fixtures.
• Treat Claude Code and Codex app homes as materialization targets, not as the canonical Agent Brain source of truth.
• Run npm test and npm run typecheck before handoff.

Useful docs:

• Architecture
• Adapter contract
• Safety model
• Contributing guide
• Agent handoff
• Agent instructions

Repository Status

Agent Brain is pre-1.0 and publicly released on npm. The CLI is suitable for guarded live use against explicit .codex, .claude, .dotstate, disposable, or other user-approved roots when the documented dry-run, snapshot, verify, and rollback gates are followed.

The default development branch is dev; main is the integration target.

The npm package is configured for public launch as @leonardsellem/agent-brain; publication is handled through deliberate release automation rather than ordinary branch merges.

Roadmap

Near-term:

• Deepen real Claude Code and Codex adapter fixtures.
• Expand import heuristics for dotstate, chezmoi, stow, bare dotfiles, and unmanaged home roots.
• Harden release evidence around live apply confirmation, snapshot storage, verification, and rollback metadata.
• Improve conflict explanations for generated targets, runtime files, and unsafe shared roots.

Later:

• Bootstrap clean second-machine setups from an Agent Brain repo.
• Add more target adapters after Claude Code and Codex are trustworthy.
• Explore richer package publishing, sharing, and visual dependency tooling.

Out of scope for the core identity:

• Blindly mirroring full app home directories.
• Acting as a generic hosted sync service.
• Treating all coding-agent apps as if they share one universal plugin format.
• Automatically adopting secrets, auth files, caches, or runtime history.

Security

Agent Brain is conservative around auth material and secrets. Secret-like content is classified as secret and excluded by default. Do not put tokens, session files, API keys, private keys, or app auth databases into canonical packages.

If you discover a security issue while this repository is private, report it through the repository owner rather than filing a public issue.

License

Agent Brain is available under the MIT License.