pi-advice

A Pi extension that gives the current work a second look. pi-advice asks a configured model—often a stronger or simply different model—to review Pi's progress, then lets the original model continue with that fresh perspective.

Use it when Pi is stuck, when you want a deliberate review, or when you want periodic check-ins during a long task.

Like this extension? See my other Pi extensions.

Requirements

• Pi 0.82.1 or later
• An authenticated model provider configured through Pi
• Node.js 22.19.0 or later for package development

Installation

From npm:

pi install npm:@arcanemachine/pi-advice

Or install directly from GitHub:

pi install git:github.com/arcanemachine/pi-advice

To update an npm installation later:

pi update npm:@arcanemachine/pi-advice

For local development from a checkout:

pi -e ./src/index.ts

Pi loads src/index.ts directly; a compiled runtime artifact is not required.

Quick start

Add a pi-advice namespace to global ~/.pi/agent/settings.json or to a trusted project's <project>/.pi/settings.json:

{
  "pi-advice": {
    "provider": "openai-codex",
    "model": "gpt-5.6-sol",
    "thinkingLevel": "high"
  }
}

Authenticate the provider in Pi, for example:

/login openai-codex

Then ask for a review:

/advise
/advise focus on correctness and overlooked risks

The advice appears as a normal assistant response. Pi then continues with the original model unless you use --stop.

Configuration

Pi reads the pi-advice namespace from its normal settings.json files:

| File | Scope | | ----------------------------- | ------------------------ | | ~/.pi/agent/settings.json | Global settings | | <project>/.pi/settings.json | Trusted-project override |

Project settings override matching global fields. Settings from an untrusted project are ignored.

| Field | Required | Description | | --------------- | -------- | ------------------------------------------ | | provider | Yes | Provider ID for the advisor model | | model | Yes | Model ID within that provider | | thinkingLevel | No | Advisor thinking level; defaults to high |

thinkingLevel can be off, minimal, low, medium, high, xhigh, or max. The merged configuration must provide non-empty provider and model. Unknown fields, malformed JSON, and invalid values are rejected with a source-specific diagnostic.

Keep credentials out of settings.json; authenticate providers through Pi with /login <provider>.

Commands

/advise

Start one review of the current work:

/advise [--tools|-t] [--stop|-s] [focus]

Examples:

/advise
/advise focus on whether the current approach matches the plan
/advise --tools inspect the relevant implementation before reconsidering
/advise -t -s

Options must come before the optional focus text. --tools and --stop can be combined in either order.

• --tools / -t lets the advisor make a minimal investigation with the active tools. Without it, the advisor uses conversation context only.
• --stop / -s gives the advice without asking the original model to continue. Without it, Pi queues a hidden continuation after the review.
• Focus text tells the advisor what to pay special attention to.

Pi rejects a manual review while another review or steering message is pending. Wait for the current work to settle and try again.

/advise-every

Schedule reviews during a longer task:

/advise-every <N> [--tools|-t] [--stop|-s] [focus]
/advise-every off

For example:

/advise-every 50 focus on correctness and overlooked risks
/advise-every 25 --tools
/advise-every 10 -s
/advise-every off

N is a positive integer. The schedule starts a review after every N completed turns from the original model, including turns that use tools. Review and continuation turns do not count. If other steering messages are pending at the threshold, the review waits until the queue is clear. Reissuing the command replaces the schedule and resets its count.

--tools, --stop, and focus text work the same way as they do for /advise. off disables future reviews but lets an active review finish safely. The schedule survives an idle /reload in the same Pi process, but not a process restart or a session change such as /new, /resume, /fork, or /clone. Pi provides autocomplete for the options and for off.

What happens during a review

1. Pi saves the active model, thinking level, and tools.
2. It switches to the configured advisor model and asks it to reconsider the current work.
3. It restores the original settings before continuing, unless --stop was requested.

Pi shows Advising... while the review is active. The review and continuation instructions are hidden from the normal transcript, so the advice reads as the assistant's own fresh realization rather than as a separate handoff.

The advisor may conclude that no material improvement is needed. It should say so rather than invent criticism or extra work. With --tools, the advisor is instructed to investigate only; it should not implement the task during the review.

Safety and limitations

• --tools is prompt guidance, not a sandbox. The active tools may still be capable of changing files or running commands.
• pi-advice supports Pi's default steeringMode: "one-at-a-time". The "all" steering mode is not supported.
• If the advisor fails, is cancelled, or produces no usable response, Pi restores the original state and does not continue.
• If Pi cannot restore the original model or settings, it does not continue, disables automatic advice, and tells you to select the intended model with /model.
• Extensions run with your full system permissions. Install pi-advice only from a source you trust.

Troubleshooting

• Advisor model not found: check the configured provider/model with /model or pi --list-models.
• No API key configured: run /login <provider>.
• Configuration invalid: fix the named settings field, then use /reload.
• Original state could not be restored: select the intended model manually with /model; automatic advice is disabled for safety.

Development

npm install
npm run format:check
npm run typecheck
npm run test
npm run build
npm pack --dry-run

Tests use a runtime-faithful fake Pi harness and make no model requests. Before release, verify the user-facing behavior in a running Pi session.

License

MIT. See LICENSE.md.