The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
---
title: "Codex CLI and Desktop"
description: "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, and Beacon records its sessions as `codex_desktop` and keeps them apart from `codex_cli`. A lightweight SessionStart hook records the local OS user for CLI token attribution, and a Stop hook records each turn's final assistant reply, which Codex's OTLP export does not carry.
## 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 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 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. The CLI Stop hook writes the turn's final reply from the payload's `last_assistant_message` as an `agent.message` event, and nothing for a turn that ended without one. Neither hook reads the transcript. 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.
### Codex CLI or Desktop
Codex CLI 0.158 and newer run on the same app-server as the desktop app, so both report the service name `codex-app-server`, and that name alone does not say which one a session ran in. Beacon goes by the `originator` Codex reports instead: `Codex_Desktop` is recorded as `codex_desktop`, and `codex-tui` (the terminal), `codex_exec` (`codex exec`), `codex_vscode` (the IDE extension) and any other value as `codex_cli`. Codex's log events and its legacy token metric carry the originator. The usage span does not, so it takes the surface its conversation's logs named; if it reaches the collector before those logs, Beacon waits up to ten seconds for them before writing it, and a usage span whose logs never arrive is recorded as `codex_cli`. `beacon endpoint codex sync` names each rollout the same way, from the originator in its `session_meta` line (`Codex Desktop` for the desktop app). Token reports still drop usage a Desktop session reports twice, through a turn span and a legacy metric or through live capture and `codex sync`. Events already in the log keep the name they were written with, so CLI 0.158+ sessions recorded before Beacon v1.3.48 still show as `codex_desktop`, and Desktop rollouts `codex sync` read before it went by the originator still show as `codex_cli`.
### Session-file recovery
Beacon can also recover Codex CLI activity from Codex's local rollout files with an explicit command:
```bash
beacon endpoint codex sync
```
This reads committed files under `$CODEX_HOME/sessions` when `CODEX_HOME` is nonempty, otherwise `~/.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`.
Install, hook install, discovery, inventory, session status, sync, handoff, and `beacon mcp connect` honor Codex's literal `CODEX_HOME` directory: it must exist, and relative paths resolve from the current working directory. Unlike shell syntax, `~` and environment-variable references in the value are not expanded. Project-level `.codex` files are not affected. Pass `--codex-dir <path>` to select a session store explicitly.
The scheduled inventory job starts without your shell's environment, so a per-user `beacon endpoint install` or `repair` writes the `CODEX_HOME` it resolved into the job's launchd or systemd definition. If you change `CODEX_HOME` later, run `beacon endpoint repair` from a shell that has the new value. System-mode installs do not record it.
### Token usage and cost
`beacon endpoint install` configures Codex's log and trace exporters in `$CODEX_HOME/config.toml` (default `~/.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.<id>.outputs.codex-home` for actions such as `openai/codex-action`.
```yaml
- name: Start Beacon telemetry
id: beacon
uses: asymptote-labs/[email protected]
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/[email protected]
with:
mode: finish
```
## Discovery and status
Beacon detects Codex CLI through the `codex` executable and `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`). Codex Desktop shares the same user-level configuration file, so Desktop 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_HOME/config.toml` (default `~/.codex/config.toml`).
`beacon endpoint install --harness codex` installs the required user-level
session context and assistant response hooks with the OTLP configuration. To refresh
them independently, run:
```bash
beacon endpoint hooks install --harness codex
```
The hook installer writes the session context (`SessionStart`) and assistant response (`Stop`) hooks to `$CODEX_HOME/hooks.json` (default `~/.codex/hooks.json`) or project `.codex/hooks.json`, depending on `--level`. A successful user-level install prints:
```text
Codex CLI endpoint hooks installed: /Users/you/.codex/hooks.json
```
Codex runs a non-managed hook only after you review and trust its exact definition. Run `/hooks` in Codex to trust the Beacon hooks after installing or upgrading; until then Codex skips them, and the assistant reply reaches the log only through `beacon endpoint codex sync`.
## Telemetry coverage
| Area | Support |
|------|---------|
| Prompt telemetry | Supported when emitted through Codex semantic logs |
| Agent responses | Supported live through the Stop hook (`last_assistant_message`, recorded as `agent.message`); Codex's OTLP export carries no response text. `beacon endpoint codex sync` also recovers every committed assistant message |
| Turn identity | Supported. Codex's `turn_id` from hooks, `turn.id` from OTLP, and the turn bracket in `beacon endpoint codex sync` are promoted to `prompt.id` |
| Command, tool, and file telemetry | Supported live from `codex.tool_result`. A shell call is `command.executed` with `command.output` and the exit code from the header Codex writes above the output (`Process exited with code N`, or `Exit code: N`); an MCP server's tool is `mcp.tool_invoked` named `mcp__<server>__<tool>`, with its reply as `gen_ai.tool.call.result`; any other tool is `tool.completed` or `tool.failed`, with its output as `gen_ai.tool.call.result`. `beacon endpoint codex sync` records the same call the same way, as a second event with `harness.collection_method=poll` |
| 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
<Columns cols={2}>
<Card title="Supported agent harnesses" icon="list-check" href="/runtimes">
Return to the runtime support overview.
</Card>
<Card title="Agent harness integration model" icon="plug" href="/runtimes/integration-model">
See how Beacon discovers and configures supported runtimes.
</Card>
</Columns>