Model Switchboard is an experimental routing layer for AI-assisted software delivery.

Its goal is to keep coding sessions moving by choosing model and effort settings before each turn, so you do not have to make that call manually every time.

The project is still exploring the product shape for automatic model hot-swapping. It is useful today as a Claude Code routing wrapper and as a Codex feasibility spike, but it is not yet a polished replacement for an existing AI coding workflow.

Choosing the right model repeatedly is a real cognitive tax. A single coding session can shift between quick clarifications, planning, implementation, and debugging, each with different cost and quality needs.

Model Switchboard explores reducing that overhead with consistent routing decisions and a short explanation of why a route was selected.

• Fewer manual model-selection decisions during active development.
• Better default cost and quality tradeoffs by task type.
• Session-aware continuity across routed turns.
• Clear, auditable decisions through concise route explanations and local evidence logs.

The current MVP is a Claude Code workflow integration powered by a separable router core. The Codex work is an active spike to test whether Switchboard can go beyond advisory routing and actually control per-turn model changes inside one continuous session.

High-level flow:

1. You send a prompt through Switchboard.
2. Switchboard classifies the turn and selects a route label.
3. Switchboard launches or resumes Claude with matching model and effort settings for that launch.
4. Route context, session state, and hook evidence are recorded for explainability, replay, and governance.

Switchboard currently has three distinct paths. They are intentionally not equivalent.

This is the most complete path today.

Use:

switchboard "your prompt"
switchboard --interactive
switchboard explain

What it allows:

• Routes each prompt before launching or resuming Claude.
• Applies model and effort choices at Claude launch/resume boundaries.
• Records local routing evidence for explainability and replay.

Advantages:

• Most productized workflow in this repository.
• Uses the existing Claude Code user experience.
• Good fit for prompt-by-prompt routing with auditability.

Does not yet support:

• Automatic model changes inside an already-running Claude interactive session.
• Eliminating the cognitive overhead of model choice during a long-lived stock Claude TUI session.

This path gives a recommendation without taking over execution.

Use:

switchboard advise --surface openai-codex "your prompt"

What it allows:

• Asks Switchboard what it would choose for a target surface.
• Lets you keep using another client manually.

Advantages:

• Low-risk way to test routing policy across vendors or clients.
• Does not require Switchboard to own the session process.

Does not yet support:

• Automatic execution.
• Automatic in-session model switching.
• Reducing all model-selection overhead, because the user still has to apply the recommendation.

This is the experimental hot-swapping path.

Use:

npm run switchboard:spike:codex-app-server:preflight
npm run switchboard:spike:codex-app-server:protocol
npm run switchboard:spike:codex-app-server:lifecycle
npm run switchboard:spike:codex-app-server

What it allows:

• Starts codex app-server --listen stdio://.
• Creates one Codex app-server thread.
• Sends multiple turn/start requests on that same thread.
• Requests different models on different turns without a codex exec resume boundary.

Advantages:

• This is the only current path that suggests Switchboard could go beyond Claude parity.
• It demonstrates a possible Switchboard-owned session surface with per-turn model override.
• It preserves one app-server thread/session while route-selected model requests change.

Does not yet support:

• A polished end-user UI.
• Hot-swapping inside the stock Codex TUI.
• Production stability guarantees, because the app-server surface is still experimental.
• Provider-side backend model attestation; current evidence proves requested model overrides and same-thread completion, not a durable backend model field.

• Not a finished replacement for your coding client.
• Not a general-purpose agent runtime.
• Not a claim that stock Claude or stock Codex TUI sessions can be hot-swapped today.
• Not a production-grade cross-vendor orchestration product in this MVP phase.

The commands below mix productized MVP commands and spike commands. Commands containing spike are feasibility evidence for the Codex direction, not polished product UX.

switchboard --interactive selects model/effort at launch, then enters Claude interactive mode with that selection.

Inside that active Claude session, Switchboard does not automatically switch to a different model on later user messages.

If you want per-turn re-routing and potential target/model changes, run prompts through Switchboard as separate turns (for example: switchboard "..." each turn) rather than staying in one interactive session.

1. Send one routed prompt: switchboard "Implement the retry logic for stale session recovery."
2. Inspect why the route was chosen: switchboard explain
3. Validate behavior before opening a PR: npm test

For detailed command documentation, environment variables, and output formats, see CLI Reference.

• Obtain the software:
  • GitHub repository: https://github.com/hannasdev/model-switchboard
  • npm package: https://www.npmjs.com/package/model-switchboard
• Provide feedback (bug reports and enhancements):
  • Issues: https://github.com/hannasdev/model-switchboard/issues
• Contribute to the project:
  • Contribution guide: CONTRIBUTING.md

This project prioritizes security for AI-related software:

• Vulnerability Scanning: Automated dependency scanning via npm audit in CI on pull requests and pushes to main, plus Snyk scans on pushes to main and a daily schedule when SNYK_TOKEN is configured
• Static Analysis: ESLint with security plugin to detect common vulnerabilities
• Responsible Disclosure: Follow the Security Policy to report vulnerabilities privately
• Test Coverage: Comprehensive test suite validates security-relevant code paths
• Developer Knowledge: Core team has expertise in secure software design and threat modeling

See SECURITY.md for details on the vulnerability reporting process and security practices.