Axe Agent

Axe is a terminal-first coding and market-operator assistant. This package owns the published axe command and the runtime surface used by the local Axe cockpit.

The package is distributed as @axe-labs/axe-agent and intentionally keeps the runtime dependency boundary narrow: it depends on the upstream @mariozechner/pi-ai, @mariozechner/pi-tui, and @mariozechner/pi-agent-core packages at exact versions while Axe-specific behavior lives in this package.

Install

npm install -g @axe-labs/axe-agent
axe

Node.js 20.6 or newer is required. Node.js 22 is the recommended runtime for release smoke tests.

First Run

Start the TUI:

axe

Then authenticate with /login or provide provider API keys such as OPENAI_API_KEY or ANTHROPIC_API_KEY. Use /model to select a model after credentials are available.

Axe stores its agent state under ~/.axe/agent by default. The legacy PI_CODING_AGENT_DIR environment variable still works for compatibility, but new automation should use AXE_CODING_AGENT_DIR.

Useful Commands

axe --help
axe --version
axe --doctor
axe --doctor-json

axe --doctor reports the model catalog, provider auth status, config paths, connector state, settings, and runtime checks. axe --doctor-json emits the same information as a stable JSON report suitable for CI and local smoke tests.

Development From The Monorepo

From a checkout of github.com/usb-labs/axe-agent:

npm install
./pi-test.sh

For source-backed local install shims:

./scripts/install-axe.sh
axe
axe-dev

The source installer remains a development path. Release users should prefer npm install -g @axe-labs/axe-agent once the package is published.

Package Smoke Test

From the repo root, run:

scripts/smoke-axe-npm-package.sh

The script builds this workspace, packs @axe-labs/axe-agent, installs the tarball into a clean npm prefix, and verifies axe --version, axe --help, and axe --doctor-json without requiring npm registry publish credentials.

Publish

The first public publish requires an npm account with publish rights to the @axe-labs scope:

npm whoami
npm org ls axe-labs --json
npm run publish:axe:dry
npm run publish:axe

The package-level publish command is:

cd packages/coding-agent
npm run publish:dry
npm publish --access public

See docs/npm-publish.md for the release checklist and clean-machine smoke steps.

Extension Imports

New extensions should import SDK types from the Axe package:

import type { ExtensionAPI } from "@axe-labs/axe-agent";

The legacy @mariozechner/pi-coding-agent specifier remains aliased at runtime so existing extensions continue to load.

License

MIT. Axe is based on the upstream pi coding-agent package and preserves the upstream MIT notice.