Axum Agent

A Pi-based coding agent distribution that bundles the Pi core with curated extensions and launches them together.

Axum Agent is built around Pi-based agent distribution. The web UI handles provider, retry, and system-prompt settings locally, and startup can be isolated with safe mode when needed.

Quick Start: Quick Start

Requirements: Requirements

Translations: English • 日本語 • 中文

Overview

Axum Agent is a Pi-based coding agent distribution package. It bundles the Pi core together with extensions and launches them together, so a single npm install -g gives you a ready-to-run agent with no extra wiring.

Highlights

• One-command install — global npm package from the main branch tarball, no clone or build step.
• Bundled extensions — Pi core plus a hand-picked set of extensions ship together and start together.
• Web-based config — provider, retry, and system-prompt settings live in a local web UI.
• Safe mode — any broken extension can be bypassed to launch only the Pi core.
• Self-contained runtime — the bundled Pi runtime lives in the user cache, so reinstalling Axum does not repeat first-run setup.

Requirements

• Node.js >= 22.19.0
• npm >= 9
• A terminal on macOS, Linux, or Windows; Android/Termux is supported too.
• An OpenAI-compatible API key (or any provider you configure in the web UI).

Quick Start

Install Axum globally from the main branch tarball:

npm install -g https://github.com/SakuraByteCore/AxumAgent/archive/refs/heads/main.tar.gz

Start the agent directly:

axum

Configure your Provider and System Prompt on the Web UI:

axum web

Chat in the browser with the bundled pi-web UI (shares providers and sessions with axum code):

axum chat

Launch the agent:

axum code

Tip: in a repository checkout, run node bin/axum.js code (or the installed code command) to skip the npm run wrapper and shave ~0.2s off every startup.

Open the bundled pi-plugins skill guide for plugin management workflows:

/plugin-create-mode

axum code --safe

Check health:

axum doctor

Bundled Runtime

The distribution ships these packages, all in one install:

• @earendil-works/pi-coding-agent
• pi-bar (AxumAgent bundled fork, absorbs the former pi-header)
• pi-companion (merged pi-shortcuts + pi-guard: slash shortcuts /plan /clear /ralph /rules /claude /plugin-create-mode, response guard, advisory watcher, bundled claude-driver skill)
• @narumitw/pi-goal
• pi-web-access (web search, extraction, and curation tools: /websearch, /curator, /google-account, /search)
• pi-hashline-edit-pro
• @gamaraan/todos-tool (structured todo tracking: the todo tool maintains a plan checklist rendered as a live HUD above the editor, plus the /todo and /todos-configure commands)
• pi-agent (vendored from @giladbarnea/pi-user-agents: user-triggered background agents with live progress widget, -P/--plan for plan-mode background dispatch, one-keystroke /spawn /scout /blueprint presets, plus /dispatch and the dispatch_agent tool for agent-driven batch fan-out)
• pi-subagents (single-agent delegation and scripted multi-agent workflows: task delegation, background runs, agent orchestration)
• pi-memory (persistent cross-session memory in a single JSON file: /memory save|list|find|remove|recall|clear; zero native deps)
• @ff-labs/pi-fff (desktop only: FFF-powered file search with frecency ranking; excluded on Android and Windows)
• @zzxb/pi-notify (Windows only: Toast notifications with terminal focus, result icons, and BEL reminders)

Install Additional Extensions

axum install npm:[email protected]

install fetches the given npm package through the same cache pipeline as the bundled set, records it in ~/.axum/packages.json (override with AXUM_USER_PACKAGES_FILE), compiles its extension entry points, and loads them on the next axum code start. Installing a package name that is already in the bundled set is rejected; Axum manages those versions. If the install fails midway, the manifest is rolled back to its previous state. On Windows prefer extensions that ship strip-safe TypeScript (no decorators, enums, or other syntax the built-in type stripper cannot handle), since Windows relies on the stripper instead of a local tsc. Only the first entry in the package's pi.extensions list is loaded.

MCP Servers

MCP support is not built into Pi itself; Axum ships it through the pi-mcp-adapter extension. Two steps and you are done:

axum mcp install    # one-time: installs the pi-mcp-adapter extension

Then start axum code and run the /mcp wizard inside the session to discover, import (Cursor / Claude Code / Codex configs), or add servers interactively.

You can also manage server entries from the shell:

axum mcp add        # interactive: name, stdio command or http(s) url, args, env
axum mcp list       # show configured servers
axum mcp remove <name>

Servers are stored in the standard mcpServers JSON format shared with Cursor, Claude Code, and Codex: the project .mcp.json first, then the global ~/.config/mcp/mcp.json as fallback. Flags --project / --global on axum mcp add force one file. Existing configs from those tools work as-is. For stdio servers the command line may include arguments; the first token becomes the command and the rest are stored as args. axum doctor reports whether the extension is installed and whether your config files are valid JSON.

Configure a Provider

Save it from the Provider tab in axum web (see Quick Start for how to launch).

Fields:

• API form. openai-completions (default) speaks the OpenAI-compatible protocol and works with any such endpoint. anthropic-messages speaks the native Anthropic protocol; its base URL is https://api.anthropic.com without /v1, and since that endpoint exposes no model list you pick a model from a preset or enter the ID manually.
• Base URL, e.g. https://api.moonshot.cn/v1
• API Key
• Model. Providers without /models can be entered manually.
• Presets (optional). One-click templates for Anthropic (https://api.anthropic.com, native form) and OpenAI Chat (https://api.openai.com/v1) that fill API form, base URL, provider name, token defaults and model candidates. Add your API key and pick a model to save.

Saved to:

• ~/.pi/agent/models.json
• ~/.pi/agent/axum.json

After saving, launch the agent again:

axum code

Providers on the openai-completions form default to supportsDeveloperRole=false / supportsReasoningEffort=false; the anthropic-messages form carries no compat block and defers to pi-ai.

Retry Settings

In the retry tab of axum web, configure the automatic retry strategy for failed API requests (see Quick Start for how to launch).

Options:

• Enable retry — default off. Pi core defaults to on, but Axum requires explicit enablement.
• Max retry count — default 3.
• Base backoff delay (ms) — default 2000. Exponential backoff: baseDelayMs * 2^(attempt-1).
• Fixed retry delay (ms) — default 3000. Fixed-cadence delay (with jitter) for the strict-429 rate-limit and connection-error exemption lanes, which do not consume the retry budget above.

Retries target overload, rate-limit, and server errors. Context overflow is not retried (it is handled by compaction).

Saved to:

• ~/.pi/agent/settings.json

Edit the System Prompt

Edit it from the System Prompt tab in axum web (see Quick Start for how to launch).

Defaults to:

~/.pi/agent/SYSTEM.md

Targets:

• Global SYSTEM.md — default. Replaces the standard prompt.
• Global APPEND_SYSTEM.md — appends to the standard prompt.
• Project APPEND_SYSTEM.md — <cwd>/.pi/APPEND_SYSTEM.md.
• Project SYSTEM.md — <cwd>/.pi/SYSTEM.md.

It shows a diff before saving. If the file was changed externally, saving is refused.

Customize the /plan Prompt

/plan supports a user-level prompt override file:

~/.pi/agent/plan-prompt.md

Rules:

• If the file does not exist, Axum falls back to the built-in /plan prompt.
• If the file exists, Axum uses its content as the /plan prompt template.
• The file must include the placeholder {{requirement}} so Axum knows where to inject the user requirement.
• If the file exists but is empty, or does not contain {{requirement}}, /plan stops with an error instead of sending a broken prompt.

Example:

[Requirement]
{{requirement}}

[Objective]
Talk the technical solution through and finalize it: make the details clear, make the implementation clear, and put together a concrete plan we can actually follow, with a one-sentence plain-English explanation of what to expect.

[Rules]

1. Do read-only research only; do not modify files, write code, or provide code snippets.
2. Only when I explicitly say "generate" should you carry out the implementation; otherwise, stay in research and discussion mode.
3. Please say clearly, in plain and simple language, what result you are trying to achieve right now.

One-Keystroke Background Agents

Three preset commands bake in the common /agent flag combinations, so dispatching a background agent takes zero flag decisions:

/spawn fix the login bug        # = /agent -s fix the login bug
/scout why does the build fail  # = /agent -i why does the build fail
/blueprint add dark mode        # = /agent -P -s add dark mode

• /spawn <task> — inherits the current conversation and delivers the finished result back automatically.
• /scout <task> — starts isolated, with a blank context and no session inheritance.
• /blueprint <task> — runs in plan mode in the background and delivers the finished plan back verbatim.

Extra flags still compose: /spawn -m gpt-5 … works, because each preset is just a prefix over the shared /agent parser, widget, and lifecycle. The original /agent [options] <task> command is unchanged.

Switch Models with /usemodel

/usemodel reads the models configured in ~/.pi/agent/models.json and opens an interactive selector that lists every model from every provider, annotating the current default:

/usemodel            # open the model selector

Each entry is shown as provider/model, and the default is marked (default). Pick any model to switch to it immediately.

The selection is written to defaultProvider/defaultModel in ~/.pi/agent/settings.json, so axum passes it as --provider/--model on the next launch.

Doctor

axum doctor

doctor checks the bundled Pi cache and entrypoint, and reports the health of user-installed extensions (including whether the MCP extension is present and whether your MCP config files are valid JSON).

Safe mode (axum code --safe) launches the Pi core without loading any of the bundled extensions above.

The bundled Pi runtime is stored in the user cache, not the npm global package directory. So reinstalling Axum usually does not repeat the first-run setup of axum code.

Update

axum update

Reinstalls the npm global package from the main branch tarball on GitHub. There is usually no need to rerun the first-run setup afterwards.

License

Axum Agent is released under the FSL-1.1-ALv2 license: Functional Source License, Version 1.1, ALv2 Future License. The future license grant is Apache License 2.0. See LICENSE for details.

Translations

• English (current)
• 日本語
• 中文