Skip to main content
The Weave plugin for Codex automatically traces every Codex turn and sends the structured data to Agent Lens. Every model call, tool execution, and reasoning step is logged with no changes to your Codex workflow. Use these traces to debug sessions, audit tool usage, and monitor cost and latency across runs. The plugin reads Codex’s own rollout session files (~/.codex/sessions/**/rollout-*.jsonl) to reconstruct spans. It runs entirely off Codex’s critical path through a fire-and-forget Stop hook, so Codex never waits on the network.
This is a Weights & Biases Weave plugin. A CoreWeave Forge version isn’t available yet. Traces the plugin sends appear in Agent Lens, because Agent Lens and Weave share the same trace data.
By default, this plugin captures span content: your prompts, the model’s responses and reasoning, tool-call arguments, and tool results. Tool results include shell commands, command output, and file contents. This data is sent to your Agent Lens instance.PII scrubbing and sensitive-data redaction aren’t implemented. To send structure, token usage, model, and timing only (with no prompts, code, or output), set WEAVE_CODEX_CAPTURE_CONTENT=0. If you can’t send this data to Agent Lens under your security or compliance requirements, don’t install this plugin.

​
Prerequisites

  • Node.js v20 or later.
  • OpenAI Codex CLI with the hooks system.
  • A CoreWeave Forge account and API key set as a WANDB_API_KEY environment variable.
  • An Agent Lens project ([YOUR-TEAM]/[YOUR-PROJECT]) to receive traces.

​
Install the plugin

1

Install the package

2

Set credentials and project

You can also set WANDB_API_KEY directly as an environment variable instead of using wandb login. See Credential resolution order for full precedence rules.
3

Install the Stop hook

This merges a Stop hook into ~/.codex/hooks.json. When each Codex turn completes, the hook spawns a detached worker that reads new rollout lines since a per-session cursor, reconstructs spans, and exports them to Agent Lens.
4

Approve the hook in Codex

Codex marks newly added hooks as untrusted and won’t run them until you approve. On your next codex launch, approve the weave-codex hook when prompted.Alternatively, set bypass_hook_trust = true in ~/.codex/config.toml to skip the prompt.Run weave-codex status to confirm everything is configured correctly.
Now you can run Codex normally, and each completed turn appears in Agent Lens within approximately one second.

​
View Codex traces in Agent Lens

After running at least one Codex session, open your project in the Agent Lens UI:
  1. Navigate to CoreWeave Forge, select Agent Lens from the product menu, and then select your project in the project selector at the top of the side menu.
  2. In the side menu, select Conversations.
  3. Select a conversation to inspect the full turn hierarchy.
For more on the Conversations tab, see View agent activity. The plugin emits one OTEL trace per Codex turn, following the GenAI semantic conventions: Agent Lens groups turns into a single conversation in the Conversations tab using gen_ai.conversation.id, which is set to the Codex session ID on every span. Span timestamps are backdated from rollout file timestamps, so durations reflect actual execution time. Traces also render in any OTEL-compatible backend, since all attributes follow the GenAI semantic conventions.

​
Known limitations

  • The codex (interactive TUI) and codex exec commands are supported. The codex mcp and app-server commands are not covered because they fire no hooks.
  • A spawned subagent appears as its spawn_agent tool call only. Its own model calls and tool executions aren’t captured.
  • The Stop hook doesn’t fire on aborted or errored turns, so those aren’t captured.

​
Configuration reference

This section lists the settings you can use to customize plugin behavior. Configuration and runtime files are stored in ~/.weave-codex/, including settings.json, the hook shim, per-session cursors, and the log file at logs/collector.log.

​
Credential resolution order

The plugin resolves credentials in this order:
  1. Environment variables (WANDB_API_KEY, WEAVE_PROJECT).
  2. ~/.weave-codex/settings.json.
  3. ~/.netrc entry for the Agent Lens host.

​
Check plugin status

You can use these CLI commands to check plugin status or troubleshoot issues:
Each line shows ✓ (OK), ✗ (action needed), or - (not yet active but not an error). If turns don’t appear in Agent Lens, check the collector log:

​
Troubleshooting

The following sections describe common issues and how to resolve them. The collector log at ~/.weave-codex/logs/collector.log is the primary diagnostic source. The plugin always logs errors regardless of the debug setting.

​
No traces appear after running Codex

  1. Run weave-codex status. Confirm all checks pass.
  2. Confirm the hook is trusted. If you skipped the approval prompt on first launch, run codex again and approve when prompted, or set bypass_hook_trust = true in ~/.codex/config.toml.
  3. Confirm WEAVE_PROJECT is set to a valid entity/project slug. weave-codex status prints the resolved project.
  4. Confirm the auth source. weave-codex status prints the resolved credential source. If it shows WANDB_API_KEY env but you set the key elsewhere, the plugin reads the wrong value.

​
Turns appear but input/output text is empty

Content capture may be disabled. Check that WEAVE_CODEX_CAPTURE_CONTENT isn’t set to 0 and that capture_content isn’t set to false in ~/.weave-codex/settings.json.

​
Errors sending traces to Agent Lens

If the plugin is active and generates spans that don’t appear in Agent Lens, check the collector log for an export error and match it against this table.

​
Hook-locked environments

If allow_managed_hooks_only is set in your Codex config, you can’t add custom hooks directly. Use Codex’s notify program as a fallback trigger instead:

​
Uninstall

This removes only the weave-codex entries from ~/.codex/hooks.json.
Last modified on September 27, 2026