pi-advisor

A Pi extension that adds a strategic advisor tool for complex coding agent tasks.

Overview

pi-advisor adds an advisor tool to the Pi coding agent, modeled after Anthropic's advisor tool pattern: the executor model keeps doing the work and only consults a stronger "advisor" model when it needs strategic guidance — not for syntax-level questions or routine implementation steps.

The advisor sees a curated transcript, understands the current task stage, and returns a verdict plus numbered action items.

Features

• Stage-aware guidance — automatically detects whether the executor is exploring, stuck, or ready for final verification, and tailors the advisor prompt accordingly
• Curated context — sends only relevant conversation history, bounded system prompt, and recent tool activity to keep token usage efficient
• Configurable model & effort — choose any provider/model and tune reasoning effort (minimal–xhigh), token budget, and context window
• Slash commands — /advisor on, /advisor off, /advisor config, /advisor ask with tab completion
• Compact TUI rendering — advisor output renders inline with token usage, stage label, and expand-to-read hint

Install

From npm

pi install npm:pi-advisor

From git

pi install git:github.com/RimuruW/pi-advisor

This is a pi package — install via npm, git, or local path.

Usage

Enable the advisor with the default model:

/advisor on

Enable with a specific model:

/advisor on anthropic/claude-fable-5

Commands

Command	Description
/advisor	Show current status
/advisor on [provider/model]	Enable advisor (optionally set model)
/advisor off	Disable advisor
/advisor config	Show full configuration
/advisor config key=value	Set a config value
/advisor ask	Manually trigger advisor consultation

Configuration

/advisor config maxContextMessages=24
/advisor config reasoning=xhigh
/advisor config maxTokens=16384

Key	Default	Description
provider	anthropic	Model provider
model	claude-fable-5	Model identifier
maxUsesPerRun	3	Max advisor calls per agent run
maxTokens	16384	Max output tokens per advisor call (thinking tokens count against this on adaptive-thinking models)
reasoning	high	Reasoning effort level (minimal, low, medium, high, xhigh)
maxContextMessages	18	Max transcript messages sent to advisor

Configuration persists to ~/.pi/agent/advisor.json.

Architecture

┌─────────────────────────────────────────┐
│              Executor (LLM)              │
│  ┌───────────────────────────────────┐   │
│  │  Decides when to call advisor      │   │
│  │  Reads advisor output & acts       │   │
│  └──────────────┬────────────────────┘   │
└─────────────────┼───────────────────────┘
                  │ advisor(params)
                  ▼
┌─────────────────────────────────────────┐
│           Advisor Extension              │
│                                          │
│  1. Detect current stage                 │
│     (initial / recovery / final-check)   │
│  2. Build curated context:               │
│     - Bounded system prompt              │
│     - Active tools summary               │
│     - Recent tool activity               │
│     - Transcript (first + last N msgs)   │
│  3. Call advisor model via pi-ai         │
│  4. Return verdict + action items        │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│           Advisor Model (LLM)            │
│  Stronger model, returns:                │
│  - Verdict: "On track" /                 │
│             "Course-correct" /           │
│             "Not done yet"               │
│  - Numbered action items (≤ 5)          │
│  - References to files, commands,        │
│    or error signals from transcript      │
└─────────────────────────────────────────┘

Stage Detection

The extension infers the executor's current stage from recent tool activity:

Stage	Trigger
initial	Exploratory reads/commands, no file mutations yet
recovery	Recent failure, or off-track implementation
final-check	Changes exist and verification output is in transcript

Project Structure

.
├── index.ts              # Extension entrypoint (tool + command registration)
├── src/
│   ├── advisor-messages.ts   # Transcript curation for advisor context
│   └── advisor-signals.ts    # Pure stage/signal detection logic
├── tests/
│   ├── advisor-signals.test.mjs  # Signal logic unit tests
│   └── package.test.mjs          # Package manifest & smoke tests
├── package.json
├── package-lock.json
├── tsconfig.json
├── CHANGELOG.md
├── README.md
└── LICENSE

Development

# Run typecheck + tests
npm run check

# Run tests only
npm test

# Smoke-load as an extension
pi -e ./index.ts

License

MIT. See LICENSE.