aenv

aenv

aenv is a CLI that manages named bundles of AI-coding-harness configuration (CLAUDE.md, .cursorrules, .mcp.json, skills, agents, etc.) — pin a project to a namespace, activate it, and the bundle materializes into the project as symlinks. Deactivate restores the project to its pre-activation state byte-for-byte.

Mental model in three sentences

Namespaces live at ~/.aenv/envs/<name>/ and own a manifest (aenv.toml) plus the actual files. A project gets pinned to a namespace via a one-line .aenv file at its root; aenv activate reads the pin, walks the extends chain, and materializes the resolved bundle. State lives in .aenv-state/state.json and the displaced originals (if any) sit in .aenv-state/backup/<timestamp>/ until aenv deactivate puts them back.

Two scopes: project vs global

aenv works at two scopes, and the verb prefix tells them apart:

• Project scope (aenv <verb>) — materializes a namespace's project files into a pinned project directory (the section above). State under <project>/.aenv-state/.
• Global scope (aenv global <verb>) — materializes a namespace's user-scope files (declared as user_files) into $HOME (~/.claude/, ~/.codex/, …). One global activation lives per user; activating another swaps it in a single transaction. State at ~/.aenv/global-state.json, displaced originals stashed under ~/.aenv/global-stash/<ts>/. This is how you swap your whole Claude Code / Codex setup. See the Global profiles section below.

User request → command map

User wants…	Run this
Set up a new namespace from scratch	aenv create <name> --adapter claude-code (also creates an empty CLAUDE.md; user edits it)
Build on top of an existing namespace	aenv create <name> --extends <parent> (composition; child overrides win section-by-section)
Capture a hand-shaped project as a reusable namespace	aenv snapshot <name> from inside the project
Pin + activate in a project	aenv use <name> then aenv activate. (Avoid aenv activate <name> without use first — it activates without writing a .aenv pin, leaving the project in a half-state where aenv status works but no future invocation knows what namespace was intended.)
Switch active namespace in a project	aenv deactivate && aenv use <other> && aenv activate
Restore project to pre-aenv state	aenv deactivate (then aenv unpin if they want the .aenv pin file gone too)
Add a skill they wrote themselves	aenv skill new <skill-name> --ns <namespace>
Install a skill from a public GitHub repo	aenv skill import git+<url> --ns <ns> --pin <ref> [--path <subdir>] — see "Pin selection" below
Install MANY skills from a monorepo at once	aenv skill import-all git+<url> --ns <ns> --base <dir> --pin <ref> [--only a,b] — clones once, imports every <base>/<subdir>/SKILL.md; malformed skills are warned + skipped, re-runs are idempotent
Copy non-skill content (agents, commands, reference docs) from a repo	aenv vendor git+<url> --ns <ns> --pin <ref> --path <subtree> --as <dest> — copies into the namespace tree, declares it under the adapter's files, records [[vendored]] provenance. --force to overwrite, re-run to refresh + report drift
Remove a skill	aenv skill remove <skill-name> --ns <ns>
Reclaim cache space (orphaned skill clones)	aenv cache prune
See what's active in the current project	aenv status
See where a managed file came from	aenv which <project-relative-path>
Show the resolution chain + parameters + policies	aenv status (text) or aenv status --json (structured)
Compare two namespaces	aenv diff <ns_a> <ns_b>
Detect drift between project and active namespace	aenv diff (no args; runs against active)
Bump a pinned skill ref	edit ~/.aenv/envs/<ns>/aenv.toml, change ref = line, then re-activate in any project using the namespace
Auto-activate on cd between projects	aenv init-shell <bash|zsh|fish> printed once into the user's rc file