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, response guard, advisory watcher)
• @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)
• @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)

Configure an OpenAI-compatible Provider

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

Fields:

• Base URL, e.g. https://api.moonshot.cn/v1
• API Key
• Model. Providers without /models can be entered manually.

Saved to:

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

After saving, launch the agent again:

axum code

For compatibility, OpenAI-compatible providers default to supportsDeveloperRole=false / supportsReasoningEffort=false.

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]
Discuss and finalize the technical solution: clarify the solution's details and implementation method, and formulate an actionable plan.

[Rules]
Focus solely on researching and discussing the solution; do not write code or generate code snippets. I will only begin generating code if you explicitly instruct me to do so. Please state the current expected outcome in plain, simple language.

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.

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)
• 日本語
• 中文