Troubleshooting

Start with one command. It checks every part of the install and says what to fix.

optiflume doctor

Each line is marked ✔ (fine), ! (a warning) or ✖ (broken), with the fix underneath. It exits with 0 when all is well, 1 with warnings and 2 when something is broken. optiflume status gives a shorter summary.

Some lines are about Cursor alone: the bridge (the OptiFlume Bridge extension), Cursor’s auto-switch check and the model list. While Cursor is closed, or on a Mac without it, warnings on those lines and not running in optiflume status are normal.

Nothing switches and no OptiFlume line appears

• Run optiflume status. Is a plan shown under License, and is the routing mode auto-switch? Paused stops OptiFlume in every tool, and suggest only stops Claude Code and Codex switching for now.
• Is the prompt small and the model already a good fit? Then there is nothing to do, and OptiFlume stays quiet on purpose. When it stays quiet lists the cases.
• Did you start the prompt with ~ or !? That keeps your model for that prompt.
• Does this project have its own settings? Look for .cursor/intent-router.json in the project folder.
• On the free tier, OptiFlume names a better model instead of switching: in Claude Code and Codex in the line under your prompt, and in Cursor as a tip, at most one every 15 minutes, and six a day.
• Then check your tool in the sections below.

The Claude Code or Codex panel doesn’t switch

• If VS Code was open during the install, click Restart VS Code on OptiFlume’s note, or reload the window: ⌘⇧P, then Reload Window. Conversations started before the install don’t switch until then.
• Run optiflume doctor. It checks each editor’s Claude Code and Codex connection and the Codex hook, and says what to fix.
• Run optiflume harness status. If it says off, run optiflume harness on and restart the editor.

claude or codex in the terminal doesn’t switch

• Open a new terminal window or tab. One that was open before the install still runs the plain claude and codex.
• Run optiflume terminal status. If the terminal is off, or you installed Claude Code or Codex after OptiFlume, run optiflume terminal on and open a new window.
• optiflume doctor checks the terminal commands too.

Codex doesn’t show the OptiFlume line

Approve OptiFlume’s hook once in Codex → Settings → Hooks. The hook only shows the one-line reason; switching works without it, so the model picker still shows the model that ran. In the Codex panel the reason is in the hook entry under your prompt; with codex in a terminal it appears as Hook · OptiFlume: ….

Turn it off for Claude Code or Codex

optiflume harness off     # Claude Code and Codex in your editors
optiflume terminal off    # claude and codex in the terminal

Turning it off puts your editor settings back exactly as they were. optiflume harness on and optiflume terminal on turn it back on. To keep your own model for a single prompt instead, start it with ~.

To remove OptiFlume altogether, optiflume uninstall removes the program and puts your editor settings back as they were; optiflume uninstall --purge also deletes your local data. See Uninstall.

Cursor: no note above the composer

Check the Bridge line in optiflume status. With Cursor open it should say running for and your project folder; if it says not running, reload the Cursor window: ⌘⇧P, then Reload Window.

Cursor: “Needs Accessibility permission”

System Settings → Privacy & Security → Accessibility → turn on Cursor. OptiFlume notices when you return to Cursor; if it doesn’t, restart Cursor. Until then OptiFlume suggests instead of switching. Claude Code and Codex don’t need this permission.

Cursor: “Automatic switching is paused on this Cursor version”

A Cursor update changed something OptiFlume relies on, so automatic switching is paused on that version until a fix ships. Suggestions keep working, and Claude Code and Codex are not affected. Update OptiFlume when a new version is available; Status lists paused versions and the fix.

Cursor: it switched and my prompt did not send

Your prompt is still in the composer: send it. Then run optiflume doctor; if the bridge or the Accessibility permission is missing it says so, and OptiFlume falls back to suggesting until it is fixed. If you had moved to another app or desktop when the switch happened, OptiFlume waits and sends the prompt when you come back to the Cursor window.

“Sign in” keeps coming back

• Run optiflume account. If it says “Not signed in”, run optiflume login and approve the Mac in your browser.
• If sign-in starts but never completes, the code may have expired. Run optiflume login again and approve within a few minutes.
• If this Mac was signed out from the console, or the account was deleted, sign in again.
• On a company network, see Networks and proxies.

I subscribed, but it still says free tier

Run optiflume refresh on that Mac (in Cursor, the Turn on Pro in Cursor button on the page after checkout does the same). Make sure the Mac is signed in with the same account you subscribed with: optiflume account shows the email.

“Turn on Pro in Cursor” did nothing

The button opens a cursor:// link, which needs Cursor and OptiFlume installed on this Mac. If Cursor opened but nothing happened, restart Cursor once and click again. Or run optiflume refresh in Terminal, which always works.

Local models stuck or failed

optiflume status shows the download state. If it failed, run optiflume models to retry. The download needs about 1 GB of free space and access to get.optiflume.ai (or huggingface.co as a fallback). OptiFlume works while the models download.

An update did not install

Run optiflume update. It prints why if a check fails, and falls back to the Terminal installer. Details of each attempt are in ~/.optiflume/logs/update.log. After an update, reload the window when Cursor or VS Code asks; Claude Code and Codex use the new version from your next conversation, or the next claude or codex you start.

Behind a corporate proxy

OptiFlume follows your macOS proxy settings or HTTPS_PROXY, and trusts certificates in your macOS Keychain, so networks that inspect HTTPS usually work as is. If optiflume.ai or get.optiflume.ai are blocked, ask IT to allow them. The full host list is in Networks and proxies.

“command not found: optiflume”

The installer adds optiflume to your PATH for new Terminal windows. Open a new window, or run it by its full path: ~/.optiflume/bin/optiflume.

Still stuck

optiflume doctor --bundle

Saves a support file to your Desktop, with no prompts, code or file paths in it. Email it to support@optiflume.ai with a line about what you expected and what happened.