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-opus-4-6

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-opus-4-6	Model identifier
maxUsesPerRun	3	Max advisor calls per agent run
maxTokens	8192	Max output tokens per advisor call
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
├── tests/
│   └── package.test.mjs      # Package manifest & smoke tests
├── package.json
├── CHANGELOG.md
├── README.md
└── LICENSE

Development

# Run tests
npm test

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

License

MIT. See LICENSE.