aenv

README

aenv

aenv is a local environment manager for AI coding agents.

It gives Claude Code and Codex separate native homes, explicit credential selection, shared native instruction and skill bundles, safe imports, and deterministic diagnostics. It is an activation and migration tool, not a security sandbox.

Status

The version 1 implementation is complete against the product and technical specification, with local verification recorded in the implementation checklist. The Phase-0 capability matrix records the exact local baseline, required vendor probes, and fallback policy. Until the protected account-backed probes and release workflow pass, source builds remain development snapshots.

Build and test

Go 1.25.8 or newer is required. Earlier 1.25 patch releases contain a standard-library vulnerability exercised by aenv's filesystem operations:

go build ./cmd/aenv
go test ./...

Install

Published releases support macOS and Linux on amd64 and arm64. Until the first release is published, build from source as shown above.

With Homebrew on macOS or Linux:

brew install comamitc/tap/aenv

On Debian or Ubuntu, download the matching .deb asset from the release and install it with:

sudo apt install ./aenv_<version>_linux_<arch>.deb

On Fedora, RHEL, or another RPM-based distribution, download the matching .rpm asset and install it with:

sudo dnf install ./aenv_<version>_linux_<arch>.rpm

For a development install with Go 1.25.8 or newer:

go install github.com/comamitc/aenv/cmd/aenv@latest

All package methods install aenv only. Install Claude Code and/or Codex separately before creating an environment.

Intended workflow

Create or import an environment, validate it, then enter a Pipenv-style child shell:

aenv init praxis --tools claude,codex
aenv auth configure praxis --tool claude
aenv doctor praxis
aenv shell praxis

Inside that shell, the normal claude and codex names resolve through aenv-owned shims. The shims select the configured vendor binary and inject only that tool's process-scoped credentials. aenv run provides the same behavior without an interactive shell:

aenv run praxis -- claude --model opus
aenv exec praxis -- env

run accepts only the logical names claude and codex; exec is the arbitrary-command interface. An absolute path to a vendor binary bypasses the shim and its credential injection.

Security model

aenv is designed to prevent accidental mixing of native homes, credentials, and shared assets. It does not isolate hostile code running as the same OS user. Use a separate OS account, container, or VM for hard isolation.

Manifests, projections, logs, receipts, and support bundles never contain secret values. Vendor-owned protected stores such as Codex auth.json may contain credentials because the vendor writes them; aenv keeps them out of its own metadata and generated state. Claude OAuth in the macOS Keychain and OS-keyring-backed Codex authentication must be treated as potentially shared until a documented, live probe proves otherwise.

Import defaults to non-destructive copy mode. Restricted adopt mode only registers an external native home: aenv does not write or project into it, and config-rewriting auth modes remain unavailable until conversion to copy mode.