agentxchain

CLI for governed multi-agent software delivery.

AgentXchain coordinates multiple AI agents — PM, developer, QA, architect, and any custom roles — to work together on a codebase with built-in governance: structured turns, mandatory challenge between agents, phase gates, human approvals, and an append-only audit trail. Think of it as the operating system for AI software teams.

The canonical mode is governed delivery: orchestrator-owned state, structured turn results, phase gates, mandatory challenge, and explicit human approvals where required.

Legacy IDE-window coordination is still shipped as a compatibility mode for teams that want lock-based handoff in Cursor, VS Code, or Claude Code.

Docs

• Quickstart
• Getting Started
• CLI reference
• Lights-Out Scheduling
• Templates
• Export schema reference
• Adapter reference
• Protocol spec (v6)
• Protocol reference
• Build your own runner
• Why governed multi-agent delivery matters

Try It Now

See governance before you scaffold a real repo:

npx --yes -p agentxchain@latest -c "agentxchain demo"

Requires Node.js 18.17+ or 20.5+ and git. The demo creates a temporary governed repo, runs a full PM -> Dev -> QA lifecycle through the real runner interface, shows gates/decisions/objections, and removes the temp workspace when finished. No API keys, config edits, or manual turn authoring required.

Install

npm install -g agentxchain
agentxchain --version

Or via Homebrew (macOS/Linux):

brew tap shivamtiwari93/tap
brew install agentxchain

For a zero-install one-off command, use the package-bound form:

npx --yes -p agentxchain@latest -c "agentxchain demo"

Testing

The CLI currently uses two runners on purpose: a 36-file Vitest coexistence slice for fast feedback and node --test for the full suite.

npm run test:vitest
npm run test:node
npm test

• npm run test:vitest: the current 36-file Vitest slice
• npm run test:node: full integration, subprocess, and E2E suite
• npm test: both runners in sequence; this is the CI requirement today

Duplicate execution remains intentional for the current 36-file slice until a later slice explicitly changes the redundancy model. For watch mode, run npx vitest.

Quick Start

Governed workflow

Run agentxchain init --governed for the guided scaffold. Use the explicit non-interactive form below for scripts, CI, or copy-paste onboarding:

agentxchain init --governed --goal "Build an API change planner for release teams" --dir my-agentxchain-project -y
cd my-agentxchain-project
git init
agentxchain template validate
agentxchain doctor
git add -A
git commit -m "initial governed scaffold"
agentxchain status
agentxchain step --role pm

If you skipped --goal during scaffold, run agentxchain config --set project.goal "Build an API change planner for release teams" before the first governed turn instead of re-running init in place.

The default governed dev runtime is claude --print --dangerously-skip-permissions with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare claude --print is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:

agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y

If you want template-specific planning artifacts from day one:

agentxchain init --governed --template api-service --dir my-agentxchain-project -y

Built-in governed templates:

• generic: baseline governed scaffold
• api-service: API contract, operational readiness, error budget
• cli-tool: command surface, platform support, distribution checklist
• library: public API, compatibility policy, release and adoption checklist
• web-app: user flows, UI acceptance, browser support
• enterprise-app: enterprise planning artifacts plus blueprint-backed architect and security_reviewer phases

Inspect the shipped template surfaces instead of inferring them from docs:

agentxchain template list
agentxchain template list --phase-templates

template list enumerates governed project templates. template list --phase-templates enumerates the reusable workflow-kit phase-template bundles you can reference from workflow_kit.phases.<phase>.template.

step writes a turn-scoped bundle under .agentxchain/dispatch/turns/<turn_id>/ and expects a staged result at .agentxchain/staging/<turn_id>/turn-result.json. Typical continuation:

agentxchain validate --mode turn
agentxchain accept-turn
agentxchain approve-transition
agentxchain step --role dev
agentxchain step --role qa
agentxchain approve-completion

Default governed scaffolding configures QA as api_proxy with ANTHROPIC_API_KEY. For a provider-free walkthrough, switch the QA runtime to manual before the QA step. If you override the dev runtime, either include {prompt} for argv delivery or set --dev-prompt-transport explicitly.

Multi-repo coordination

For initiatives spanning multiple governed repos, use the coordinator to add cross-repo sequencing and shared gates:

agentxchain init --governed --template api-service --dir repos/backend -y
agentxchain init --governed --template web-app --dir repos/frontend -y
agentxchain multi init
agentxchain multi step --json

If the coordinator enters blocked, fix the cause and run agentxchain multi resume before continuing with multi step or multi approve-gate. See the multi-repo quickstart for the full cold-start walkthrough.

Migrate a legacy project

agentxchain migrate
agentxchain status
agentxchain step

Command Sets

Governed lifecycle and execution

Governed proof and inspection

Governed automation, plugins, and continuity

Shared utilities

Legacy v3 compatibility

Governed Flow

1. agentxchain step initializes or resumes the run if needed.
2. It assigns the next role for the current phase.
3. It writes .agentxchain/dispatch/turns/<turn_id>/.
4. The assigned role writes .agentxchain/staging/<turn_id>/turn-result.json.
5. The orchestrator validates and either accepts, rejects, advances phase, pauses for approval, or completes the run.

Protocol Conformance

AgentXchain ships a conformance kit under .agentxchain-conformance/. Use it to prove a runner or fork still implements the governed workflow contract:

agentxchain verify protocol --tier 3 --target .

Useful flags:

• --tier 1|2|3: maximum conformance tier to verify
• --surface <name>: isolate one surface such as state_machine, dispatch_manifest, or coordinator
• --format json: emit a machine-readable report for CI
• --target <path>: point at the root containing .agentxchain-conformance/capabilities.json

Important governed files:

agentxchain.json
.agentxchain/state.json
.agentxchain/history.jsonl
.agentxchain/decision-ledger.jsonl
.agentxchain/dispatch/turns/<turn_id>/
.agentxchain/staging/<turn_id>/turn-result.json
TALK.md
.planning/

The first-party governed workflow kit includes `.planning/SYSTEM_SPEC.md` alongside `PM_SIGNOFF.md`, `ROADMAP.md`, `acceptance-matrix.md`, and `ship-verdict.md`. `template validate --json` exposes this under the `workflow_kit` block.

Runtime support today

• manual: implemented
• local_cli: implemented
• mcp: implemented for stdio and streamable HTTP tool-contract dispatch
• api_proxy: implemented for synchronous review_only and proposed write-authority turns; stages a provider-backed result during step

Legacy IDE Mode

Legacy mode is still useful if you specifically want one IDE session per agent and lock-file coordination.

agentxchain start                   # Cursor (default)
agentxchain start --ide vscode
agentxchain start --ide claude-code
agentxchain kickoff
agentxchain supervise --autonudge

In this mode, agents hand off through lock.json, state.json, triggers, and TALK.md. For new projects, prefer governed mode unless IDE-window choreography is the goal.

macOS Auto-Nudge

supervise --autonudge is legacy-only and macOS-only.

agentxchain supervise --autonudge
agentxchain supervise --autonudge --send

Requires:

• osascript
• jq
• Accessibility permissions for Terminal and Cursor

Links

• agentxchain.dev
• Quickstart
• CLI reference
• Adapter reference
• Protocol spec (v6)
• GitHub
• Legacy Protocol v3 spec

License

MIT