> ## Documentation Index > Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt > Use this file to discover all available pages before exploring further. # Codex CLI and Desktop > Beacon support details for Codex CLI and Codex Desktop endpoint telemetry ## Runtime overview Beacon supports Codex CLI runtime telemetry through local OTLP logs and one selective usage-bearing turn trace. Codex Desktop uses the same Codex OTLP configuration path through its app-server process, and Beacon records it as `codex_desktop` instead of merging it with `codex_cli`. A lightweight SessionStart hook records the local OS user for CLI token attribution. ## Prerequisites Before enabling Codex telemetry, make sure: * Codex CLI is installed and available as the `codex` executable for the user or managed endpoint. * Codex Desktop is installed if you want Desktop app-server telemetry. * 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 Beacon's localhost collector. Codex Desktop exports the same Codex semantic telemetry from `codex-app-server` when user-level `~/.codex/config.toml` enables OTLP. Beacon 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 CLI SessionStart hook writes a metadata-only `session.context` event; it never reads transcript content. Inventory is written by the scheduled inventory job, not by this hook. 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. ### Session-file recovery Beacon can also recover Codex CLI activity from Codex's local rollout files with an explicit command: ```bash theme={null} beacon endpoint codex sync ``` This reads committed files under `~/.codex/sessions` and appends mapped events to the local runtime log with `harness.collection_method=poll`. It is useful for historical sessions or sessions that ran before OTLP was configured. The sync path is not part of hook execution and cannot approve, deny, or delay tool calls. Use `beacon endpoint codex sync --print` to preview mapped events without writing the runtime log or advancing the cursor. Use `beacon endpoint codex status` to see which session files are present and how far Beacon has read each one. Codex rollout files can contain prompts, assistant responses, tool inputs, command output, and code. Sync is therefore explicit: Beacon does not read `~/.codex/sessions` during normal Codex hook execution, and it never reads `~/.codex/auth.json`. ### 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](/cli/token-usage#how-token-attribution-works) for the cross-runtime model. ### Rollout JSONL recovery behavior The Codex session sync reads complete JSONL lines and checkpoints by file path and line number. It maps session metadata, prompts, assistant messages, custom tool calls and outputs, task completion, and `token_usage_record` rows. Token input is normalized into Beacon's disjoint `gen_ai.usage` fields by subtracting cache reads and cache writes from Codex's inclusive input count. ## CI support Beacon can also capture Codex telemetry in CI with `beacon ci start` and `beacon ci finish`. In GitHub Actions, the Beacon action creates a temporary `CODEX_HOME` with Codex OTLP settings and exposes it as `steps..outputs.codex-home` for actions such as `openai/codex-action`. ```yaml theme={null} - name: Start Beacon telemetry id: beacon uses: asymptote-labs/agent-beacon@v0.0.95 with: mode: start harnesses: codex - uses: openai/codex-action@main with: openai-api-key: ${{ secrets.OPENAI_API_KEY }} codex-home: ${{ steps.beacon.outputs.codex-home }} prompt: "Review this pull request" - name: Finish Beacon telemetry if: always() uses: asymptote-labs/agent-beacon@v0.0.95 with: mode: finish ``` ## Discovery and status Beacon detects Codex CLI through the `codex` executable and `~/.codex/config.toml`. Codex Desktop shares the same user-level configuration file, so Desktop app-server events appear once the app emits OTLP to Beacon's local collector. Use `beacon endpoint discover` or `beacon endpoint status` to confirm that Codex configuration is present. ## 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: ```bash theme={null} beacon endpoint hooks install --harness codex ``` The hook installer writes the metadata-only session context hook to `~/.codex/hooks.json` or project `.codex/hooks.json`, depending on `--level`. A successful user-level install prints: ```text theme={null} Codex CLI endpoint hooks installed: /Users/you/.codex/hooks.json ``` ## Telemetry coverage | Area | Support | | --------------------------------- | -------------------------------------------------------------------------------------------------------- | | Prompt telemetry | Supported when emitted through Codex semantic logs | | Command, tool, and file telemetry | Supported when emitted through Codex semantic logs | | Token usage | Supported per turn through a selective OTLP trace (input, output, cache read, cache creation, reasoning) | | Cost attribution | Not available; Codex emits no cost signal | | Per-session attribution | Supported from `thread.id` on the turn span | | Per-user attribution | Supported in local reports by joining the OS-user SessionStart context | | Local JSONL and dashboard | Supported | | MDM deployment | Supported through the system-mode package or MDM-managed config | ## 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. ## Related Return to the runtime support overview. See how Beacon discovers and configures supported runtimes.