Skip to main content

​
Runtime overview

Asymptote supports Codex CLI runtime telemetry through local OTLP logs and one selective usage-bearing turn trace. A lightweight SessionStart hook records the local OS user for token attribution and also triggers endpoint inventory heartbeats.

​
Prerequisites

Before enabling Codex CLI telemetry, make sure:
  • Codex CLI is installed and available as the codex executable for the user or managed endpoint.
  • Codex CLI 0.149.1 or newer is used for verified turn-trace token attribution.
  • beacon endpoint install has run so the local collector, endpoint config, and runtime log path exist.
  • The install includes the codex harness, either through the default harness list or an explicit --harness codex value.
  • Your team has reviewed content handling and destination access for prompt telemetry.

​
Collection path

Codex CLI exports local OpenTelemetry logs and traces to Asymptote’s localhost collector. Asymptote uses Codex semantic logs for session, prompt, approval, and tool-result events. For tokens it keeps only the completed session_task.turn span carrying thread.id, turn.id, model, and usage; hundreds of transport and internal spans remain suppressed. The SessionStart hook writes a metadata-only session.context event and refreshes inventory_state.jsonl; it never reads transcript content. Use --include-codex-spans during install or repair only when you need every raw Codex span for troubleshooting. It is not required for token attribution.

​
Token usage and cost

beacon endpoint install configures Codex’s log and trace exporters in ~/.codex/config.toml. Beacon normalizes the completed turn span into the same canonical gen_ai.usage fields used for Claude Code: uncached input_tokens, output_tokens, cache_read.input_tokens, cache_creation.input_tokens, and reasoning.output_tokens. Codex’s input count includes both cache reads and cache writes, so Beacon subtracts both before recording uncached input. The span directly supplies the model and session.id (from Codex thread.id). Beacon joins the matching SessionStart context event to attribute local reports by OS user. The runtime log therefore contains both the token event and its session identity context, and both forward through configured JSONL shippers. Codex still does not emit a cost signal on this span, so gen_ai.usage.cost_usd remains empty. Beacon never puts locally estimated pricing into that runtime-reported field. Legacy codex.turn.token_usage metrics in older logs remain reportable, but they have no session or user identity. New Beacon-managed configuration uses traces as the single live token source so spans and metrics cannot double-count the same turn. See How token attribution works for the cross-runtime model.

​
Rollout JSONL recovery

Beacon does not continuously scan ~/.codex/sessions or ingest rollout transcripts. Turn traces are structured, attributable, and avoid reading files that can contain prompts, tool output, and code. If historical backfill is added later, it should be an explicit recovery action over a hook-provided transcript path. A safe parser must read only session metadata, turn boundaries, and token_count records; compute positive field-by-field deltas from cumulative totals; handle repeated snapshots, forks, and resumes; and atomically checkpoint complete JSONL lines. It must never inspect auth.json.

​
CI support

Asymptote can also capture Codex telemetry in CI with beacon ci start and beacon ci finish. In GitHub Actions, the Asymptote action creates a temporary CODEX_HOME with Codex OTLP settings and exposes it as steps.<id>.outputs.codex-home for actions such as openai/codex-action.

​
Discovery and status

Asymptote detects Codex CLI through the codex executable and ~/.codex/config.toml. Use beacon endpoint discover or beacon endpoint status to confirm that Codex CLI is present and configured.

​
Install or configuration support

beacon endpoint install writes Codex OTLP exporter tables to ~/.codex/config.toml. beacon endpoint install --harness codex installs the required user-level session context and inventory hooks with the OTLP configuration. To refresh them independently, run:
The hook installer writes the metadata-only session context hook plus inventory heartbeats to ~/.codex/hooks.json or project .codex/hooks.json, depending on --level. A successful user-level install prints:

​
Telemetry coverage

​
Deployment notes

For MDM deployments, use the signed and notarized macOS .pkg so endpoint events land in /var/log/beacon-agent/runtime.jsonl. The package installs the endpoint agent under /opt/beacon, creates system endpoint configuration, and loads the local collector LaunchDaemon. If a system collector is running while the CLI is reading the default per-user log, beacon endpoint status and the local dashboard surface a runtime-log source warning so you can tell where OTLP events are being written.

Supported agent harnesses

Return to the runtime support overview.

Agent harness integration model

See how Asymptote discovers and configures supported runtimes.