pi-codex-router

Deterministic Codex model and thinking-level routing for Pi.

pi-codex-router automatically selects configurable Luna, Terra, or Sol models and their thinking level for coding tasks. It uses local prompt and repository signals—not another model—to keep routine work inexpensive and escalate complex work before each Pi agent turn.

Status: pi-codex-router is published on npm.

Installation

Install globally:

pi install npm:pi-codex-router

Or install for the current project:

pi install -l npm:pi-codex-router

Try a package for one Pi run without persisting it:

pi -e npm:pi-codex-router

Pin a version when needed:

pi install npm:pi-codex-router@<version>

Pi packages execute with your user permissions. Review package source before installing it.

Usage

Routing is automatic. Restart Pi or run /reload after installation, then send a normal prompt.

Use the /codex-router command to inspect or control the current session:

/codex-router status
/codex-router enable
/codex-router disable
/codex-router override balanced high
/codex-router override provider/model-id medium
/codex-router clear

status reports the selected profile, resolved model ID, and Pi's effective thinking level. Choosing a model or thinking level manually in Pi takes precedence over the router for that session.

Typical Routes

Request	Profile	Thinking
Rename a symbol, fix a typo, format code	fast	low
Explain a line of code	fast	low
Explain a security/authentication issue	balanced	medium
Plan a database migration	advanced	high
Fix a small regression	balanced	low–medium
Implement a normal feature	balanced	medium
Refactor a module	balanced	high
Debug a race condition	advanced	high
Redesign an architecture	advanced	high

The default profile mappings are:

Profile	Default model	Intended work
fast	openai-codex/gpt-5.6-luna	Small, low-risk tasks
balanced	openai-codex/gpt-5.6-terra	Everyday development
advanced	openai-codex/gpt-5.6-sol	Complex debugging and architecture

These are configurable model IDs, not assumptions about every Pi installation.

How It Works

The router combines deterministic prompt classification with bounded local repository signals. Model selection and thinking selection are independent: Terra can use high thinking for a difficult refactor, for example.

It considers:

• task and risk language;
• prompt-mentioned file count;
• approximate repository file count and language mix;
• unstaged Git diff size; and
• the prior route only to avoid switching between closely scored tasks.

Repository inspection skips .git, .pi, and node_modules, uses a short cache, and falls back to neutral signals if inspection fails. Repository signals are modifiers, not decisions by themselves.

Before every routed prompt, the router announces the applied profile, resolved model ID, and Pi's effective thinking level. Each new prompt is treated as a task boundary, allowing the router to downgrade after an unrelated expensive task; hysteresis still avoids switches for genuinely similar work. Pi must accept a route change before the router records it, and status reports Pi's effective thinking level if Pi clamps the requested level. A configured model that Pi cannot resolve falls back to the balanced profile when possible, then Pi's current model. An unavailable model must not prevent Pi from starting.

Configuration

Configuration uses JSON at these locations:

1. ~/.pi/agent/codex-router.json for global defaults.
2. .pi/codex-router.json for project overrides.

Project values override global values. Reload Pi after changing either file.

{
  "enabled": true,
  "models": {
    "fast": "openai-codex/gpt-5.6-luna",
    "balanced": "openai-codex/gpt-5.6-terra",
    "advanced": "openai-codex/gpt-5.6-sol"
  },
  "defaultThinking": "medium",
  "advancedThreshold": 70,
  "hysteresis": 12,
  "switchPolicy": "stable",
  "debug": false
}

Field	Default	Description
enabled	true	Enables automatic routing.
models.fast	Luna ID	Model ID or alias for small tasks.
models.balanced	Terra ID	Model ID or alias for everyday work.
models.advanced	Sol ID	Model ID or alias for complex work.
defaultThinking	medium	Thinking level for ordinary feature work.
advancedThreshold	70	Score for eligible advanced routing.
hysteresis	12	Score band that retains a stable route.
switchPolicy	stable	stable or always.
debug	false	Adds a compact route reason to each per-prompt notification.

Supported thinking levels are off, minimal, low, medium, high, xhigh, and max, subject to Pi and the selected model. Invalid configuration falls back safely to defaults and produces one compact warning after reload; an unavailable explicit model override is cleared with a warning.

Environment Overrides

export PI_CODEX_ROUTER_FAST_MODEL='provider/fast-model'
export PI_CODEX_ROUTER_BALANCED_MODEL='provider/everyday-model'
export PI_CODEX_ROUTER_ADVANCED_MODEL='provider/advanced-model'

Privacy and Limitations

The router runs locally. It does not send prompts, repository contents, diffs, credentials, or usage history to a routing service, and it does not call an LLM to classify work.

It is a heuristic, not a guarantee of the optimal route. Provider-qualified model IDs are more reliable than aliases. Budget awareness, failure-driven escalation, local history, and learned routing weights are intentionally not part of the first release.

Development

npm install
npm test
npm run check
npm pack --dry-run
npm publish --dry-run

To publish:

./publish-to-npm.sh

The prepublishOnly hook runs tests, type checking, and npm pack --dry-run before publishing.

See docs/routing.md for scoring, model resolution, and configuration details.

Contributing

Keep routing deterministic, explainable, and inexpensive by default. Improve the route matrix and tests before changing thresholds or adding features.

License

MIT