Modes and Stop/Keep

Let OptiFlume switch for you, have it suggest and leave the switch to you, or pause it. And, if you like, a few seconds to stop each switch.

The three modes

Mode	What happens when a better-suited model exists
Switch automatically (default)	OptiFlume switches the model before the prompt goes, says why in one line, and the prompt sends on the new model. Needs Pro or the trial. In Cursor it also needs Accessibility permission; without it, OptiFlume suggests instead.
Suggest only	In Cursor, the prompt pauses and a note names the recommended model and why. Switch the model and send the prompt again, or start it with `!` to keep yours. Nothing is sent until you choose.
Paused	Nothing: prompts go straight through with no notes. The session watchdog is off too. The Guardian keeps running, and on Pro the working-memory handoff continues.

Switching automatically and pausing apply to every tool. Suggest only is for Cursor for now. Claude Code and Codex do not have it yet: optiflume auto-switch off stops them switching altogether (prompts go straight through, with no note), and a project set to suggest only still switches in them. To turn OptiFlume off for Claude Code and Codex alone, run optiflume harness off (editors) or optiflume terminal off (terminal); see Claude Code and Codex.

Change the mode from Terminal:

optiflume auto-switch on       # switch automatically
optiflume auto-switch off      # suggest only
optiflume auto-switch pause    # paused
optiflume auto-switch status   # current state and recent switches

optiflume configure asks the same question interactively, along with your cost-or-quality preference. optiflume status shows the mode in force, and the Settings reference covers editing the file by hand. Setting the mode for all your Macs from console settings is coming soon.

When suggest-only is the better fit

You want to see every recommendation in Cursor before anything changes, for example in your first days with OptiFlume.
You work in a Cursor project where you always want to choose. Set suggest-only for that project alone with optiflume configure --project.

On the free tier, in every tool, OptiFlume behaves differently from both: it never pauses a prompt, and names a better-suited model instead. See Free tier and Pro.

The Stop/Keep notice

By default an automatic switch sends your prompt on the new model straight away. Turn on the Stop/Keep notice and each switch waits a few seconds while a notification shows the reason and two buttons:

Stop cancels the switch and puts your previous model back. Your prompt is not sent: send it however you like.
Keep <your model> puts your previous model back and sends the prompt on it straight away.

Either way, the next prompt goes through on the model you chose. If you click after the prompt has already gone, OptiFlume says so; start the next prompt with ~ in Claude Code and Codex, or ! in Cursor, to use your own model.

To turn it on, add these to ~/.optiflume/config/routing-config.json:

{
  "switch_notification": true,
  "switch_stop_window_ms": 2600
}

switch_stop_window_ms is how long the notice waits before sending, in milliseconds. The default is 2600 (about 2.6 seconds) and the shortest allowed is 600. Add the keys to the settings already in the file rather than replacing it. Turning the notice on from console settings is coming soon.

Stop or keep from Terminal

optiflume stop   # same as the Stop button
optiflume keep   # same as the Keep button

These act on a switch that is still waiting to send, in any window. With nothing pending they print “No switch is pending.” They are most useful with the Stop/Keep notice on, since that is when a switch waits.