Switchback 3.1.0

Added

• A project's .mcp.json is read. Its mcpServers load below .switchback/config.json, which can adjust or turn off its servers. ${NAME} references read the environment. Servers Switchback can't run are skipped with a warning (ADR 0030)

Changed

• Project MCP servers start without switchback mcp trust. Set requireMcpTrust: true in your user config to keep the check, for .mcp.json and .switchback/ servers alike

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-3.1.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 3.0.0

Added

• Tab completes slash command arguments in the TUI. Models, agents, themes, effort levels, and each command's fixed words complete as you type. With several matches, Tab completes what they share, lists them, and goes round them. Inside a command, Tab no longer switches the model
• Commands open a list when run with no argument. /agent, /subagent, /subagent-model, /effort, /theme, and /review let you pick the value, and /tab opens the sessions dashboard
• Agents can tighten permissions. An agent's permissions (in its frontmatter or the agents config key) sets stricter category levels and adds ask and deny rules while it works. It never loosens yours (ADR 0029)

Changed

• /review with no argument opens a list instead of going back to review.mode. Use /review default for that
• Shift+Tab switches agents instead of permission modes. It goes build → plan → your own primary agents, and /agent <name> switches this session's agent while keeping the conversation instead of starting a new session. explore, review, and general only run as subagents (ADR 0029)
• Plan mode is the plan agent. It can read, search, run commands after asking, and browse, but not edit. Approving its plan switches back to the agent before it; Approve and auto-approve also sets the auto level
• Permission modes became three levels: ask, auto, and bypass. /permissions ask|auto|bypass switches them, and /mode is gone. permissions.level replaces permissions.defaultMode; the old value still loads, with plan starting the plan agent and acceptEdits becoming ask with a warning. --permission-mode takes the levels and the old names
• Protocol 3. session.setPermissions and permissions.changed carry the level, and session.setAgent and agent.changed are new. session.setMode and mode.changed are gone (protocol.md)

Fixed

• /model and the other pickers scroll past nine rows and wrap from the last row to the first and back
• More read-only commands run without asking: tree, sort, uniq, nl, tr, readlink, od, the checksum tools, test, and others, unless a flag writes a file (sort -o). The tools' descriptions point the model at read, glob, and grep first
• An input redirection from outside the workspace asks. cat < /etc/hosts counted as exploring the workspace

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-3.0.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.6.0

Added

• The model can read and change Switchback's settings. models lists each model with its tier, context, price, and role in the session, so the model can pick one for a subagent. config reads the configuration in effect with secrets hidden. set_config changes one setting in a config file and keeps its comments. set_roles changes the session's models and escalation ladder. Changes always ask, even in acceptEdits or auto-approve, and apply at once (ADR 0028)
• /autocompact [on|off] [--save] turns automatic compaction on or off for a session (session.setAutoCompact in the protocol)
• /ladder edits the escalation ladder. With no argument it opens an editor in the TUI. /escalate still works as an alias

Changed

• Compaction summarizes in parts and merges them. It leaves out tool output that a later call superseded, summarizes the history in parts, and merges the summaries. Each summary ends with a word-for-word record of your requests, the files changed and read, and the commands that failed. Both clients show its progress as the working status (ADR 0027)
• Models with less than 32k of context get fewer tools, which leaves them more room to answer. They keep the core tools plus webfetch, websearch, and docs
• Exploring takes fewer calls. read on a directory lists its entries, folders first. grep can show lines around each match (context) or list only the matching files (filesOnly)

Fixed

• /models refresh finds the claude CLI for subscription providers. The compiled binary failed with "native CLI binary not found"; it now uses the claude on your PATH
• The model no longer thinks config files reload on their own. Its instructions say to use set_config, or to ask you to type /reload after editing a file directly

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.6.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.5.0

Added

• Auto-approve mode asks a local judge model before allowing tool calls that normally need permission. Explicit ask rules and access outside the workspace still ask.
• Read-only shell commands can explore workspace files without a prompt when no rule requires one.
• Clickable TUI controls include answers, picker rows, and key hints. Esc sends queued messages while a turn is running.
• Model pickers can refresh endpoint lists and open setup; route labels and setup prompts explain their choices.
• switchback resume [id] reopens a session from the shell. With no id it opens the TUI on the session picker; with one, that session, or a clear error when the workspace has no session with that id. -r / --resume is the same command. Leaving the TUI prints Resume this session with: switchback resume <id> for a session with messages (#154)

Changed

• Config edits take effect on /reload. Running engines no longer watch config files. Edit them however you like, then type /reload in the TUI or VS Code (config.reload in the protocol) to apply them to the running engine; it says which settings changed, or which file didn't parse while the config in effect stays. Organization-enforced settings still win, and setup run from a client still applies what it writes right away

Fixed

• Turn review inspects every changed file. It includes shell commands, formatters, commits, and merged subagent work, while leaving pre-existing workspace changes out of the review.
• The resume command printed on exit works. It said switchback --resume <id>, which the CLI rejected as an unknown command

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.5.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.4.0

Added

• Asking for subagents gets you subagents. "Use 4 subagents to…" starts four, in parallel, each with its own brief and files; with no number the model uses as few as the work needs, and when a number looks wrong for the work it says so and you agree on one. Two subagents never edit the same file: each gets its own files or its own worktree
• Big fan-outs don't flood the parent's context. The subagents started in one step share 60,000 characters of report, and each is told its share, so 150 of them cost the parent about what two do. Subagents get a short note on reporting instead of the whole Switchback guide
• A built-in review agent. "Have a reviewer check it" sends a read-only reviewer over the change, which lists bugs and missed cases with file and line
• Subagents waiting for a slot show as waiting. Past subagents.maxConcurrent, a subagent's row says waiting for a free slot until it starts (subagent.queued in the protocol), and a running row shows the model it's on
• The mock provider fans out use 3 subagents to <goal>, so --mock demos orchestration without a model
• The prompt-cache hit rate is in the status bar. The TUI's status bar and VS Code's composer show how much of the session's input came from the provider's cache (cache 91%), with the latest turn's when it differs. call.stats events carry each call's usage. --mock simulates a prefix cache, so the rate shows there too
• /rename names a session. Up to 60 characters, in the TUI and VS Code (session.rename in the protocol). The title shows in /sessions, --resume, the VS Code view, the terminal's title (restored on exit), and ACP editors. /rename alone shows the current title
• Sessions are retitled at compaction. The summary that compaction already makes suggests a title, so it costs no extra model call; a title you set is never replaced
• /goal <objective> keeps working until it's done. The agent starts turn after turn until the model reports the goal done or blocked with the new goal tool, a goal.maxTurns or goal.maxMinutes limit is reached, three turns in a row fail, or you stop it with Esc or /goal stop. Each new turn is an appended reminder, so routing, budgets, and permission prompts apply as usual. Both clients show the goal above the prompt (ADR 0024)

Changed

• 16 subagents run at once by default, up from 4 (subagents.maxConcurrent), so a large fan-out finishes sooner. Local servers queue what they can't run at once
• Tool results and @ mentions fit the model's context window. A step's tool results share a quarter of the calling model's window (2,000 to 30,000 characters each), and a prompt's attachments half the session's, so a small local model isn't swamped by one read and pushed to escalate. Cut results keep their last lines, so a command's exit code survives. The cap is applied in one place for every tool, MCP tools included
• More of each request hits the cache. Claude requests add a cache breakpoint on the system prompt, so tools and system stay cached after compaction or past the 20-block lookback. OpenAI and Azure OpenAI requests send the session ID as prompt_cache_key, so a session's calls reach the same cache

Fixed

• Copying text works on Windows. The TUI no longer turns on mouse reporting there, so dragging selects text and Ctrl+C or Enter copies it in Windows Terminal, conhost, and VS Code's terminal. /mouse on brings back wheel scrolling and tab clicks, and /mouse off gives plain selection on macOS and Linux; the choice is remembered
• PowerShell commands don't flash a console window on Windows. Commands run outside the sandbox, hooks, git, ripgrep, the clipboard helpers, and the engine VS Code starts now run with their window hidden
• Status bar marks have their space back. The permission mode's mark (» accept edits, ║ plan, ! bypass) and the remote model's (▲, was ☁) are one cell wide in every terminal; the emoji-capable ones they replace (⚠, ⏸, ☁) were drawn two cells wide on Windows and covered the space after them
• Setup with one model doesn't ask which model does what. It used to offer an escalation ladder, reviewers, and a subagent model that a single model can't have

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.4.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.3.0

Added

• Starting from OpenCode reads its newer config format. providers with package and settings.baseURL, a model's modelID, agents' provider/model#variant, the permissions list, and mcp.servers come over like the older provider, permission, and mcp
• Sampling settings per model. temperature, topP, topK, and body (extra request fields such as vLLM's min_p or chat_template_kwargs) go with every request to that model, on every provider that takes them. Starting from OpenCode brings a model's body over as these, a #variant with its own body as a model of its own, and image input as vision
• Starting from OpenCode brings its agents and compaction settings. Agents keep their description, prompt, mode, step limit, and model; tools an agent denies are left out of its tool list. compaction's auto, keep.tokens, and buffer become enabled, keepRecent, and threshold
• Models on your own endpoints show up without running setup again. Each launch asks every OpenAI-compatible provider (vLLM, Ollama, LM Studio, a team's server) what it serves, as it already did for Claude Code and Codex sign-ins, and /models refresh asks right away and says what's new or gone. listModels: false turns this off for one provider
• /init runs setup inside Switchback. The TUI asks setup's questions in a panel above the prompt, the same ones switchback init asks, and the new config is in use as soon as it's saved. VS Code's /setup is /init too

Changed

• switchback init opens Switchback on setup, and so does a first run with no config, instead of asking in the terminal before the UI opens. With any answer given as a flag, or --yes, switchback init still asks in the terminal
• Web search runs without asking. permissions.websearch is a level of its own, default allow: only the query leaves the machine, to the search backend. Fetching a page still asks under permissions.web, and web: deny turns both off
• The docs tool tells the model that config changes apply live. It used to say they needed a restart, so the model told people to restart when they didn't have to

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.3.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.2.0

Added

• Claude Code and Codex models can use Switchback's tools. Each turn on one serves task, merge_worktree, escalate, docs, and skill to it over MCP on a loopback address, so asking it for a subagent starts a Switchback subagent in its own tab. Claude Code's own subagent tool is off while task is offered
• Tab switches to the next model. In the TUI, with no menu open, it makes the model after the current one, in config order, the current model for the session and says Switched to <model>.; pressed again it goes round them all
• The TUI says when a new version is out. At launch it checks GitHub's releases, at most once a day, and when yours is older says so in the chat with switchback update to update. updates.check: false turns it off
• Every model is told how to work in Switchback. The system prompt, and each Claude Code or Codex turn, explains subagents and their tabs, escalation, and reading the docs before changing settings

Changed

• Alt+↓ and Alt+↑ move between subagents and the session in the TUI, in place of Tab. Alt+↓ shows the next subagent; Alt+↑ comes back to the session
• Alt+↑ no longer escalates. /up still does, and Escalate now in VS Code

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.2.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.1.0

Added

• Tab shows a running subagent in place of the session. Tab moves through each subagent, then back to the session; the status bar says which one is in view, and /model there sets the subagent model
• More ways to move between tabs. Ctrl+Tab and Ctrl+Shift+Tab cycle tabs, a click on a tab switches to it, and Ctrl+W on an empty prompt closes the tab in front (with text typed it still deletes a word). Most terminals keep Ctrl+Tab for their own tabs, so it reaches Switchback only once you unbind it there
• The model can ask to escalate. A new escalate tool, which every session has, asks for the next step to run one model up the ladder, with a reason. The new model-escalation routing rule follows escalation.policy, privacy, and budgets like the other escalations, and the system prompt says when to use it
• Web search works without setup. When web.search isn't set, websearch uses Exa's hosted search, which needs no key; an optional apiKey raises its rate limits. Each search still asks first unless you allow websearch
• VS Code sends the workspace's problems. The problems chip counts errors and warnings across the whole workspace, with the active file's first, and attaches them as context
• The terminal UI uses kitty's keyboard protocol where the terminal supports it, so keys the terminal would otherwise merge, such as Ctrl+Tab and Shift+Enter, arrive as themselves

Changed

• switchback init asks less. It writes the config without showing it first, and allows the common test, build, and lint commands for every toolchain instead of asking which to allow. The config kind of setup.note is gone
• New Session in VS Code starts on a clear chat. The previous session is saved and /resume brings it back
• An exact command name wins over longer ones, so /model and Enter runs /model, not /models

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.1.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 2.0.0

Added

• switchback usage is a dashboard in a terminal. Pick today, the last 7 days, the month, the year, or all time, step back through earlier periods with ← and →, and see spend, savings, budget meters, how tokens split between local and remote models, a chart per day or month, and the breakdown by rule, agent, or model. --from/--to report any span of days, --period also takes year and all, and piped output and --json work as before. The usage.get protocol method takes a range and returns byDay
• Agents have modes, limits, and their own reasoning effort. An agent's mode says whether it runs as a session's agent, as a subagent, or both; effort and maxSteps set its reasoning effort and step limit; and agents limits which subagents it may call (an empty list removes its task tool). The new agents config key adds agents, changes built-ins field by field, and turns them off with disable: true. explore now runs at low effort
• The parent picks a subagent's model and effort per task. The task tool takes model and effort; an agent pinned to the local model refuses a remote one. subagents.effort sets the default for subagents whose agent sets none
• /effort changes reasoning effort for the current session. It overrides the agent's and model's effort for that session only, and /effort default goes back. --effort sets it at launch, it works the same in VS Code, and the protocol adds session.setEffort, effort on session.create, and the effort.changed event
• A Claude or ChatGPT plan brings all its models. Claude Code and Codex providers get every model their sign-in offers without listing them in config. Switchback asks the CLIs at launch (Codex through codex app-server, Claude Code through the Agent SDK) and caches the answer in subscription-models.json in the data folder, so newly released models show up without an update or re-running setup. Setup no longer asks which Claude Code or Codex model to add; --remote-model still picks one
• Setup asks for an API key for every provider that signs in with one (Anthropic, OpenAI, Azure OpenAI, DeepSeek, Gemini, Foundry, OpenCode, OpenRouter, and optionally OpenAI-compatible servers) when none is in the environment. The key is typed hidden, saved only in the user config, which setup makes readable by you alone, and never shown back. A project config never gets a key, and leaving the answer empty keeps reading the environment variable. setup.ask questions carry secret: true for this

Fixed

• A permission prompt shows only in the client that owns the session. A terminal chat's prompt no longer pops up in VS Code, and the reverse

Removed

• No more Intel Mac build. Releases no longer include a darwin-x64 binary or .vsix. On an Intel Mac, the installer and switchback self-update now say there is no build instead of failing to download one. Apple silicon under Rosetta still gets the arm64 build

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-2.0.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.

Switchback 1.6.0

Added

• Start from your OpenCode setup. On a first run, when an OpenCode config is found, switchback init first asks whether to start from it: its models (the main one stays current), MCP servers, and permissions come over and are shown before anything is written; API keys stay where OpenCode keeps them, and setup names the environment variables Switchback needs. --from opencode does it unattended (ADR 0022)

Fixed

• Config changes made outside a running engine take effect. The shared engine reloads ~/.switchback/config.json and the project's config files when they change, so switchback init in a terminal, switchback config edit, and editor saves apply without closing every client first. A file that doesn't parse is reported and the config in effect stays
• switchback doctor points out ~/.config/switchback and ~/.local/share/switchback left from before 1.1.0, which nothing reads
• Setting the current model during setup (--current) no longer leaves it on the escalation ladder too
• VS Code webview tests no longer fail depending on which test file loads the Markdown renderer first

Install

On macOS and Linux: curl -fsSL https://switchback.sh/install.sh | sh (add -s -- --vscode after sh for the VS Code extension too). On Windows, in PowerShell: irm https://switchback.sh/install.ps1 | iex. Or download the binary for your platform, verify it against SHA256SUMS, make it executable, and put it on your PATH as switchback. Then run switchback init.
Install the VS Code extension from the Marketplace or Open VSX (code --install-extension isaiah-harville.switchback), or from the switchback-vscode-1.6.0-<platform>.vsix here. Each platform's extension includes the engine, so no separate install is needed; the universal .vsix uses switchback from your PATH.

Binaries are not yet signed or notarized (#33). On macOS, clear the quarantine flag with xattr -d com.apple.quarantine switchback.