Docs / Agents
Codex (CLI and app)
Updated
Codex (the command-line tool and the Codex desktop app) is covered by Tokenade through hooks, MCP wrapping and, when the hooks do not run, a local LLM proxy. The Codex-specific point: Codex refuses to run a hook until it is trusted. tokenade install writes that trust for you; if it is missing, Tokenade falls back to the proxy so you are still covered.
What install writes
All files live in ~/.codex/ (%USERPROFILE%\.codex\ on Windows), shared by the CLI and the app.
| File | What Tokenade adds |
|---|---|
~/.codex/hooks.json | Six lifecycle hooks, each tagged _tag: "tokenade-…" |
~/.codex/config.toml | Trust entries for those hooks ([hooks.state."…"] with a trusted_hash), wrapped [mcp_servers.<name>] entries, and, when needed, the LLM proxy provider |
~/.codex/AGENTS.md | A short Tokenade rules section |
The hooks
| Event | Role |
|---|---|
| SessionStart | Session context |
| UserPromptSubmit | Style note before each prompt |
| PreToolUse | Rewrites a shell command to tokenade wrap '<cmd>' |
| PostToolUse | Folds command output |
| PreCompact | Runs before Codex compacts the conversation |
| SubagentStart | Subagent context |
Hook trust
Codex records trust for each hook in ~/.codex/config.toml. A hook without a matching entry is inert: no rewrite, no compaction, no savings. Codex has no official command to trust a hook, so Tokenade writes the entry itself, only for the hooks it wrote. Your other hooks are never touched.
During install you see:
✓ trusted 6 Codex hook(s) (compaction active — no /hooks step needed)
tokenade install --dry-run names this write before doing it, because it edits the file holding your model, providers and MCP servers.
Re-apply trust
If you edited hooks.json, restored config.toml from a backup, or healthcheck says the hooks are not trusted, run:
If Tokenade cannot write the trust (install prints could not auto-trust Codex hooks), approve the hooks by hand: open Codex, run /hooks, and trust the Tokenade entries.
When the hooks don't run: the LLM proxy
Many Codex setups end up with untrusted hooks, in the CLI as in the app. Since 1.2.1, Tokenade checks whether every Codex hook is trusted. If not, tokenade install sets up the local LLM proxy for Codex, which carries what the hooks would have done:
- folded tool output in the history sent to the model,
- credentials scrubbed from tool results on the way to the provider,
- the style note,
- savings figures read from the provider's own usage,
- since 1.2.1, identical tool output sent only once (a later copy of the same unchanged file or command output becomes a short pointer to the first).
The proxy listens on 127.0.0.1 (port 8787 by default, the next free port if another agent already uses it) and is set to start at boot. In ~/.codex/config.toml it adds a provider:
[model_providers.tokenade]
name = "tokenade llm proxy"
base_url = "http://127.0.0.1:8787"
wire_api = "responses"
requires_openai_auth = true
If you sign in to Codex with your ChatGPT account (every Codex app user does), the proxy keeps that sign-in (requires_openai_auth = true) and reaches the ChatGPT service; with an API key it uses env_key = "OPENAI_API_KEY". Install checks the proxy answers before keeping the change, and puts your config back exactly as it was if it does not. If the hooks do run, nothing is done twice.
tokenade llm-proxy uninstall --agent codex # remove it for Codex
Once you remove it, later installs and upgrades leave it off. Re-add it with tokenade llm-proxy install --agent codex.
The Codex app
The Codex desktop app runs Codex on your machine with the same ~/.codex/config.toml, so it gets the same coverage through the LLM proxy, plus MCP optimisation for your own MCP servers. The app installs its own MCP server (browser and computer use) in your Codex settings; since 1.2.1 mcp-wrap leaves it as it is, because the app changes its path on every update. Savings from MCP servers in the app are credited to the app by name.
Verify
Look for:
Then run a Codex session with a noisy command and check tokenade gain. See your first session.
Remove
tokenade uninstall
Uninstall removes every Tokenade entry from ~/.codex/hooks.json, removes the trust entries it wrote to ~/.codex/config.toml, reverts the LLM proxy provider, restores your wrapped MCP servers, and removes the rules section. To remove only the proxy, use tokenade llm-proxy uninstall --agent codex. See Upgrade and uninstall.