Claude Code

In the Claude Code panel in VS Code and in the claude command in your terminal, OptiFlume picks the model for each prompt and says why.

Where it works

• The Claude Code panel in VS Code, and in Cursor and Windsurf, which use the same extension.
• claude in any terminal.

It is on as soon as OptiFlume is installed, with nothing to set up. You keep using Claude Code exactly as before, with your own account and plan: OptiFlume changes which model each prompt runs on, nothing else.

What you see

For each prompt, OptiFlume picks the model and effort level it needs, switches to it, and tells you in one line, for example:

OptiFlume: routine change → Sonnet 5 · low

• In the panel: the line appears under your prompt and the model chip shows the new model.
• In the terminal: the line appears, the model changes for this session, and your prompt is sent on the new model by itself. To keep the current model for a prompt, start it with ~.

A switch never changes your saved default model. Picking a model yourself is fine too: the next prompt is still checked, and OptiFlume switches again when another model fits better.

Keep your own model for a prompt

Start the prompt with ~, with or without a space:

~ refactor this module carefully
~explain this error

That prompt stays on the model you have selected. In the panel the ~ is removed before it is sent; with claude in a terminal it stays in the prompt, and OptiFlume tells the model to ignore it. If your prompt itself starts with a path such as ~/project, add the marker in front: ~ ~/project/app.py is failing. In the panel, a leading ! works too.

Setup, the first time

1. VS Code open during the install? A note asks you to restart it. Click Restart VS Code (it reloads the window). A conversation started before the install switches once you start a new one or restart.
2. Terminal: open a new terminal window or tab. One that was already open still runs the plain claude.
3. Sign in from the OptiFlume note in VS Code, or run optiflume login in a terminal.

Claude Code needs no extra permissions. The OptiFlume item in VS Code’s status bar shows the model it last chose and your plan.

Start-up, flags and scripts

• Starting claude: type it as before, with any of your usual options, including --continue and --resume. The first prompt of a session can take a moment longer while OptiFlume’s local models load.
• --model and --effort: set the model and effort the session starts on. OptiFlume still checks every prompt from there and switches when another model fits better. To keep your model for a prompt, start it with ~.
• Headless and scripted runs: claude -p (print mode), any run with --output-format, and any claude run from a script or with its output piped run exactly as they would without OptiFlume: no switching, no Guardian, no working memory and no session watchdog. So does a session started with your own --settings file or with --bare.
• Claude Code’s own commands, such as claude update, claude doctor, claude mcp and claude config, run unchanged. Claude Code keeps updating itself as before, and each new claude you start uses the version that is installed.

Turn it off, or back on

optiflume harness off     # the panel (Claude Code and Codex)
optiflume terminal off    # claude and codex in the terminal
optiflume harness on
optiflume terminal on

Turning it off puts your editor settings back exactly as they were. The installer’s Customize step has the same two choices. To keep your own model for a single prompt instead, start it with ~.

To see OptiFlume’s pick without it switching, run optiflume auto-switch pause (suggest only): the line under your prompt names the better model, and the prompt goes ahead on yours, in the panel and in the terminal. optiflume auto-switch on switches again. optiflume auto-switch off stops switching and suggestions; the Guardian and working memory keep running. See Modes.

What OptiFlume changes, and what it leaves alone

• one setting in VS Code (and in Cursor and Windsurf) so the Claude Code panel uses OptiFlume;
• OptiFlume’s own claude command in ~/.optiflume/bin, first on your PATH, so claude in a new terminal runs with OptiFlume (optiflume terminal off turns this off; details);
• the OptiFlume Status extension, for the status bar.

Your CLAUDE.md files, memory, transcripts and sign-in stay as they are, and Claude Code’s own settings are only read, never written. Claude Code updates keep working as before. OptiFlume only uses models your Claude account can run. Uninstalling removes everything above and restores your settings.

Safety and long sessions

These work in the panel and with claude in the terminal:

• The Guardian asks you, with Claude Code’s own Allow / Deny dialog, before the agent reads a sensitive file such as .env or a file with a secret, runs a command that may print secrets or can’t be undone, or deletes a file that existed before the session. optiflume guardian strict keeps secrets out with no question; optiflume guardian allow only warns. If you switched Claude Code’s permission prompts off (--dangerously-skip-permissions), unsure finds don’t stop the agent; you get a warning such as “The agent is using the secrets in config/prod.yml for your task.” Sure finds, such as a key or a .env file, deletes of what existed before the session and destructive commands are still stopped, and the agent asks you in chat. (The same rule as in every tool; see Safety.) To always allow a file, run optiflume allow <file>.
• Working memory hands the session’s goal, decisions and failed approaches to the next model after a compaction or a switch, and a new conversation can pick up where you left off in Cursor or Codex in the same project. Pro and the trial.
• The session watchdog warns when a session goes in circles.
• The optional Stop/Keep notice: answer in the OptiFlume notification in VS Code, or with optiflume stop or optiflume keep in a terminal; in the panel, Stop keeps your previous model and does not send the prompt: OptiFlume ends the turn and puts your prompt on the clipboard, with “Stopped. Your prompt was not sent; it’s on your clipboard: paste it to edit and send it again.” With claude in a terminal, switches are not held (the switch is done a fraction of a second after you press Return); start a prompt with ~ to keep your model.

Privacy

OptiFlume decides on your Mac and never sends your prompts or code anywhere. Claude Code still sends your prompt to the model, as it always has. See What is stored where.

If a prompt does not switch

• Run optiflume doctor: it checks the panel in each editor and the terminal command, and says what to fix.
• On the free tier OptiFlume shows its pick and you switch yourself; Pro and the trial switch for you.
• More in Troubleshooting.