Codex plugin

Trace Codex agentic sessions, LLM calls, and tool executions in W&B Weave.

Weave for Agents is in public preview. Features, APIs, and the Agents view UI may change before general availability.

The Weave Codex plugin automatically traces every Codex turn and sends the structured data to W&B Weave. 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.

By default, this plugin captures span content: your prompts, the model’s responses and reasoning, tool-call arguments, and tool results (which include shell commands, command output, and file contents). This data is sent to your W&B Weave 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 Weave under your security or compliance requirements, don’t install this plugin.

Prerequisites

• Node.js v20 or later.
• OpenAI Codex CLI with the hooks system (recent versions).
• A W&B account and API key set as a WANDB_API_KEY environment variable.
• A Weave project ([YOUR-TEAM]/[YOUR-PROJECT]) to receive traces.

Install the plugin

1. Install the package:

   npm install -g weave-codex
   
2. Set credentials and project:

   wandb login
   export WEAVE_PROJECT="YOUR-TEAM/YOUR-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:

   weave-codex install
   

   This merges a Stop hook into ~/.codex/hooks.json. The hook spawns a detached worker when each Codex turn completes, reads new rollout lines since a per-session cursor, reconstructs spans, and exports them to Weave.

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 Weave within approximately one second.

View Codex traces in Weave

After running at least one Codex session, open your project in the Weave UI:

1. Navigate to https://wandb.ai and select your project.
2. In the sidebar, select Agents for the multi-turn chat view and per-agent version grouping, or select Traces for the raw span tree.
3. Select a conversation to inspect the full turn hierarchy.

For more on the Agents view, see View agent activity.

The plugin emits one OTEL trace per Codex turn, following the GenAI semantic conventions:

Span	Emitted on	Key attributes
invoke_agent codex	Per turn (root span)	Agent name/version, gen_ai.conversation.id, model, summed token usage, user prompt and final answer (when content capture is on)
chat <model>	Per model call	gen_ai.usage.* (input, output, cached, reasoning tokens), finish reason, server.address, assistant output (when content capture is on)
execute_tool <name>	Per tool execution	gen_ai.tool.name, gen_ai.tool.call.id, arguments and result (when content capture is on), and MCP calls also carry mcp.server.name

Weave groups turns into a single conversation in the Agents view 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 are not yet captured.
• The Stop hook does not fire on aborted or errored turns, so those are not captured.

Configuration reference

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.

Setting	Environment variable	settings.json key	Default
W&B API key	WANDB_API_KEY	wandb_api_key	~/.netrc (through wandb login)
Weave project	WEAVE_PROJECT	weave_project	None (required, entity/project)
Base URL	WANDB_BASE_URL	wandb_base_url	https://trace.wandb.ai
Capture content	WEAVE_CODEX_CAPTURE_CONTENT	capture_content	true
Debug logging	WEAVE_CODEX_DEBUG	debug	Off (errors always log)

Credential resolution order

Credentials are resolved in this order:

1. Environment variables (WANDB_API_KEY, WEAVE_PROJECT).
2. ~/.weave-codex/settings.json.
3. ~/.netrc entry for the Weave host.

W&B Dedicated Cloud or self-hosted instances

Set WANDB_BASE_URL to your install host before running Codex:

export WANDB_BASE_URL=https://YOUR-INSTANCE.wandb.io

Check plugin status

You can use these CLI commands to check plugin status or troubleshoot issues:

weave-codex status

Each line shows ✓ (OK), ✗ (action needed), or - (not yet active but not an error). If turns aren’t appearing in Weave, check the collector log:

cat ~/.weave-codex/logs/collector.log

Troubleshooting

The collector log at ~/.weave-codex/logs/collector.log is the primary diagnostic source. Errors are always logged 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 is reading the wrong value.

Turns appear but input/output text is empty

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

Errors sending traces to Weave

If the plugin is active and spans are being generated but not appearing in Weave, check the collector log for an export error and match it against the table below.

Symptom	Most likely cause	Fix
401 or 403 from trace.wandb.ai	Invalid or scope-limited API key	Verify the key is current and the team owns the entity and project. Check the resolved credential source with weave-codex status.
404 from the agents endpoint	Wrong base URL	For Dedicated Cloud installs, set WANDB_BASE_URL to your install host.
Connection refused or DNS error	DNS, proxy, or firewall	Confirm the host can reach trace.wandb.ai (cloud) or your install host (Dedicated Cloud) on port 443.

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:

# ~/.codex/config.toml
notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"]

Uninstall

weave-codex uninstall

This removes only the weave-codex entries from ~/.codex/hooks.json.