Your AI Coding Agent Needs a Package Manager, Not a Synced App Folder

AI coding-agent setups are becoming real developer environments.

That happened quietly. First you add a prompt. Then a skill. Then a plugin. Then an MCP server. Then an AGENTS.md. Then a Codex profile, a Claude Code setting, a few symlinks into dotfiles, a generated system file, a cache, a local override, and a history file you very much do not want to sync.

Eventually the setup works.

But you cannot explain it anymore.

That is the problem Agent Brain is meant to solve.

The Setup Became Useful Before It Became Legible

My own setup crossed the line before I noticed. I had skills in one place, prompts in another, plugin metadata elsewhere, Codex config in a different shape from Claude Code config, repo-local instructions, global instructions, dotfile symlinks, generated artifacts, and local state that had no business following me to another machine.

The pain was not only “a file broke.”

The real pain was ownership fog.

What owns this file? Did I author it? Did an app generate it? Is it source, state, cache, secret, runtime history, or a local machine assumption? If I move it through dotfiles, am I preserving intent or just shipping sediment?

That last question is where the ordinary dotfiles model starts to feel too thin.

Dotfiles Are Necessary, But Not Sufficient

I like dotfiles. I use them. They remain the right answer for a lot of developer setup.

But dotfiles answer a path-level question: which files should appear on this machine?

AI coding-agent setups need a semantic answer: what does this file mean?

There is a difference between:

• a human-authored skill;
• a generated target file;
• app-native state;
• runtime cache;
• auth material;
• a machine-local override;
• a file owned by another tool;
• an unknown leftover that needs review.

A sync tool can move all of those. It cannot reliably tell you which ones should become portable product source.

That distinction matters because Claude Code and Codex are not passive config readers. They are target apps with their own layouts, generated files, plugin behavior, caches, project-local semantics, and safety assumptions. Syncing a whole .claude or .codex directory can preserve exactly the mess you are trying to escape.

App Homes Are Materialization Surfaces

Agent Brain takes a different stance.

The durable model is not “whatever happens to be in the app folder.”

The durable model is packages, profiles, provenance, target adapters, materialization locks, and a safety lifecycle.

Packages describe portable capabilities: skills, prompts, plugin intent, MCP definitions, connector intent, or other authored agent behavior.

Profiles describe which packages apply together.

Provenance records where an artifact came from, which adapter observed it, and how confidently it was classified.

Target adapters preserve app-specific semantics for Claude Code, Codex, and eventually other agent apps.

Materialization locks map canonical intent to generated target paths, so apply and rollback can reason about what happened.

In that model, local app folders are materialization targets. They are not the source of truth.

What The Public Release Does Today

Agent Brain is now public on npm as @leonardsellem/agent-brain and on GitHub at leonardsellem/agent-brain.

Install it with:

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

The current release supports the full guarded workflow I wanted before inviting feedback:

• fixture-backed rehearsal, so you can inspect the model without touching personal state;
• explicit live-root diagnosis for .claude, .codex, .dotstate, disposable, or other approved roots;
• import of portable source candidates into an Agent Brain repo;
• dry-run planning before mutation;
• exact fingerprint confirmation before apply;
• baseline snapshots;
• materialization locks;
• verify after apply;
• rollback from snapshot metadata;
• bootstrap of another target from canonical intent.

This is not a hosted sync service. It is not a plugin marketplace. It is a local-first CLI for making agent environments explainable before they become portable, and reversible before they become automated.

How Live Safety Works

The safety model is deliberately fussy.

Live commands start from explicit roots. No guessing around your home directory. No cheerful crawl of private folders.

Before mutation, Agent Brain builds a dry-run plan with the exact create, update, move, and symlink operations. That plan gets a fingerprint. To apply it, you confirm that exact fingerprint, not just a vague “yes.”

Before writing, Agent Brain captures a baseline snapshot. After writing, it records a materialization lock and runs verification. Rollback uses snapshot metadata rather than pretending it can reverse history from memory.

Secrets, auth material, runtime state, caches, and machine-local files are excluded from canonical source by default. Unknown files should be explained, not silently adopted.

That posture is the point. A tool that manages agent homes should earn trust before it touches them.

Why Release This Now

The most important question is not whether every adapter rule is perfect today. It is whether the ownership model matches the setups people are actually building.

I want Agent Brain to learn from real mess.

Not artificial “hello world” setups. Real ones: half-dotfiled, half-symlinked, partly generated, full of old experiments, with useful skills sitting next to files nobody wants synced.

That is where the product either earns its category or does not.

What I Want Feedback On

If you have a valuable but hard-to-explain agent setup, I would love your critique.

The questions I care about most:

• Does the ownership vocabulary match your real setup?
• Which Claude Code and Codex artifacts should be portable?
• Which files should never be adopted automatically?
• Where should target adapters preserve app-native semantics instead of flattening everything into generic files?
• What would make a dry-run, apply, verify, and rollback report credible?
• What messy setup pattern should become a fixture?

Agent Brain is here: https://github.com/leonardsellem/agent-brain

If your setup works but you cannot explain it, you are exactly the person I want to learn from.