> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect OpenAI Codex to Terma for Usage Tracking

> Wire Codex to Terma via a notify entry and hooks.json to capture turn-by-turn activity, file edits, and token spend from Codex sessions.

Codex operates turn-by-turn, and Terma captures each turn as it happens. A notify entry announces the turn to Terma, while `.codex/hooks.json` intercepts patch events to build a file manifest that Terma uses for commit attribution. Together, these two mechanisms give you per-turn visibility into what Codex touched, what it spent, and which commits it produced.

## How it works

Terma hooks into Codex at two levels:

* **Notify entry** — announces each turn to Terma as it starts, establishing the session context and associating it with the user running Codex
* **`apply_patch` hook** — fires whenever Codex writes a patch to the working tree; Terma intercepts the payload to build a file manifest that ties staged changes back to the session

When a session ends and a commit is made, Terma matches the file manifest from the `apply_patch` events against the commit diff to produce attribution data — connecting the commit to the exact Codex session that generated it.

## Setup

Run `terma setup` once per developer machine. It writes the notify entry and creates `.codex/hooks.json` automatically.

```bash theme={null}
terma setup
```

After setup, your `.codex/hooks.json` will contain:

```json .codex/hooks.json theme={null}
{
  "hooks": [
    {
      "event": "apply_patch",
      "command": "terma hook post-tool-use"
    }
  ]
}
```

### Trust the hooks in Codex

Codex requires you to explicitly grant hook permissions the first time hooks are registered on a machine. After `terma setup` completes, open Codex and run:

```text theme={null}
/hooks
```

This is a one-time step per machine. Once trusted, hooks fire automatically for all subsequent sessions.

<Note>
  If you skip the `/hooks` trust step, patch events will not be forwarded to Terma and file attribution will be incomplete. Run `terma doctor` to confirm hooks are active.
</Note>

## What's captured

| Signal              | Detail                                                             |
| ------------------- | ------------------------------------------------------------------ |
| Per-turn activity   | Each turn is recorded with its timestamp and context               |
| File edit manifests | Files touched by `apply_patch` events, used for commit attribution |
| Token counts        | Input and output tokens per session                                |
| Cost                | USD cost per session, attributed to the user who ran it            |
| Model               | Which Codex model handled the session                              |

## Verifying the connection

Check that Codex is wired correctly after setup:

```bash theme={null}
terma harness status
```

Codex should appear as connected. For a deeper end-to-end check:

```bash theme={null}
terma doctor
```

`terma doctor` verifies that the notify entry is firing, that `apply_patch` events are reaching Terma, and that attribution is resolving. Any misconfiguration is surfaced as a specific finding with a suggested fix.