blevene/aenv/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

Pin selection (for aenv skill import --pin <ref>)

When the user wants to import a skill, ask which form of pin they want (or pick a default and tell them):

• Tag (v1.0, v2.39.0) — when the source repo has releases. Semantic; reads cleanly. Find via repo's Releases tab.
• Commit SHA (40-char hex) — when there are no tags, or for absolute immutability. Find via repo's Commits view; the URL ends with the full SHA.
• Branch name (main) — only when the user actually wants to track that branch's head at the moment of import. aenv freezes the resolved SHA either way; re-import to follow main later.

--pin is optional. Without it, aenv re-resolves to the default branch HEAD on every activation. Always pin for anything reproducible.

Global profiles (aenv global — user scope)

Swapping the user-level config that every Claude Code / Codex session reads. aenv global use is the one-command front door.

Deprecated: aenv global activate <ns> still works but prints a deprecation notice — prefer aenv global use <ns> (a superset that also imports sources and records a swap-back point).

Unified scope flags (equivalent to the `aenv global` tree): the project verbs accept --global to act on user scope without switching command trees — aenv create <ns> --global (= global new), aenv activate <ns> --global [--yes] [--no-baseline], aenv deactivate --global [--force]. Either spelling is fine; aenv global … is not going away. Guards: --global can't be combined with a --project <path> override, --yes/--no-baseline/--force are global-only, and --prune is project-only.

One copy serving both scopes (`shared_files`): to reuse one profile's content both globally and inside a project without storing it twice, declare those paths under shared_files in the adapter block instead of user_files — e.g. [adapters.claude-code] shared_files = [".claude/CLAUDE.md", ".claude/agents/"]. Content is stored once under ~/.aenv/envs/<ns>/user/; aenv activate <ns> --global materializes it into $HOME, and aenv use <ns> + aenv activate (project) materializes the same bytes into the repo, with role-tagged files remapped to each scope's layout (.claude/CLAUDE.md → repo-root CLAUDE.md in a project). Emit shared_files directly at creation/capture time with the opt-in --shared flag on aenv create <ns> --global --shared, aenv global new --shared, aenv global snapshot --shared, or aenv global import --shared (default is unchanged — user_files; on create, --shared requires --global). Or migrate an existing global-only profile by renaming its user_files key to shared_files (no files move). files/user_files still mean project-only / user-only. Heads-up: declaring the same project destination via both files and a shared_files remap makes aenv activate print a collision warning — keep one declaration per path.

Global gotchas — surface these proactively

• One activation per user. aenv global use <b> while <a> is active deactivates <a> and activates <b> atomically; on failure <a> is restored. There's no "both at once."
• First activation auto-captures `baseline`. Your pre-aenv ~/ surface is saved as the baseline namespace so you always have a return point (aenv global use baseline / use -). --no-baseline opts out. An empty $HOME captures nothing.
• Running sessions keep their config until restart. aenv swaps files on disk; a live Claude Code / Codex process read its config at launch. Tell the user to quit and relaunch the harness for a swap to take effect — aenv prints this caveat on every activation.
• Lifecycle hooks are opt-in, never inferred. A namespace runs a setup script on activation only if it declares [lifecycle] on_activate in its manifest or a source repo's aenv-namespace.toml. aenv does NOT auto-run a repo's install.sh (those are self-installers that fight aenv). First run prompts for approval (SHA-pinned at ~/.aenv/envs/<ns>/.approved); --yes skips the prompt.
• Recovery / lockout. If an activated namespace's hooks lock you out of a Claude Code session (e.g. a settings.json hook calls a missing runtime), open a non-Claude shell and run aenv global deactivate --force, or aenv-rescue (a standalone binary that restores $HOME from global-state.json via direct fs ops, never running lifecycle scripts).

Gotchas — surface these proactively