> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex plugin

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

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

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.

<Warning>
  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 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.
</Warning>

## Prerequisites

* [Node.js](https://nodejs.org/) v20 or later.
* [OpenAI Codex CLI](https://github.com/openai/codex) with the hooks system.
* A W\&B account and [API key](https://wandb.ai/authorize) set as a `WANDB_API_KEY` environment variable.
* A Weave project (`[YOUR-TEAM]/[YOUR-PROJECT]`) to receive traces.

## Install the plugin

<Steps>
  <Step title="Install the package">
    ```bash lines theme={null}
    npm install -g weave-codex
    ```
  </Step>

  <Step title="Set credentials and project">
    ```bash lines theme={null}
    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](#credential-resolution-order) for full precedence rules.
  </Step>

  <Step title="Install the Stop hook">
    ```bash lines theme={null}
    weave-codex install
    ```

    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 Weave.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](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](/weave/guides/tracking/view-agent-activity).

The plugin emits one OTEL trace per Codex turn, following the [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/):

| Span                  | Emitted on           | Key attributes                                                                                                                             |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `invoke_agent codex`  | Per turn (root span) | Agent name or 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 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`.

| 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

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 Weave host.

### W\&B Dedicated Cloud or self-hosted instances

Set `WANDB_BASE_URL` to your install host before running Codex:

```bash lines theme={null}
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:

```bash lines theme={null}
weave-codex status
```

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

```bash lines theme={null}
cat ~/.weave-codex/logs/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 Weave

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

| 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:

```toml lines theme={null}
# ~/.codex/config.toml
notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"]
```

## Uninstall

```bash lines theme={null}
weave-codex uninstall
```

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