---
slug: "pi-external-advisor"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/hwei/pi-external-advisor@master/README.md"
repo: "https://github.com/hwei/pi-external-advisor"
source_file: "README.md"
branch: "master"
---
# 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](https://github.com/RimuruW/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](https://developers.openai.com/codex)** — `codex exec`
- **[Claude CLI](https://docs.anthropic.com/en/docs/claude-command-line)** — `claude -p`

---

## Installation

```bash
npm install pi-external-advisor
```

Or load it directly in pi:

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

---

## Quick start

```bash
# 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](https://github.com/RimuruW/pi-advisor).

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

See [LICENSE](https://github.com/hwei/pi-external-advisor/tree/HEAD/LICENSE) for the full text.