Open-source model and reasoning effort routing for coding agents.
Automatic model selection for Claude Code and Codex.
Website · Get started · How it works · Customize your policy · Contribute
Switchboard automatically selects a model and reasoning effort for Claude Code and Codex. Jev or experimental self-hosted Laya assesses the task; your routing policy makes the final choice. It runs inside the coding CLI you already use, keeping the selected pair fixed through follow-ups, tool calls, and resume.
Use it for implementation, debugging, code review, and documentation. You can also route writing, research, and other tasks inside those CLIs; the default routing criteria currently emphasize software engineering.
A real Codex session: submit a task and see Switchboard's model and effort choice.
- Task-aware decisions. Use hosted Jev, the default System One classifier, or experimental self-hosted Laya for structured task judgments. Your routing policy selects the model and effort.
- Stable conversations. Model and effort stay fixed through tool calls, follow-ups, and resume. A new conversation gets a fresh routing decision.
- Your policy. Use the defaults, exclude unavailable models, or customize model tiers, effort caps, confidence thresholds, and fallback behavior.
- Open source and free to use. Apache-2.0. All Switchboard routing code is available to inspect, change, and run yourself. No Switchboard account or subscription; hosted classifier and native-provider usage are billed separately.
- Local control. The proxy and route history run on your machine. No Switchboard telemetry or hosted routing service. Classification runs through your chosen Jev provider or Laya server; see privacy and data flow.
| Metric | Measured result |
|---|---|
| Median Jev classification latency | 0.55 seconds |
| p95 Jev classification latency | 0.67 seconds |
| Normalized cost per 1,000 classifications | About US$0.62, including reporting tags |
Classifier requests only. Actual latency and cost vary.
You need:
- macOS or Linux for this first release.
- Node.js 22.18+ and npm. The Homebrew installation also installs Node.
- Claude Code or Codex, installed and signed in. Follow the Claude Code quickstart or Codex CLI setup first.
- A Jev API key from TypeSafe, Vercel AI Gateway, or OpenRouter, or a self-hosted Laya server (experimental). See Laya setup.
Switchboard uses your agent's existing login and does not install the agent for you. Choose one package manager for your global installation.
npm
npm install -g @ruban24/switchboard
switchboard init
switchboard doctor
switchboard claude
# Or: switchboard codexHomebrew
brew install ruban-24/tap/switchboard
switchboard init
switchboard codexnpx (no global installation)
npx --package=@ruban24/switchboard switchboard init
npx --package=@ruban24/switchboard switchboard claudeswitchboard init walks you through three choices:
- Detect installed coding agents and choose which to enable.
- Select a Jev provider and enter your API key in a hidden prompt, or point to your own Laya server.
- Optionally add a configuration path to your shell profile.
If your connection uses a key, it is saved in a file readable only by your user. You can launch immediately, with no alias or shell restart. Running setup again preserves your personal policy.
Setup makes no AI calls. doctor checks your policy, enabled agents, and whether
a key is present; your first routed task tests the connection. If Codex reports
that a routed model is missing, Claude reports "Usage credits are required
for this model" for Fable, or your Claude Code is too old for Opus 5.5
(2.1.280 or newer), run switchboard doctor in a terminal: it walks you
through the fix. Use switchboard config to change models, effort limits, and
other settings from a menu, without editing JSON.
See classifier connections for endpoints, privacy for what leaves your machine, and the installation guide for shell profiles, environment overrides, updates, and removal.
Run Laya on your machine to keep task classification local, then choose
Self-hosted Laya during switchboard init. Switchboard applies the same
routing policy and pins the chosen model and effort for the conversation.
Your existing Claude Code or Codex login still handles coding inference.
The tested setup uses Laya 0.3.20 with the English checkpoint. Tasks longer than 700 characters use the uncertain fallback for a new conversation. Low-confidence answers retain conservative policy behavior; routing quality against Jev has not yet been evaluated. Running Laya yourself avoids hosted classifier API charges; hardware, hosting and coding-provider costs still apply.
Read the Laya router guide for Claude Code and Codex for an overview, or follow the local server setup.
Clone the repository, build, and use the same setup:
git clone https://github.com/ruban-24/switchboard.git
cd switchboard
npm ci
npm run build
npm run switchboard -- init
npm run switchboard -- doctor
npm run switchboard -- claude
# Or: npm run switchboard -- codexFrom a checkout, npm run switchboard also loads .env.local if present;
those values override saved connection settings. Installed commands do not
load project environment files.
Switchboard makes two related decisions:
- Model: which model has enough capability for the task?
- Effort: how much reasoning effort does that model need?
A stronger model at low effort and a smaller model at maximum effort are different choices. Switchboard does not treat them as interchangeable points on one scale.
Illustrative example: a System One model (Jev) supplies judgments and confidence; your policy makes the final choice. View the static diagram.
The local proxy extracts the user task and sends one request to Jev. Jev returns structured answers and probabilities; the selected model still does the work.
Jev considers how familiar the work is, what remains uncertain, which constraints interact, and how much analysis is needed. These are criteria for its judgments, not separate numeric scores. Prompt length alone does not determine the route.
| Judgment | What Jev returns | How Switchboard uses it |
|---|---|---|
| Capability needed | Fast, balanced, strong, or highest | Maps to a model through your policy. |
| Enough context to classify? | Yes or no | Uses the configured fallback when difficulty cannot be estimated. |
| Effort for each eligible model | Low, medium, high, xhigh, or max | Reads the answer for the model policy actually selects. Haiku needs no effort answer. |
| Task type | Explain, edit, implement, debug, review, architecture, or other | Records it for diagnostics; it does not set the model tier. |
Each judgment includes a confidence value from 0 to 1:
- Capability and selected-model effort have separate policy thresholds. Both default to 0.70.
- Task-type and context confidence are recorded for diagnostics.
Confidence describes how decisive the classification is, not the probability that the selected model will complete the task correctly. TypeSafe explains confidence here.
Shipped defaults merge with your personal overrides. Policy then determines:
- Model selection. Map the capability tier to a model and respect your exclusions. Low model confidence applies a balanced minimum; a stronger proposed tier stays stronger.
- Effort selection. Read the selected model's effort answer, apply effort confidence rules and profile defaults, then apply your effort mappings or caps.
- Fallback. If Jev is unavailable or cannot classify the task, use the configured fallback for the new conversation.
Your policy also determines which models get effort questions in the first place. Those conditional questions are bundled into the same Jev request; there is no second call after model selection. The local policy makes the final choice.
The native provider executes the task. Switchboard saves the selected model and effort locally, then:
- Reuses that pair for the conversation, including tool continuations.
- Skips classification for tool continuations.
- Can recommend a stronger route for a new conversation after a later user turn, without changing the active one.
Routing explanations describe the policy decision. Review the result as you normally would; a confident classification does not guarantee a correct answer.
For implementation details, see the architecture and routing rules, request/response examples, and personal policy guide.
| Tier | Intended work | Claude Code | Codex |
|---|---|---|---|
| Fast | Mechanical edits and simple, bounded requests | Haiku | GPT-6 Luna |
| Balanced | Everyday implementation, familiar algorithms and scoped changes | Sonnet | GPT-6 Sol (medium default) |
| Strong | Difficult debugging or consequential correctness decisions | Opus 5.5 | GPT-6 Sol (high default) |
| Highest | Exceptional reasoning or extensive work beyond the strong tier | Fable | GPT-6 Astra |
GPT-6 has no Terra model, so Sol serves both middle Codex tiers with a different default effort for each. GPT-5.6 Terra remains available in personal policy while Codex offers it; see customization.
For example, an LRU cache implementation ordinarily fits the balanced tier;
reviewing concurrent money transfers may need the strong tier. These describe
the policy's intent, not fixed prompt-to-model rules. Effort is assessed
separately for the selected model. Haiku gets no effort parameter; the other
configured models support mappings for low, medium, high, xhigh, and
max. See routing and policy for the exact rules.
Coding agents repeatedly send shared context: instructions, tool definitions, conversation history, and code. Provider prompt caching can reuse that work. Moving a conversation to another model can lose that reuse, so a cheaper model midway through a task can still produce a more expensive overall run.
Switchboard keeps both model and effort fixed for the whole conversation. Although some providers offer model-specific cache-preserving effort updates, Switchboard has not yet verified and implemented them through its supported native CLI paths.
- Follow-up prompts, tool calls, and resume keep the saved pair.
- Start a new conversation for an independent task or a stronger-model recommendation.
- An explicit native model choice still overrides automatic routing.
This avoids cache disruption caused by Switchboard changing the active model or effort. It cannot guarantee a cache hit: provider expiration, context changes, compaction, and native CLI behavior still matter. See the Anthropic and OpenAI caching documentation for provider behavior.
- Claude Code: the Switchboard status line shows the selected model and effort
below your existing status line. The model label reads
switchboard. - Codex: a routing notice shows the selected pair in the conversation.
The header reads
switchboard auto.
Those labels identify automatic routing. The status line or notice shows the model actually selected. An illustrative initial selection and follow-up look like this:
[Router] gpt-6-sol / medium — Jev capability and effort selection.
[Router] gpt-6-sol / medium — pinned for this conversation.
For either CLI, inspect a saved conversation with:
switchboard explain claude CONVERSATION_ID
switchboard explain codex CONVERSATION_IDUse the native session UUID as CONVERSATION_ID. The
session guide shows how to
find it and resume through Switchboard. From a source checkout, use
npm run switchboard -- explain in place of switchboard explain.
explain shows the active model and effort, the policy reason, confidence
adjustments, and any recommendation for a new conversation.
Native CLI details explain this behavior.
Route metadata is stored locally without raw prompts by default. You can inspect the decision without enabling task-text logging.
Personal settings live at ~/.config/switchboard/policy.json by default.
Run doctor to find the actual path. You can change:
- Model choices: exclude unavailable models or change which model each tier uses.
- Reasoning effort: remap effort levels or cap the effort a model can use.
- Decision rules: adjust confidence thresholds and fallback models.
For example, exclude models your plan cannot use or tiers you prefer not to spend on:
{
"excludedModels": {
"claude": ["claude-fable-5-1"],
"codex": ["gpt-6-astra"]
}
}To apply a personal override:
- Edit your personal
policy.json. Only include settings you want to change; objects merge with the defaults, while arrays replace them. - Run
switchboard config checkto validate it andswitchboard config showto inspect the merged policy. - Relaunch Switchboard and start a new conversation. Existing conversations retain their saved pair.
Keep overrides in your personal file so package updates preserve them. The customization guide explains each option and its effect.
For setup errors or a route that keeps falling back, see troubleshooting. The installation guide covers updates, uninstallation, and saved settings.
The policy reference also covers profiles, timeouts, and local history settings.
Switchboard is fully open-source software, with no Switchboard backend receiving your prompts. You control the code, keys, policy, and local route history.
- Classification: the classifier receives extracted task text, including any code or secrets you put in that prompt. Jev is hosted; with Laya running on your machine, classification stays local. A remote Laya server receives the task on the host you configure.
- Native inference: requests go to your native provider.
- Local logging: raw-prompt logging is off by default. Native transcripts and provider retention are separate.
Read the data flow before using it with sensitive work.
- Agents: Claude Code and Codex in local interactive CLI sessions.
- Platforms: macOS and Linux. Both adapters have passed interactive validation on macOS and a Debian Linux VM with native sandboxing.
- Classifier: Jev through TypeSafe, Vercel AI Gateway, or OpenRouter, or a self-hosted Laya server (experimental).
Native Windows, desktop-app routing, remote/background sessions, and custom model gateways are outside v0. See native CLI compatibility for tested versions and limitations.
- Pi (coming soon)
- OpenCode (coming soon)
- Kev (coming soon)
- Cua-S1 (coming soon)
Each classifier needs an adapter for its judgments and confidence format. A new endpoint alone does not make a different model compatible.
- Contribute code or report a routing problem: start with
CONTRIBUTING.md for setup, checks, and native adapter guidance.
Run
npm testandnpm run test:packagebefore submitting a code change. - Report a vulnerability: follow SECURITY.md.
- Read release notes: see CHANGELOG.md.
If you would like to support development, you can sponsor me or buy me a coffee.
Apache-2.0. Copyright 2026 Ruban. See NOTICE and third-party licenses.
If Switchboard helped you, please give it a star ⭐.