npm & git for the agentic era
Plan/execute separation, JSON resolution, deterministic exit codes, and a journal of every local change aren't an agent mode bolted onto xnpm — they're what npm and git look like when the caller might be a process that can't recover from a hung prompt. That serves two different people: the agent issuing the command, and the developer who is overseeing the agent and has to trust what it did.
For the agent
xnpm ask is a resolver first. --plan --json returns the matched command, argv, risks, and explanation without executing anything. In non-TTY mode xnpm never waits for approval — if approval is needed, it exits with a dedicated code instead of blocking on stdin.
--agent, XNPM_AGENT=1, CI=true, or non-TTY mode skip the interactive prompt entirely.4 with the plan printed. TTY behavior for humans is unchanged.Full reference: Ask → code-agent-safe, Install → exit codes.
Measured, not asserted
We measured this rather than claiming it. On a synthetic monorepo with a linear dependency chain (pkg-1 ← pkg-2 ← pkg-3 …), we compared the tokens an agent has to read to reach a confident, dependency-correct release plan: manually discovering every package.json and running npm publish --dry-run on each package, versus one xnpm ask "release the stack" --plan --json call. No package was actually published or pushed in either path.
| Packages | Manual (raw npm/git) | xnpm (--plan, one call) | Ratio |
|---|---|---|---|
| 3 | 990 tokens | 170 tokens | 5.8× |
| 6 | 2,000 tokens | 170 tokens | 11.8× |
| 10 | 3,280 tokens | 170 tokens | 19.3× |
The manual path grows roughly linearly with package count — each additional package means another file to read and another dry-run call. The xnpm number stays flat because ask --plan returns a routing decision (which command to run and why), not a per-package enumeration — confirmed by checking that the raw output was byte-identical at every package count tested.
Method: tiktoken cl100k_base token counts of raw command output fed back into context (not model reasoning tokens), measured at 3, 6, and 10 packages on a synthetic fixture with minimal near-empty package files. Real monorepos have larger files and longer dry-run output, so this ratio is likely a lower bound, not an upper one — but we're not claiming a number we haven't tested at production scale.
For the developer overseeing the agent
You're not the one typing --plan --json. You're the one deciding whether to let an agent run a release unattended at all. xnpm draws an explicit line between what an agent can do on its own and what needs your approval — so that line is something you can audit, not something you have to take on faith.
xnpm list
xnpm validate
xnpm release --stack <stack> --dry-run --report --yes
xnpm ask "<request>" --plan --json
xnpm ask "<request>" --yes
xnpm release --stack <stack> --yes --report
xnpm install --fix --yes
xnpm --full-flow --yes
The dividing line is irreversibility, not difficulty: anything that only inspects or plans is on the left. Anything that publishes to npm, pushes to git, or rewrites dependency specs needs --yes set explicitly by whoever configured the agent — it cannot cross that line by accident in a non-interactive run.
What you get back after an agent run
xnpm undo --last reverses them without you reading agent chat transcripts to figure out what changed. See Undo.2 means publish succeeded but push failed — a different outcome from total failure (1) or a refused approval (4), so you don't have to parse prose to know which.Why this is redefined, not wrapped
xnpm doesn't add a new mental model on top of npm install, npm publish, and git push. It makes that existing model legible to a caller that can't ask a clarifying question when something is ambiguous. A human stuck at a confusing prompt can read the screen, think, and answer. An agent stuck at the same prompt in a non-interactive shell just hangs — the orchestrating process eventually kills it, and the release is left half-done with no record of why.
That's the actual redefinition: not new commands, but the same release contract — discover the graph, plan, execute in order, journal, report — expressed in a form a deterministic process can consume. Why → for code agents covers the underlying product values; this page is the contract itself.