The fast, project-local environment manager for Claude Code and Codex.
aenv initializes, audits, compares, captures, and protects AI coding environments without touching global Claude Code or Codex configuration. It is a local-first, CLI-first tool: no account, API key, daemon, cloud service, or LLM is required.
npm install -g @tinylion1024/aenv
mkdir my-agent-project &&cd my-agent-project
aenv init --provider codex --yes
aenv doctor
aenv diffThat creates a small agent-env.json manifest and a repository-level AGENTS.md. Use --provider claude-code to create the corresponding Claude Code environment.
Claude Code and Codex project instructions, MCP declarations, local settings, and credentials can drift between repositories or leak into invisible global state. aenv keeps the supported project environment explicit and reviewable.
| Need | aenv action |
|---|---|
| Start a Claude Code or Codex project consistently | aenv init |
| Find invalid config, inline secrets, or unsafe Git state | aenv doctor |
| See drift from the selected recipe without changing files | aenv diff |
| Reuse a proven, redacted project environment | aenv capture then aenv init |
| Keep local agent state out of commits | automatic local Git guard |
| Command | Writes | Result |
|---|---|---|
aenv init | Project files; local .git metadata in Git repositories | Creates only missing files from a recipe |
aenv doctor | Nothing | Audits the selected provider, configuration, secrets, context size, and Git state |
aenv diff | Nothing | Reports missing, unchanged, modified, and unmanaged files |
aenv capture <name> | Local or explicitly selected recipe directory | Creates a provider-specific, redacted private recipe |
Common automation forms:
aenv init --provider claude-code --recipe web --dry-run --cwd /path/to/project
aenv doctor --json --cwd /path/to/project
aenv diff --json --cwd /path/to/project
aenv capture team-base --cwd /path/to/projectdoctor exits with 1 when a failing finding exists. diff exits with 1 when drift exists. Their JSON output is a single document suitable for CI; normal human output remains the default.
| Provider | Baseline project files | Global locations never touched |
|---|---|---|
| Claude Code | CLAUDE.md, .claude/settings.json, optional captured .mcp.json | ~/.claude |
| Codex | repository-root AGENTS.md | $CODEX_HOME, default ~/.codex |
Codex project .codex/config.toml, project skills, and MCP configuration are outside aenv's managed baseline. The default Git guard treats .codex/ as protected local state; teams that intentionally version Codex project configuration must manage that policy explicitly outside aenv.
Existing files are never overwritten. agent-env.json records the selected provider and recipe so doctor, diff, and capture use an explicit environment rather than guessing.
Built-in recipes establish concise policy, not a hidden tool bundle:
lean— minimal guidance; no plugins or MCP servers enabled.web— web-project guidance; integrations remain opt-in.research— research-project guidance; external access remains opt-in.
Capture a working environment and reuse it offline:
# Run inside a project already initialized by aenv.
aenv capture team-base
mkdir ../next-project
aenv init --provider codex --recipe team-base --yes --cwd ../next-projectCaptured recipes default to ~/.agent-env/recipes/ for backward compatibility. Use --recipes-dir to select a private team directory. Capture accepts only provider-owned project files, replaces likely secrets with ${ENV_VAR}, replaces machine-specific home paths with ${LOCAL_PATH}, and writes an AUDIT.md review checklist.
- Core commands are deterministic and require no network access.
- aenv never reads or writes Claude Code or Codex account, credential, cache, session, or global configuration files.
- Writes stay inside the target project, aenv's local recipe store, or an explicit recipe directory.
- Existing project and recipe files are preserved.
- Recipe paths are provider-scoped and reject absolute paths, traversal, duplicates, and symlinks at the root, directory, or file level.
- Capture and audit refuse symlinked project roots, manifests, and provider-owned source files.
doctoranddiffare always read-only and never print differing file contents.- In Git repositories, aenv installs local protection in the default hooks directory or a project-local
core.hooksPath. It blocks local agent state and probable inline credentials while leavingCLAUDE.mdandAGENTS.mdversionable. An externalcore.hooksPathis never modified and produces a warning.
No. aenv does not run agents, route models, manage accounts, store credentials, or support arbitrary providers. Its scope is deliberately limited to project environment management for Claude Code and Codex.
The primary command is aenv. The former agent-env command remains as a compatibility alias, and the existing agent-env.json / ~/.agent-env/recipes/ names remain stable for existing users.