# Codex (CLI and app)

> How Tokenade covers OpenAI Codex: hooks in ~/.codex/hooks.json, hook trust via tokenade codex-trust, the local LLM proxy fallback and the Codex app.

Source: https://tokenade.net/en/docs/codex · Updated: 2026-10-07

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:

```text
  ✓ Codex passive hooks (Pre/PostToolUse/SessionStart/…) → ~/.codex/hooks.json
  ✓ 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:

```bash
tokenade codex-trust
```

```text
trusted 6 Codex hook(s) in ~/.codex/config.toml
```

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](https://tokenade.net/en/docs/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:

```toml
model_provider = "tokenade"

[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.

```bash
tokenade llm-proxy status                      # which agents point at a proxy, and what it adds
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

```bash
tokenade healthcheck
```

Look for:

```text
  OK  Codex hooks trusted — compaction active (6 hook(s))
```

Then run a Codex session with a noisy command and check your savings with `tokenade dashboard` (a local report in your browser). See [your first session](https://tokenade.net/en/docs/first-session).

## Remove

```bash
tokenade uninstall --dry-run   # preview
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](https://tokenade.net/en/docs/upgrade-uninstall).

## Related

- [The LLM proxy](https://tokenade.net/en/docs/llm-proxy)
- [Supported agents and compatibility](https://tokenade.net/en/docs/compatibility)
- [Wrap MCP servers](https://tokenade.net/en/docs/mcp-wrap)
- [Troubleshooting](https://tokenade.net/en/docs/troubleshooting)
- Article: [Reduce Codex token usage](https://tokenade.net/en/articles/reduce-codex-token-usage)
