codex shell command, the desktop app, and the IDE extension share Codex’s user-level configuration, hooks, and trust settings in ~/.codex, so one setup covers all of them.
Set up
Runterma setup once on your machine and choose Codex TUI & Desktop when asked:
terma setup for every option.
Setup approves terma’s own Codex hooks for you, so there is no separate review step in Codex. If you change terma’s hook entries by hand, Codex asks you to trust them again; run terma setup to restore them.
Sessions are collected only where your team’s collection policy allows: in a repository the policy lists, or everywhere if the policy collects every session. An org admin sets this on Team settings → Data collection.
How it works
Terma configures Codex at the user level. Nothing is written into your repositories.Telemetry: Codex’s OpenTelemetry export
terma setup points the [otel] exporter in ~/.codex/config.toml at a relay terma runs on your machine, on 127.0.0.1. The relay forwards only sessions that a hook claimed in a repository your team collects, with your team’s key, and drops everything else on your machine. Your team’s key never appears in Codex’s configuration.
This channel carries model calls with their token counts and cost, tool calls, and — when your team’s policy collects them — prompts, responses, and tool content. Setup also routes Codex’s notify setting through terma to capture turns, and keeps any notifier you already had.
Terma also reads Codex’s local session log for activity Codex’s telemetry does not report, such as hosted actions and compactions.
Attribution: machine-wide hooks
terma setup adds these entries to ~/.codex/hooks.json:
Each command is guarded, so on a machine without terma it does nothing. Hooks never make a network request: they append to a local queue that terma delivers in the background. Set
TERMA_HOOKS=0 to turn them off for one shell or process.
When your team’s policy stamps commits, the first session in a collected repository also installs commit hooks in that repository’s .git/hooks. See Commit attribution.
What’s captured
Some of this capture reads Codex’s private local session format, which can change between Codex releases, and Codex exempts some hosted and specialized tools from hooks. New Codex item types may require a terma update; run
terma update.Controlling what is sent
Your team’s collection policy decides what leaves your machine. An org admin sets it on Team settings → Data collection. The local relay removes what the policy does not collect before anything leaves. See Privacy and data.Verify
doctor checks your sign-in, whether your team collects the current repository, the hooks and whether Codex trusts them, Codex’s export, and delivery to Terma. It also warns when a Codex process started before setup is still exporting where it did; restart it. Every failure names its fix, usually terma setup.