Switchback
A local-first coding agent from Harville Labs. (Formerly Harness.) Most of the work runs on a model on your own machine; Switchback escalates the hard parts to the hosted model of your choice (OpenAI, Anthropic, DeepSeek, or any OpenAI-compatible API) and shows you exactly when and why it did.
- Local by default, remote when it matters. A transparent router sends each model call to your local model (Ollama, llama.cpp, LM Studio, vLLM, SGLang, KoboldCpp, Jan, TGI) and escalates to your remote provider (OpenAI, Azure OpenAI, Anthropic, DeepSeek, Gemini, Bedrock, Vertex, Claude Platform on AWS, Microsoft Foundry, OpenRouter, OpenCode, or any OpenAI-compatible API) when the local model is struggling, the context won't fit, or you ask. No vendor is a default, and every provider gets the same features. Budgets cap remote spend. With several local servers, escalation can climb through a bigger local model first (fast local → large local → remote), so only the last step costs money.
- Subagents that save money. Say "use 4 subagents to…" and Switchback starts four in parallel, each with its own brief, files, context, and routing; two never edit the same file. The model can also delegate searches and side tasks on its own. The built-in
explore agent always runs locally. Agents are Markdown files in .switchback/agents/, and model: large|medium|small means your provider's models of that size.
- Review with a stronger model. Optionally, a ladder of reviewers checks every change, and the writing model fixes what they find. A free local reviewer can check everything, with a remote one stepping in only when its findings don't get fixed: a remote review costs a few cents, while having the remote model write the change would cost many times more. See docs/review.md.
- Private files stay private. List paths that must never reach a remote model (
secrets/, *.pem, customer data); once a session touches one, it stays on local models for good, even if you ask for remote. Credentials in anything sent remotely are redacted first. See docs/privacy.md.
- Managed by your organization. Sign in with
switchback login and your org's server pushes approved models (including company GPU servers), spend caps, provider restrictions, or an outright remote-off switch, live. See docs/organizations.md.
- Terminal and VS Code, same engine. The TUI and the VS Code extension are thin clients of one engine and one protocol, and they render from the same view model, so they can't drift apart.
Status: 2.4. Progress is tracked in GitHub issues and the roadmap.
Install
On macOS or Linux:
curl -fsSL https://switchback.sh/install.sh | sh
On Windows, in PowerShell:
irm https://switchback.sh/install.ps1 | iex
The scripts (install.sh, install.ps1) download the binary for your machine from the latest GitHub release, check it against the release's SHA256SUMS, and put it in ~/.local/bin, without sudo or administrator rights. install.sh never edits your shell profile; install.ps1 adds the directory to your user PATH unless you pass -NoModifyPath. Options for install.sh go after sh -s --: --vscode also installs the VS Code extension, --version 0.5.0 picks a release, and --dir <path> installs elsewhere. install.ps1 takes -VSCode, -Version, and -Dir (run it as & ([scriptblock]::Create((irm https://switchback.sh/install.ps1))) -VSCode) or the SWITCHBACK_VERSION and SWITCHBACK_INSTALL_DIR environment variables.
Update the CLI in place with switchback self-update (or switchback self-update --check to see whether there's a newer release). It verifies the download the same way the installers do.
For VS Code alone, install Switchback from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback). It includes the engine. Use the terminal UI, the extension, or both: with both installed, they run the newer of the two engines and share live sessions.
Quick start
Start a local model server (Ollama, LM Studio, llama.cpp, or vLLM) with a model that supports tool calling, then:
switchback init # opens Switchback on setup: finds your local server, picks models
switchback doctor # check config, providers, and agents
switchback # open the TUI in the current directory
switchback run "explain src/index.ts" # headless, one prompt
From source
Requires Bun 1.4+. bun run dev -- stands in for switchback:
bun install
bun run dev -- --mock # try the TUI with scripted models, no setup needed
bun run dev -- init
Switchback ships with no default local model. Which server and model your machine runs is your choice, and switchback init (or /init inside Switchback) sets it up. Running switchback for the first time with no config opens on setup.
In the TUI, /local, /remote, and /auto control routing, Shift+Tab or /agent plan switches the session's agent (build, plan, or your own), /goal <objective> keeps working across turns until the objective is met, /rename names the session, /usage shows spend and savings, and esc cancels. The status line shows how much of each prompt the provider served from its cache.
The TUI shows a proposed edit before asking for permission:
The completed turn keeps the edit and test results in the transcript:
Press ctrl+o to expand the thinking and test output:
Regenerate these screenshots with bun run screenshots. The script uses a temporary demo project and scripted models.
How routing works
Every model call goes through the router, which picks the first matching rule:
- Your explicit choice for this turn (
/remote, --route local)
- The agent's pin (
model: haiku, route: local)
- Context overflow: the prompt won't fit the current model's window
- Stickiness: stay on the step an escalation reached for a couple of calls
- Quality signals: repeated tool errors, malformed tool calls, loops, refusals, or failures. Each escalation moves one step up
routing.escalate, which can hold any models, local or remote. Escalates automatically, asks first for remote steps, or does neither, per routing.escalation.policy.
- Default: the current model (
routing.current)
Budget and availability guards then apply. Over budget means staying local; a provider that's down means falling back to the other tier. Each decision appears in the UI with its reason. Details are in docs/routing.md.
Configuration
switchback init writes ~/.switchback/config.json (this machine) or .switchback/config.json (this project). You can also edit these files directly: switchback config edit opens one, switchback config show prints the merged result, and the VS Code extension validates and autocompletes both. A typical file:
{
"providers": {
"ollama": { "type": "openai-compatible", "baseUrl": "http://localhost:11434/v1" },
"openai": { "type": "openai" }
},
"models": {
"local": { "provider": "ollama", "model": "<your model>", "contextWindow": 32768 },
"remote": { "provider": "openai", "model": "gpt-6-sol", "contextWindow": 1050000 }
},
"routing": {
"escalation": { "policy": "ask" },
"budget": { "dailyUsd": 5, "monthlyUsd": 50 }
},
"permissions": { "edit": "ask", "bash": "ask" }
}
See docs/configuration.md for every option and examples/ for Bedrock, Vertex, and llama.cpp setups.
Repository layout
packages/
protocol/ engine <-> client contract: JSON-RPC methods, events, transcript types
providers/ model adapters: OpenAI-compatible (local), Anthropic/Bedrock/Vertex, mock
router/ pure routing decisions and escalation signals
engine/ sessions, agent loop, tools, permissions, subagents, config, usage ledger
client/ typed protocol client and the shared view model
apps/
cli/ `switchback` binary: TUI, run, serve --stdio, doctor, usage
vscode/ VS Code extension
docs/ architecture, routing, subagents, providers, protocol, ADRs
Development
bun run check # Biome lint + TypeScript + tests (what CI runs)
bun test --watch
To work on the VS Code extension, open this folder in VS Code and run the Run Extension launch configuration. It builds the extension and points it at the dev CLI.
License
Switchback is licensed under the Apache License 2.0. Using Switchback on your own is free; companies pay for a site on the hosted console at app.switchback.sh to manage it for their team (ADR 0020).
