The flow, at a glance
Conflicting intent in → shared evidence and review context out
aienvmap gives AI coding agents read-only evidence about the environment they share — runtimes, package managers, dependencies, and pending change intent. It is advisory by default: it surfaces review boundaries but never grants permission or installs, switches, or removes software on its own.
npx aienvmap@latest start
npx aienvmap@latest status
npx aienvmap demo for a scripted conflict, or npx aienvmap trial to test it safely in a disposable copy of your own project
A map, a version inventory, and a light SBOM — evidence for review, never automatic authority
One environment map, every agent reads the same one
aienvmap start writes AIENV.md plus .aienvmap/status.json — the live runtime, package manager, and next-step state, instead of each agent guessing its own.
aienvmap context --json
Detected runtime and tool routing, visible — never touched
aienvmap reconcile inspects bounded evidence for Node, Python, Java, their package managers, and additional runtime presence. Command aliases such as python and python3 are grouped before distinct environments are counted. Read-only by design; it never deletes or modifies anything on its own.
aienvmap reconcile --check
Dependency risk context, without a heavy scanner
A light SBOM gives agents dependency awareness before a change. Already run Syft, Trivy, or Grype? Import that evidence instead of duplicating the scan.
aienvmap sbom --json
Conflicting intent in → shared evidence and review context out
What aienvmap reconcile actually does — observe, then hand off to a human
Three commands make up the loop
npx aienvmap start
Boot in one command
Creates the env map, light SBOM, status, and dashboard when missing or stale — plus a copy-paste prompt any agent can pick up immediately.
aienvmap context --json
Agents ask first
Any agent can read the same bounded decision contract — environment state, evidence paths, next command, and review question — before changing a shared environment. Observed facts stay separate from approval.
aienvmap intent / checkpoint
Intent, then checkpoint
What an agent plans to change is logged first (intent). checkpoint records the outcome, re-syncs the env map, and hands off to the next agent.
What an agent plans to change (intent) and how it's resolved (resolve, checkpoint) are
appended to .aienvmap/intents.jsonl and timeline.jsonl.
Non-blocking by default — it records, it doesn't stop you.
aienvmap doctor checks the same drift for vulnerable dependencies, policy
rules, and conflicting agent intents. Warn-only locally; add
--strict security|policy|coordination|all to fail CI or a release gate on it.
.aienvmap/dashboard.html gives people a concise environment overview and a
separate light-SBOM view. Detailed AI evidence remains available in the JSON artifacts.
# AIENV.md (illustrative)
runtime node@22.4.0, python@3.12
package_manager pnpm@9
# timeline.jsonl
intent codex → upgrade test runner
intent claude → replace package manager
resolve human → keep pnpm, drop upgrade
aienvmap reconcile is read-only; add --check as an optional CI drift gate