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