Skip to main content
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.
After setup, your .codex/hooks.json will contain:
.codex/hooks.json

​
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:
This is a one-time step per machine. Once trusted, hooks fire automatically for all subsequent sessions.
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.

​
What’s captured

​
Verifying the connection

Check that Codex is wired correctly after setup:
Codex should appear as connected. For a deeper end-to-end check:
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.