switchboard-fyi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Switchboard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,538 @@
+# Switchboard
+
+## Local routing CLI
+
+Switchboard is designed to sit in front of normal `codex` and `claude` usage.
+The install step creates local PATH shims so those commands route through
+Switchboard anywhere in the terminal.
+
+Install from npm:
+
+```bash
+npm install -g switchboard-fyi
+```
+
+Or install with Homebrew after the public tap is published:
+
+```bash
+brew install switchboardfyi/tap/switchboard-fyi
+```
+
+Installed CLI entrypoint:
+
+```bash
+switchboard
+```
+
+Bare `switchboard` opens the interactive local console. The published CLI
+supports macOS and Linux for launch; Windows shims are intentionally not
+included in this release.
+
+The interactive `start` action opens the live dashboard for that harness. It
+does not launch Codex or Claude Code.
+
+Harness state is runtime scoped:
+
+- `installed`: Switchboard is ready, but routing is off. Codex and Claude use
+  your normal model settings.
+- `observe`: `switchboard observe <harness>` is running in a terminal. Harness
+  calls go through Switchboard for logging, but models are preserved.
+- `routing`: `switchboard start <harness>` is running in a terminal. Harness calls
+  go through Switchboard and can be routed according to the selected profile.
+
+Closing the `start` or `observe` terminal turns that harness back to
+`installed`.
+
+Only one `start` or `observe` terminal can own a harness at a time. If Codex or
+Claude Code is already active in another window, Switchboard refuses the second
+start and shows the owning process id.
+
+Only one wrapped Codex or Claude Code session can run through Switchboard for a
+harness at a time. That keeps local gateways tied to visible terminal sessions
+instead of accumulating in the background.
+
+The home screen is harness-first: before a shim is active, each harness only
+offers `install`; after install, it offers `start`, `observe`, `settings`, and
+`uninstall`.
+
+Install the shims:
+
+```bash
+switchboard install
+```
+
+This writes `codex` and `claude` wrappers to `~/.switchboard/bin`, records the
+real binary paths in `~/.switchboard/install.json`, and adds a managed PATH
+block to your shell rc file. Open a new terminal after install. Then use the
+tools normally:
+
+```bash
+codex
+claude
+```
+
+To install one harness or remove the shims:
+
+```bash
+switchboard install codex
+switchboard install claude
+switchboard uninstall codex
+switchboard uninstall claude
+switchboard uninstall
+```
+
+Settings expose each installed harness model set, including the difficulty
+`1..5` model map for each harness.
+
+Run Codex through the Responses model-provider proxy:
+
+```bash
+codex
+```
+
+Codex must be routed at the model-provider boundary, not the app-server
+`turn/start` boundary. The canonical path is:
+
+```text
+codex -> Switchboard /v1/responses -> chatgpt.com/backend-api/codex/responses
+```
+
+This preserves ChatGPT/Codex subscription auth locally and exposes each internal
+Codex model request to Switchboard.
+Switchboard v1 supports ChatGPT subscription auth only for Codex. API-key Codex
+requests are rejected locally before routing, without spending a Switchboard
+request credit or forwarding to `api.openai.com`.
+
+Run Claude Code through the Anthropic-compatible gateway:
+
+```bash
+claude
+```
+
+Switchboard v1 supports Claude Code subscription OAuth only, including
+`CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`. Anthropic API-key,
+PAYG, Bedrock, Vertex, and Foundry auth paths are stripped or rejected before
+routing.
+
+Observe mode:
+
+```bash
+--observe
+```
+
+Switchboard API routing:
+
+```bash
+switchboard login
+switchboard balance
+switchboard config use-switchboard-api https://api.switchboard.fyi
+```
+
+The gateway sends a compact classification packet and local routing settings to
+the Switchboard API. The Cloudflare API owns the classifier prompt, checks
+credits, calls Workers AI, and returns difficulty `1..5`, a reason code, and a
+short dashboard task label. The local CLI maps that difficulty to the configured
+model for the active harness. A successful new API classification spends one request credit,
+including best and observe recommendations. It sends a compact routing summary,
+not the raw provider request, and the billing ledger does not store full
+prompts. If the API is unavailable or the account has no request credits, the
+dashboard records an explicit router error or insufficient-balance state.
+
+After that, this is enough:
+
+Terminal 1:
+
+```bash
+switchboard start codex
+```
+
+Terminal 2:
+
+```bash
+codex \
+  exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox \
+  "Reply with exactly: router-ok"
+```
+
+For an interactive Codex session, use:
+
+```bash
+codex
+```
+
+If the default local proxy port is already occupied, the wrapper automatically
+uses the next free port and prints the port it selected.
+
+Model catalog and difficulty map:
+
+```bash
+switchboard models
+switchboard models list
+switchboard models codex
+switchboard models claude-code
+switchboard difficulty
+switchboard difficulty set codex 5 gpt-5.5 xhigh
+switchboard difficulty set claude-code 3 claude-sonnet-4-6 medium
+```
+
+Switchboard classifies each request as difficulty `1..5`, then resolves that
+difficulty locally from the configured map for the active harness. Use
+`models` to inspect the bundled catalog and `difficulty set` to edit a single
+difficulty level. The default Codex map is:
+
+```text
+5  gpt-5.5       reasoning=xhigh
+4  gpt-5.5       reasoning=medium
+3  gpt-5.4       reasoning=medium
+2  gpt-5.4-mini  reasoning=medium
+1  gpt-5.4-mini  reasoning=low
+```
+
+For Codex, the three main-model choices are `gpt-5.5 reasoning=xhigh`,
+`gpt-5.5 reasoning=high`, and `gpt-5.5 reasoning=medium`. For Claude Code,
+the default map routes lower difficulty requests to Haiku/Sonnet and higher
+difficulty requests to Opus.
+
+The model catalog lists standard uncached input and output billing rates per
+million tokens: Codex uses Codex credits, and Claude uses USD API pricing.
+The local CLI dashboard shows requests and provider token usage from local
+responses. Account status shows hosted request counts; hosted token totals are
+shown only when token accounting is available. It does not show cost estimates.
+
+The bundled model catalog is curated and updates with new Switchboard releases.
+
+CLI updates:
+
+```bash
+switchboard update check
+switchboard update
+```
+
+After the npm package is published, `switchboard update check` reads the npm
+registry and `switchboard update` runs the package-manager update flow. The CLI
+also checks periodically and can show a TTY-only update prompt:
+
+```text
+✨ Switchboard update available! 0.1.0 -> 0.1.1
+
+Release notes: https://switchboard.fyi/release/latest
+
+  1. Update Switchboard
+  2. Skip
+```
+
+Skipping only applies to the current run; if the same version is still latest,
+Switchboard prompts again on the next interactive `switchboard` launch. Normal
+wrapped `codex` and `claude` runs never show this prompt. The latest npm result
+is cached in `~/.switchboard/update-state.json` so normal Switchboard launches
+do not hit the registry every time.
+
+Component status:
+
+```bash
+switchboard status
+switchboard status set codex needs-update "Codex harness needs a Switchboard update"
+switchboard status set claude down "Claude harness temporarily disabled"
+switchboard status set switchboard api degraded "Classifier API latency is elevated"
+switchboard status clear codex
+switchboard config set componentStatus.url https://status.example.com/switchboard.json
+switchboard status refresh
+```
+
+`status set` writes a local override to `~/.switchboard/config.json`. By default,
+remote component status is read from `<api.baseUrl>/v1/status`. That API-owned
+feed is the production source of truth for `claude`, `codex`, and `api`
+compatibility. Its steady state should be `ok`; `unknown` is only a local
+fallback when no status source has been read.
+
+Production incidents should be handled through the API status feed, not local
+overrides. The operational runbook is in
+`docs/component-status-runbook.md`.
+
+Use API-level component status when an upstream Claude Code or Codex release
+breaks Switchboard compatibility, or when the Switchboard API itself is
+degraded. The CLI renders `ok` as a checkmark and `degraded`, `needs_update`,
+or `down` as attention states. For incidents that should use a different feed,
+publish a small JSON manifest at `componentStatus.url`; the CLI caches it in
+`~/.switchboard/component-status.json` and still allows local overrides for
+testing or emergency support.
+
+Manifest shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "updatedAt": "2026-05-19T12:00:00Z",
+  "components": {
+    "codex": { "state": "ok" },
+    "claude": { "state": "needs-update", "message": "Run switchboard update before using Claude Code." },
+    "api": { "state": "degraded", "message": "Classifier latency is elevated." }
+  }
+}
+```
+
+Logs:
+
+```bash
+switchboard watch codex
+switchboard watch claude-code
+switchboard inspect
+switchboard inspect --harness codex
+switchboard inspect --harness claude-code
+switchboard status codex
+switchboard config show
+switchboard dashboard --local codex
+switchboard dashboard --local claude-code
+switchboard watch codex
+switchboard logs codex
+tail -f ~/.switchboard/harnesses/codex/events.jsonl
+tail -f ~/.switchboard/harnesses/claude/events.jsonl
+```
+
+Switchboard keeps runtime logs and health state per harness under
+`~/.switchboard/harnesses/<harness>/`, while global config remains shared.
+Use `switchboard inspect` for the local web inspector. It groups calls by
+`decisionId` and shows the routing payload, API/router response, applied
+route, forwarding status, and raw JSONL events.
+
+More detail is in `docs/mvp-usage.md`, `docs/codex-subscription-provider-proxy.md`,
+`docs/routing-api.md`, `docs/known-limitations.md`, and `docs/smoke-test.md`.
+
+## 1-Page Product Spec
+
+Switchboard — 1-Page Product Spec
+Product summary
+
+Switchboard is an API-directed model-routing gateway for developers using tools like Claude Code, Codex, and future AI coding harnesses.
+
+Developers keep using their existing tools exactly as normal. Switchboard sits behind the harness as the model endpoint, asks the Switchboard API where to route, tries the recommended cheaper model when directed, and automatically falls back to the original model if the routed provider call fails before useful output is sent.
+
+Use the right model without thinking about it.
+
+Core promise
+
+Switchboard does one thing:
+
+Route when the Switchboard API says to route, and protect the developer with automatic original-call fallback.
+
+It does not rewrite prompts, compact context, modify tools, change agent behavior, or interfere with the developer’s workflow.
+
+Problem
+
+Developers love Claude Code and Codex because the harness is already excellent: repo awareness, shell access, tool use, patches, context handling, and workflow muscle memory.
+
+But these tools often use expensive models for tasks that do not need them:
+
+Rename this variable
+Write a PR description
+Explain this small error
+Summarize this diff
+Make this copy clearer
+
+At the same time, many tasks genuinely deserve the strongest model:
+
+Fix this auth bug
+Refactor this module
+Debug failing tests
+Think through this architecture
+Make a complex multi-file change
+
+Today, users have to manually decide which model is worth using. Most will not. So they either overspend or risk underpowering important work.
+
+Target users
+
+Initial users are AI-heavy developers, indie hackers, founders, and small teams who already use Claude Code, Codex, Cursor, or similar tools daily.
+
+They want:
+
+- lower AI model spend
+- less top-tier quota waste
+- no workflow migration
+- no degraded quality on hard tasks
+- simple override controls
+Non-goals
+
+Switchboard v1 should be intentionally narrow.
+
+It should not do:
+
+- prompt rewriting
+- context compaction
+- tool blocking
+- repo analysis
+- validation loops
+- custom agent behavior
+- coding-agent replacement
+- new IDE/chat interface
+
+The trust boundary is simple:
+
+Switchboard only chooses the destination model.
+
+How it works
+Claude Code / Codex
+        ↓
+Switchboard Gateway
+        ↓
+Route Classifier
+        ↓
+Lower-cost model OR strongest model
+        ↓
+Response streams back to original harness
+
+The user configures their tool to use Switchboard as the model endpoint.
+
+Example model alias:
+
+model = "auto"
+
+Switchboard maps `auto` to the model configured for the API-assigned
+difficulty. It maps `auto` to the configured best model when preserved,
+uncertain, or falling back.
+Routing policy
+
+Switchboard classifies each request into difficulty `1..5`:
+
+- `1` → trivial, exact, mechanical, or simple text work
+- `2` → light routine text or bounded work
+- `3` → normal bounded coding or analysis
+- `4` → substantial multi-step, tool-driven, or multi-file work
+- `5` → hard debugging, architecture, large context, or high-risk work
+
+The API owns difficulty classification. The CLI owns model selection,
+execution, retry, and narrow routed-path cooldowns after real routed failures.
+
+Default principle:
+
+Route to save money when the API recommends it; fall back to the original model when execution proves that route unhealthy.
+
+Lower-tier examples
+- naming
+- simple rewrites
+- small explanations
+- commit messages
+- PR descriptions
+- formatting
+- command generation
+
+Mid-tier examples
+- summarizing short diffs
+- simple terminal-output explanation
+- large-context summarization
+- straightforward single-file edits
+- routine config/docs work
+
+Best-tier examples
+- bug fixing
+- auth/payments/security work
+- refactors
+- multi-file edits
+- test failures
+- architecture decisions
+- unclear requirements
+- consequential security review
+- repeated failed attempts
+- anything the router is unsure about
+Product modes
+1. Observe
+
+No routing. Switchboard only reports what it would have done.
+
+12 calls would have been preserved on the strongest model.
+7 calls could likely have used cheaper routing.
+2. Auto
+
+Switchboard automatically routes obvious low-risk calls down and preserves the strongest model for everything else.
+
+Three routing modes:
+
+- `Quality`: prioritize the strongest model for harder work while still routing clear low-risk waste
+- `Balanced`: recommended default for everyday sessions
+- `Saver`: route more aggressively to reduce spend while still protecting high-risk work
+User experience
+
+The product should be quiet.
+
+The developer still runs:
+
+claude
+
+or:
+
+codex
+
+Optional session receipt:
+
+Disabled by default. Enable it with:
+
+```bash
+switchboard config set sessionReceipt.enabled true
+```
+
+Switchboard session receipt
+
+Requests: 8
+Tokens processed: 42k
+Cheap-route retries: 0
+
+Power-user overrides:
+
+auto
+lower
+best
+MVP
+Must-have
+- gateway endpoint
+- Claude Code / Codex setup instructions
+- model alias: auto
+- API-directed route classifier
+- difficulty-to-model mapping
+- streaming response passthrough
+- request/cost logging
+- session receipt
+- user override: force best
+Should-have
+- observe mode
+- auto mode
+- simple dashboard
+- per-project settings
+- routed-request regret tracking
+Success metrics
+
+Primary metric:
+
+Best-tier requests avoided without increasing retries.
+
+Track:
+
+- strongest-model requests avoided
+- tokens processed
+- routed-request retry rate
+- user override rate
+- router disable rate
+- preserved-request rate
+- cost per accepted task
+
+Most important quality metric:
+
+Lower-tier regret rate
+
+Meaning:
+
+How often did a user rerun, override, or escalate after Switchboard used a lower-cost tier?
+
+That number must stay low.
+
+Positioning
+
+Simple version:
+
+Switchboard routes AI coding requests through the Switchboard API and falls back to the original model when a routed provider call fails.
+
+Developer version:
+
+An API-directed model-routing layer for Claude Code, Codex, and other AI coding harnesses. Keep your workflow. Cut wasted top-tier calls. Fall back safely.
+
+Punchier tagline:
+
+Use your strongest model where it matters.