Skip to main content
Use this guide to capture Codex Developer decisions, commit Attribution, inference calls, and optional Edit observations on one developer machine.

​
Evidence captured

Developer decisions by agent harness defines Codex verdicts, explicitness, per-file expansion, and missing-signal limits.

​
Before you begin

Install the CLI and get a capture token with Configure local capture. This guide covers Codex CLI 0.153.4; Codex Desktop isn’t verified. <Codex home> means CODEX_HOME, or ~/.codex when it’s unset.

​
Install capture

  1. Connect the CLI to the Sediment endpoint:
  2. Install capture in the repository:
    Replace alice with your developer identifier. The installer adds hooks to <Codex home>/hooks.json, and creates a sediment Codex profile that adds telemetry to your existing model and settings.
  3. Load the environment, then start Codex with the telemetry profile:
  4. Run /hooks, and trust the Sediment hooks. Trust them again whenever an installation changes them.

​
Configure Developer decisions

The installer writes an [otel] table to <Codex home>/sediment.config.toml, with mode 0600. Codex sends header values literally, so the file holds your capture token itself. Keep it private. The table sets log_user_prompt=false, and the installer keeps the profile’s model, provider, and other settings. Decision telemetry can include patch text and other tool arguments, even without transcript capture. log_user_prompt=false doesn’t remove them. Agree on this with participants before you enable the profile. After you rotate the capture token, rerun the install command with the same flags to refresh the profile. If the profile already has an [otel] table that Sediment didn’t write, choose another profile name, or remove that table. Generic OTEL_EXPORTER_OTLP_* variables don’t configure Codex. Sediment records decisions for native apply_patch calls and for exec_command calls that start with an apply_patch heredoc. It ignores other shell commands.

​
Configure inference-call capture

If your deployment routes Codex through a gateway, your operator distributes the sediment provider, the gateway profile, and its credential, as described in Distribute gateway routing. You don’t need a gateway credential.
  1. Add native telemetry to the gateway profile. Pass your usual flags, not --no-env, which would also switch Cursor’s hooks to read the process environment:
  2. Start Codex with the gateway profile:
Codex carries its Session identifier in x-codex-turn-metadata. This route doesn’t carry a user identifier.

​
Configure Edit observations

Transcript capture sends applied patch text and the file’s content at Session end, so it’s off until you opt in. Rerun the installer with --transcripts added to your usual flags, and restart Codex:
The SessionEnd extractor needs a completed single-file patch. A multi-file patch still produces Developer decisions, but no Edit observation. Opt in to transcript capture covers the --no-env case.

​
Verify capture

Remote checks need a separate operator login.
  1. Check the configuration:
  2. Ask Codex to apply a single-file patch, end the Session, and commit the change.
  3. Read the commit’s Session note:
  4. After telemetry flushes, check that Session on the server:
    The check needs a Codex Developer decision in that Session and its entry in the note. With transcript capture, add --transcripts. For a gateway-routed Session, add --inference-calls.

​
Limits and troubleshooting

  • An interactive rejection can emit no Developer decision.
  • A decision without a file path, such as a rejection or a result in a later batch, produces one Developer decision with an empty path. A shell-tool decision without its result produces none.
  • Multi-file patches have no Edit observations. Codex doesn’t support Rejected edits, Retry linkages, or external line counts.
  • A patch event without a matching Session, tool-call identifier, timestamp, or confirmed result produces no Edit observation. The extractor logs why.
  • Transcript capture omits conversations, prompts, shell commands, and shell output. Inference-call capture includes model inputs and outputs.
  • To remove the telemetry profile, see Uninstall capture.
  • If doctor --fetch reports a notes-ref failure, follow Repair a notes ref.
Privacy boundaries and ceilings lists the fields that each capture path sends.