npm & git for the agentic era

Built for the agent.
Trusted by the developer running it.

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

Resolve intent without
risking a stuck shell.

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.

  • ✓
    --plan resolves without executingReturns the matched command and risk assessment — nothing runs.
  • ✓
    --json for machine-readable outputSame resolution, structured for a calling agent instead of a human reading a terminal.
  • ✓
    Never blocks on stdin in agent contexts--agent, XNPM_AGENT=1, CI=true, or non-TTY mode skip the interactive prompt entirely.
  • ✓
    Deterministic refusal, not a hangApproval-required work without approval exits 4 with the plan printed. TTY behavior for humans is unchanged.

Full reference: Ask → code-agent-safe, Install → exit codes.

agent plan, then execute
$ xnpm ask "release the stack" --plan --json → { command, argv, risks, explanation, suggestedYesCommand } $ XNPM_AGENT=1 xnpm ask "release the stack" ✕ exit 4 — approval required, plan printed $ xnpm ask "release the stack" --yes ✓ executes — approval given explicitly

For the developer overseeing the agent

Know what an agent can do
before you hand it the release.

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.

Safe without approval

xnpm list xnpm validate xnpm release --stack <stack> --dry-run --report --yes xnpm ask "<request>" --plan --json

Requires explicit approval

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

Why this is redefined, not wrapped

Same model. A caller
that can't ask a follow-up question.

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.