Codex

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

Where it works

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

It is on as soon as OptiFlume is installed. You keep using Codex exactly as before, with your own ChatGPT account and plan: OptiFlume changes which model and reasoning effort each prompt runs on, nothing else.

What you see

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

OptiFlume: routine change → GPT-5.6 Terra · low

• In the panel: the model picker shows the model that ran. The one-line reason is in the hook entry under your prompt.
• In the terminal: the line appears under your prompt as a hook message.

A switch applies to that prompt only and never changes your saved default model. Picking a model yourself is fine too: the next prompt is still checked.

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, and the ~ is removed before Codex sends 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. Approve OptiFlume’s hooks once in Codex → Settings → Hooks. They show the one-line reason and run the Guardian and working memory; switching works without them; the Guardian does not. Using Codex only in the terminal? Codex says hooks need review: type /hooks in Codex, select OptiFlume’s hooks and trust them. One approval covers the panel and the terminal. Approvals you gave before an OptiFlume update are kept; a hook that an update adds needs one approval.
2. VS Code open during the install? Click Restart VS Code on the note that appears (it reloads the window). The Codex panel starts using OptiFlume after that.
3. Terminal: open a new terminal window or tab. One that was already open still runs the plain codex.
4. Sign in from the OptiFlume note in VS Code, or run optiflume login in a terminal.

Start-up, flags and scripts

• Starting codex: type it as before, with any of your usual options. A new session, codex resume and codex fork all run with OptiFlume. The first prompt of a session can take a moment longer while OptiFlume’s local models load.
• --model and -m: set the model 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: codex exec, codex review and any codex run from a script or with its output piped run with no switching and no one-line reason. OptiFlume’s hooks are in Codex’s own settings, not in the codex command, so once you have approved them, the Guardian and working memory run wherever Codex runs its hooks.
• Codex’s own commands, such as codex login, codex mcp and codex update, run unchanged. Codex keeps updating itself as before, and each new codex 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 and the Codex hooks 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 Codex panel uses OptiFlume;
• OptiFlume’s hooks, for the one-line reason, the Guardian and working memory, in a marked block of ~/.codex/config.toml;
• OptiFlume’s own codex command in ~/.optiflume/bin, first on your PATH, so codex in a new terminal runs with OptiFlume (optiflume terminal off turns this off; details);
• the OptiFlume Status extension, for the status bar.

Your AGENTS.md files, transcripts and sign-in stay as they are. Codex updates keep working as before. OptiFlume only uses models your ChatGPT account can run. Uninstalling removes everything above and restores your settings.

Safety and long sessions

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

• The Guardian, once you have approved OptiFlume’s hooks, checks the files Codex reads, also with a shell command such as cat or sed -n. Codex has no way for OptiFlume to ask you from a hook, so when the agent is about to use a sensitive file such as .env or a file with a secret (a key, a card number, a database address with its password, a sign-in token, a phone number), delete a file that existed before the session, or run a destructive command, the Guardian stops it and the agent asks you in chat. Reply allow to let it go ahead once; reply anything else and it stays stopped. Prefer no questions about secrets? Run optiflume guardian strict (kept out) or optiflume guardian allow (a warning). With Codex’s own approvals off (bypass or full access), unsure finds only warn, as in every tool; sure finds such as keys, deletes and destructive commands still stop. To always allow a file, run optiflume allow <file>. See When the agent stops and asks you.
• 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 Claude Code 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. Keep sends the prompt on your previous model. In the panel, Stop keeps your previous model and does not send the prompt; Codex shows “Stopped. Your prompt was not sent; edit it and send it again.” as a message that could not be sent. With codexin a terminal there is nowhere to show the notice, so switches are not held there; start a prompt with ~ to keep your model.

Privacy

OptiFlume decides on your Mac and never sends your prompts or code anywhere. Codex 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, the terminal command and the Codex hooks.
• On the free tier OptiFlume shows its pick and you switch yourself; Pro and the trial switch for you.
• More in Troubleshooting.