Get started

Install and uninstall

Two ways to install, both signed and verified. Updates install themselves, and one command removes OptiFlume and restores your editor settings.

Before you start

  • macOS 11 (Big Sur) or later. Apple silicon and Intel Macs each have their own package; the download page and the Terminal command pick the right one.
  • Cursor, Claude Code or Codex; any one of them is enough. Claude Code and Codex work in VS Code (and in Cursor and Windsurf) and in the terminal. OptiFlume looks for Cursor in /Applications or ~/Applications.
  • About 1 GB of free disk space for the local models.

Option 1: the macOS installer

  1. Create your account (no card), then download from the install page. The file is a .pkg, signed with OptiFlume’s Apple Developer ID and notarized by Apple.
  2. Open it, click Continue, then Install. macOS asks for your password once: the installer unpacks OptiFlume in a shared folder and then moves it into your own user folder.
  3. Restart what was open during the install, so each tool starts using OptiFlume:
    • VS Code (or Windsurf): click Restart VS Code on the note that appears; it reloads the window. Conversations started before the install don’t switch until then.
    • Terminal: open a new window or tab. One that was already open still runs the plain claude and codex.
    • Cursor: quit it (⌘Q) and open it again.

Choose what to set up

Everything is on by default. To leave something out, click Customize on the Installation Type step. There are three boxes, all ticked:

  • OptiFlume for Cursor, which is required and always installed, whether or not you use Cursor;
  • Claude Code and Codex in your editors: the panels in VS Code, Cursor and Windsurf;
  • Claude Code and Codex in the terminal: the claude and codex commands.

You can change the two Claude Code and Codex choices later; see Turn Claude Code and Codex off or on.

To check the package before you open it:

pkgutil --check-signature ~/Downloads/OptiFlume-*.pkg
spctl -a -vv -t install ~/Downloads/OptiFlume-*.pkg
shasum -a 256 ~/Downloads/OptiFlume-*.pkg

The first should name Developer ID Installer: Raghav Joginipally (P9DMNRWU6G); the second should say accepted and Notarized Developer ID. Compare the fingerprint with the one on the install page.

Option 2: one Terminal command

The install page, once you have an account, also has a one-line Terminal install. It downloads the right package for your Mac, checks it, and installs for your user account. It needs no password. When it finishes, restart what was open, as in step 3 above.

What the installer does

  • Installs the program in ~/Library/Application Support/OptiFlume. It brings everything it needs, so there is nothing else to install.
  • For Claude Code and Codex in your editors: a setting in each editor so its Claude Code and Codex panels use OptiFlume, one Codex hook in a marked block of ~/.codex/config.toml, and the OptiFlume Status extension for the status bar.
  • For Claude Code and Codex in the terminal: OptiFlume’s own claude and codex commands in ~/.optiflume/bin.
  • For Cursor: its hooks, added to Cursor’s hook list, ~/.cursor/hooks.json (hooks you already had stay); the OptiFlume Bridge extension, which switches the model and shows OptiFlume’s notes; and a short rule, ~/.cursor/rules/optiflume.mdc, so Cursor’s assistant can explain those notes when you ask.
  • Puts the optiflume command on your PATH with one line in ~/.zshrc (or ~/.bash_profile, or a fish conf.d file), marked # OptiFlume CLI.
  • Creates your settings in ~/.optiflume/config/routing-config.json with automatic switching on. If you are reinstalling, your existing settings are kept.
  • Starts downloading the local models (about 1 GB) in the background. optiflume status shows progress.

The full list of files, and what each one holds, is in What is stored where.

After installing

Sign in, then take the one step your tool needs: nothing for Claude Code, approving OptiFlume’s hook once for Codex, and the optional Accessibility permission for Cursor. Your first switch walks through it. What you see with each switch is on each tool’s page: Cursor, Claude Code and Codex.

Turn Claude Code and Codex off or on

optiflume harness off     # Claude Code and Codex in your editors
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. optiflume harness status shows what is on.

More than one user on a Mac

OptiFlume installs for one macOS user at a time: the macOS installer sets it up for the person signed in at the screen. Anyone else who uses the Mac installs it from their own account; the Terminal command above is the quickest way, and needs no password. Each person signs in with their own OptiFlume account.

The macOS installer writes a log to /Library/Logs/OptiFlume-install.log. If it could not finish for your user, it says so there and leaves its files in /Library/Application Support/OptiFlume; run bash "/Library/Application Support/OptiFlume/install.sh" to complete the install.

Updates

OptiFlume checks for a newer version when Cursor or VS Code starts, when a Claude Code or Codex session starts, and every few hours. A new version is installed only after four checks pass: the release is signed by OptiFlume, the package comes from get.optiflume.ai and matches the signed fingerprint, macOS confirms it is signed with OptiFlume’s Developer ID and notarized by Apple, and the new version starts correctly before anything is changed. It installs into your user folder, with no password, and keeps your settings, history and plan. In Cursor and VS Code, a note asks you to reload the window to finish. Claude Code and Codex use the new version from the next conversation, or the next claude or codex you start. If any check fails, nothing is installed and an Update note appears instead.

optiflume update           # install the newest version now
optiflume update --check   # only say whether a newer version exists
optiflume version          # the installed version

If the in-place update cannot run, optiflume update falls back to the Terminal installer above. To be asked before updates install, set "auto_update": false; to stop checking altogether, set "update_check": false. Both live in ~/.optiflume/config/routing-config.json; see Settings reference.

Uninstall

optiflume uninstall           # remove the program, restore editor settings, keep your data
optiflume uninstall --purge   # also delete your local data in ~/.optiflume

One command removes the program and puts your editor settings back as they were; --purge also deletes your local data. In detail, optiflume uninstall removes everything it added for Claude Code and Codex, and OptiFlume’s Cursor hooks (yours stay in hooks.json), the OptiFlume Bridge extension, the rule, the optiflume command, the PATH line and the program folder in ~/Library/Application Support/OptiFlume. Without --purge, your settings, logs and license stay in ~/.optiflume so a reinstall picks up where you left off. Restart Cursor to finish. Claude Code and Codex conversations that were already running keep working until you close them.

If the macOS installer left shared files in /Library/Application Support/OptiFlume, the uninstaller prints the one command that removes them, which needs an administrator:

sudo rm -rf "/Library/Application Support/OptiFlume" && sudo pkgutil --forget ai.optiflume.engine

Uninstalling does not cancel a subscription or delete your account. To do that, see Account, Macs and billing.

Last updated 8 October 2026

Questions? support@optiflume.ai