pi-external-advisor

Pi extension that replaces pi's built-in LLM provider call with an external agent CLI (Codex CLI or Claude CLI) for strategic advisor consultation.

---

What is this?

pi-advisor is a pi extension that registers an advisor tool — when the executor model calls it, the advisor receives a curated transcript and returns strategic guidance (verdict + action items).

The original pi-advisor calls completeSimple() through pi's built-in LLM provider system. This fork replaces that call with execSync() to an external agent CLI, so you can use Codex CLI or Claude CLI as the advisor backend instead.

Key differences from pi-advisor

Aspect	pi-advisor	pi-external-advisor
LLM backend	pi's provider system (completeSimple())	External CLI (spawn())
Configuration	provider, model, maxTokens, reasoning	cliCommand + per-CLI model/reasoningEffort, timeoutMs
Command syntax	/advisor on anthropic/claude-fable-5	/advisor on codex + interactive /advisor config menu
TUI display	Token counts (↑↓)	CLI name + elapsed duration
Dependencies	@earendil-works/pi-ai	No pi-ai dependency; requires external CLI installed

---

Prerequisites

You need at least one of these CLIs installed and configured on your system:

• Codex CLI — codex exec
• Claude CLI — claude -p

---

Installation

npm install pi-external-advisor

Or load it directly in pi:

pi -e node_modules/pi-external-advisor/index.ts

---

Quick start

# Enable advisor with Codex CLI
/advisor on codex

# Or with Claude CLI
/advisor on claude

# Open the interactive settings menu (model, reasoning effort, timeouts, …)
/advisor config

# Then call the advisor tool from the executor
# (the executor will call advisor() automatically based on guidelines)

---

Commands

Command	Description
/advisor on [cli]	Enable advisor with the given CLI (codex or claude)
/advisor off	Disable advisor
/advisor config	Open the interactive settings menu (TUI); shows a text summary in non-TUI modes
/advisor config key=value	Set a config value directly (scriptable alternative to the menu)
/advisor ask	Trigger a consultation manually

Configuration keys

Key	Default	Description
cliCommand	codex	Active CLI: codex or claude
model	(CLI default)	Model override for the active CLI (saved per CLI). Passed as --model <value>
reasoningEffort	(CLI default)	Reasoning effort for the active CLI (saved per CLI). codex: -c model_reasoning_effort=<v>; claude: --effort <v>
timeoutMs	300000	Max execution time (5 min)
maxUsesPerRun	3	Max advisor calls per run
maxContextMessages	18	Max transcript messages sent to advisor

model and reasoningEffort are stored per CLI (clis.codex / clis.claude in advisor.json), so switching CLIs never carries over settings that the other CLI would reject. Legacy single-slot configs are migrated automatically on load.

Model / effort discovery and validation

Valid values are discovered from your system at session start:

• codex — model slugs and each model's supported reasoning efforts are read from ~/.codex/models_cache.json and models_catalog_*.json. This list is exhaustive, so unknown models/efforts are rejected and auto-corrected.
• claude — effort values and model aliases are parsed from claude --help. Model names stay free-form (any full model ID is accepted); only effort values are validated.

If the stored config turns out invalid at session start (e.g. a model was removed or its effort list changed), it is auto-corrected and a warning is shown. Discovery failures fall back to a built-in static list.

How it works

1. The executor calls advisor({ stage }) with an optional stage hint
2. pi-external-advisor curates the conversation transcript (stage detection, tool activity summary, executor signals)
3. The curated context is piped via stdin to the external CLI
4. The CLI's response (JSON/JSONL) is parsed and returned as advice
5. The executor receives a verdict (On track / Course-correct / Not done yet) + action items

Session resume (KV-cache friendly)

The first consultation in a pi session starts a fresh CLI session and records its id (session_id from claude -p --output-format json, thread_id from codex exec --json). Subsequent consultations resume that session (claude -p --resume <id> / codex exec resume <id>) and send only the transcript delta since the last call, so the provider-side prompt/KV cache stays warm instead of replaying the full transcript as a brand-new conversation each time.

The session is dropped and a fresh one started automatically when:

• the CLI, model, or reasoning effort changes
• the pi transcript is no longer a pure extension of what the advisor saw (branch switch, compaction)
• resuming fails (expired/GC'd session) — the call transparently retries fresh

---

License

MIT License. Forked from RimuruW/pi-advisor.

Copyright (c) 2026 RimuruW
Copyright (c) 2026 hwei

See LICENSE for the full text.