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

# Codex plugin

> Install Weave telemetry on each machine for per-developer Codex sessions

The Weave Codex plugin is a per-machine install that turns on Codex's native OTLP export and registers Weave hooks so agent replies can be captured.

Codex already emits tokens, cost, prompts, and tool calls over OTLP. The native exporter does **not** emit Codex's own prose (replies and reasoning summaries) or git context on prompt rows, so the installer also downloads `weave-telemetry.js` and registers it on `Stop`, `SubagentStop`, `SessionEnd`, `PreCompact`, and `UserPromptSubmit`.

<Note>
  The [Codex](/ai-tools/codex) page covers cost, OpenAI-direct API usage, and how Codex shows up in Weave metrics. This page is the install: the command, hook trust prompt, content categories, and fleet rollout.
</Note>

## What's tracked

* **Usage and cost** — tokens, models, and credit consumption from Codex's native OTLP export
* **Prompts** — prompt submissions and (optionally) prompt text for activity classification
* **Tool calls** — tool name, commands, and results
* **Agent messages** — Codex replies and reasoning summaries (hooks; requires hook trust and the `agent_messages` category)
* **Git context** — branch and repository remote on prompt rows (hooks)
* **Install health** — a per-machine ping so you can confirm each developer is reporting

## What it unlocks

* **Per-developer, per-session granularity** — attribute Codex activity to individual machines and ChatGPT login emails
* **[AI skills](/reports/ai-skills)** — conversation scoring reads agent message text from the hooks
* **Install health monitoring** — see which machines have the plugin installed and reporting
* **Easy rollout** — a single install command per machine, with hourly auto-update of `weave-telemetry.js`

## Prerequisites

* Codex CLI installed (the installer creates `~/.codex` if needed)
* **Node.js 18 or later** on each machine (the hooks run on Node)
* A Weave install token (created in the steps below)

## Setup

<Steps>
  <Step title="Create an install command in Weave">
    Go to **Data** → **Codex** → **Connect** (if Weave asks **How do you use Codex?**, pick your plan and click **Install Weave Plugin**). If you can't open that page, open **Personal plugin setup** on the **Data** page and choose **Codex**. The page is titled **Install Weave for Codex**. Admins click **Create install command** for a shared token; any signed-in member can click **Create my personal command** instead. Weave shows the full token once, plus macOS/Linux and Windows one-liners and downloadable scripts.
  </Step>

  <Step title="Run the install command on each machine">
    Copy the command from the modal. Weave fills in your token, ingest endpoint, environment, and org content-category flags. It looks like:

    **macOS / Linux:**

    ```bash theme={null}
    curl -fsSL 'https://app.workweave.ai/api/codex/plugin/install.sh' | bash -s -- \
      --token 'wcdxkey_...' --endpoint '...' --environment '...' \
      --privacy-mode false --prompt-bodies true --agent-messages true \
      --tool-io true --file-paths true --git-context true
    ```

    **Windows (PowerShell):**

    ```powershell theme={null}
    $env:WEAVE_TOKEN='wcdxkey_...'; $env:WEAVE_ENDPOINT='...'; $env:WEAVE_ENVIRONMENT='...';
    $env:WEAVE_PRIVACY_MODE='false'; $env:WEAVE_PROMPT_BODIES='true'; $env:WEAVE_AGENT_MESSAGES='true';
    $env:WEAVE_TOOL_IO='true'; $env:WEAVE_FILE_PATHS='true'; $env:WEAVE_GIT_CONTEXT='true';
    iwr -useb 'https://app.workweave.ai/api/codex/plugin/install.ps1' | iex
    ```

    The installer writes a managed block into `~/.codex/config.toml` (native OTLP export + hook registrations), downloads `weave-telemetry.js` to `~/.weave/codex-plugin/`, and writes `~/.weave/codex-plugin.json` (token, endpoint, content policy).
  </Step>

  <Step title="Restart Codex and trust the hooks">
    Restart Codex. On first start after install, Codex asks you to review the new hooks. Choose **Trust all and continue**. See [Hook trust prompt](#hook-trust-prompt).
  </Step>
</Steps>

The hook runtime **auto-updates hourly**: installed copies poll `/api/codex/plugin/version` and refresh `weave-telemetry.js`. A successful install prints `✓ Verified telemetry pipe — install_ping received by Weave.` on macOS/Linux, or `Verified telemetry pipe - install_ping received by Weave.` on Windows PowerShell. An MDM-deployed hook does **not** auto-update — poll that version endpoint and redeploy when the version or hash changes.

The full install sets `log_user_prompt = false` on Codex's native exporter so prompt text is not double-sent; prompts and git context come from the `UserPromptSubmit` hook instead.

### Hook trust prompt

The installer registers five Codex hooks (`Stop`, `SubagentStop`, `SessionEnd`, `PreCompact`, and `UserPromptSubmit`). Codex will not run a newly added hook until you have reviewed it once, so the first start after install shows a hook review prompt. Choose **Trust all and continue**.

This happens **once per machine**. Codex records approval as a `trusted_hash` under `[hooks.state]` in `config.toml` and derives that hash itself — the installer cannot pre-approve hooks.

Until the hooks are trusted, Codex still reports tokens, cost, prompt counts, and tool calls through native OTLP; prompt text, git context on prompt rows, and agent messages are missing, so [AI skills](/reports/ai-skills) conversation scores will not appear.

### Personal install command

Org-shared commands attribute usage by matching the ChatGPT/OpenAI login email to a Weave account. If those emails differ, click **Create my personal command** instead. The key is scoped to your Weave account, so telemetry attributes to you without email matching.

If some Codex logins still cannot be matched, admins see an **unlinked Codex users** banner listing unattributed usage from the last 30 days. Link each ChatGPT login email to the right Weave member (historical usage is not backfilled). Admins can also link OpenAI users from the [Members page](https://app.workweave.ai/members) via the OpenAI icon in the connections column.

### Optional Codex marketplace plugin

The hosted install command is the supported customer path. The Codex plugin is available for employees and local development while marketplace distribution remains private:

1. Add the marketplace:
   ```bash theme={null}
   codex plugin marketplace add weave-os/weave
   ```
2. Open the plugin browser with `/plugins` and install **Weave Telemetry**
3. Run the `install-weave-telemetry` skill to finish setup

### Manual / telemetry-only configuration

If a machine cannot run the install script, paste the TOML from the modal into `~/.codex/config.toml`. That enables native OTLP only: tokens, cost, prompt counts, and tool calls. The TOML keeps `log_user_prompt = false` and does **not** register hooks, so prompt text and agent messages are never captured and AI skills stay empty.

If Codex does not include ChatGPT account identity, add `"X-Weave-User-Email" = "user@company.com"` to the exporter `headers` in `config.toml` (alongside `"X-Weave-Token"`).

## Content categories

What Weave stores is governed by five categories, the same set the [Claude Code plugin](/ai-tools/claude-code-plugin) and [Cursor plugin](/ai-tools/cursor-plugin) use. The install command Weave generates already includes your org floor. Members can opt out further, but not back in past that floor.

| Category | Covers | Install flag |
| - | - | - |
| `prompt_bodies` | Text of the prompts you send to Codex | `--prompt-bodies` |
| `agent_messages` | Codex replies and reasoning summaries | `--agent-messages` |
| `tool_io` | Tool calls, shell commands, and results | `--tool-io` |
| `file_paths` | Workspace roots, cwd, and edited file paths | `--file-paths` |
| `git_context` | Branch name and repository remote | `--git-context` |

Pass `false` to deny a category. `--privacy-mode true` denies all five at once.

`agent_messages` governs the agent prose the hooks capture. With it denied, Weave still records that Codex responded (timestamps, model, message length) but stores none of the text, so sessions are not scored for AI skills.

## Fleet / MDM rollout

For a fleet rollout that skips the per-user hook review prompt, deploy the three artifacts from the modal's **MDM / fleet deployment (advanced)** section (hidden for personal keys, because a personal key would attribute every machine to one account):

1. **`requirements.toml`** — admin-enforced hooks. Deploy to `/etc/codex/requirements.toml` (macOS / Linux), `%ProgramData%\OpenAI\Codex\requirements.toml` (Windows), or as the macOS MDM preference `com.openai.codex:requirements_toml_base64` (base64-encode the file first). Hooks declared here are trusted by policy. The generated Unix command is `/usr/bin/env node /opt/weave/codex-hooks/weave-telemetry.js`; Node must be on the `PATH` Codex inherits (MDM/desktop launches often do not load a user version-manager), or replace the command with your fleet's absolute Node binary. On Windows the generated command uses `C:\Program Files\nodejs\node.exe` and `C:\ProgramData\Weave\codex-hooks\weave-telemetry.js`.
2. **`managed_config.toml`** — managed OTLP exporter defaults (token in `X-Weave-Token`). Deploy to `/etc/codex/managed_config.toml` (Unix), `~/.codex/managed_config.toml` (Windows), or `com.openai.codex:config_toml_base64`.
3. **`codex-plugin.json`** — hook runtime config at `~/.weave/codex-plugin.json` for each user, mode `600`, owned by that user. Substitute `weave_user_email` per user before deploying. Without it, that machine's agent messages cannot be linked to a Weave account.

Your MDM must also drop `weave-telemetry.js` (from `/api/codex/plugin/weave-telemetry.js`) into the managed directory named in `requirements.toml`. MDM-deployed hooks do not auto-update; poll `/api/codex/plugin/version` and redeploy when the version or hash changes.

## Uninstall

**macOS / Linux:**

```bash theme={null}
curl -fsSL 'https://app.workweave.ai/api/codex/plugin/install.sh' | bash -s -- --remove
```

**Windows (PowerShell):** switches cannot be passed through `iwr ... | iex`, so save the script and run `-Remove`:

```powershell theme={null}
iwr -useb 'https://app.workweave.ai/api/codex/plugin/install.ps1' -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1 -Remove
```

`--remove` / `-Remove` strips the Weave-managed block from `~/.codex/config.toml` and deletes `~/.weave/codex-plugin/` plus `~/.weave/codex-plugin.json`. User-authored `[features]` keys and hooks are left in place. Uninstall does not revoke the API key.

## Metrics enabled

Once reporting, the plugin feeds:

* **[AI code LOC](/metrics/ai-code-loc)** — lines generated by Codex
* **[AI output percentage](/metrics/ai-output-percentage)** — portion of output from Codex
* **[AI efficiency index](/metrics/ai-efficiency-index)** — impact on productivity
* **[AI tool costs](/metrics/ai-tool-costs)** — Codex spend per engineer (credit volume from telemetry, priced at the rate you configure)
* **[AI skills](/reports/ai-skills)** — per-conversation scoring of how well engineers work with Codex

## Cost tracking

Plugin telemetry supplies **credit/token volume**. Dollar cost uses the credit rate in **Settings → Financial → Tool subscription costs**. See [Codex](/ai-tools/codex#cost-tracking). For OpenAI API calls made outside Codex, connect an OpenAI admin API key on the Codex page.

## Sync frequency

Native OTLP and hook events are sent as Codex emits them during a session.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="terminal" title="Installer can't find Node">
    The hooks require Node.js 18+. Install it (`brew install node`, `nvm`, or your platform's package manager) and re-run the command. The installer searches `PATH` and common version-manager locations (mise, asdf, nvm, Volta, fnm, Homebrew); pass `NODE_BIN` to pin a binary.
  </Accordion>

  <Accordion icon="plug" title="Install finished but Weave shows nothing">
    Confirm the installer printed `✓ Verified telemetry pipe — install_ping received by Weave.` (macOS/Linux) or `Verified telemetry pipe - install_ping received by Weave.` (Windows). Then restart Codex and choose **Trust all and continue**. Tokens and cost can still flow before hooks are trusted; agent messages (and AI skills) wait on trust.
  </Accordion>

  <Accordion icon="shield" title="No AI skills scores after install">
    1. Confirm you chose **Trust all and continue** at the hook review prompt
    2. Check `[hooks.state]` in `~/.codex/config.toml` for a `trusted_hash`
    3. Restart Codex after trusting
    4. Until hooks are trusted, tokens, prompt counts, and tool calls still flow; prompt text and agent messages are missing
  </Accordion>

  <Accordion icon="user" title="Usage is not attributed to a Weave member">
    Use **Create my personal command**, or add `"X-Weave-User-Email"` to the OTLP headers, or link the ChatGPT login email from the unlinked-users banner / Members page.
  </Accordion>
</AccordionGroup>

## Data privacy

The plugin sends session metadata, token and credit usage, tool usage, and — unless the matching content category is denied — prompt text, agent messages, tool I/O, file paths, and git context. It does **not** read source files beyond what Codex passes through OTLP events and hook payloads.

## Related integrations

* [Codex](/ai-tools/codex) — cost configuration and OpenAI-direct API usage
* [Claude Code plugin](/ai-tools/claude-code-plugin) — the equivalent per-machine plugin for Claude Code
* [Cursor plugin](/ai-tools/cursor-plugin) — the equivalent per-machine plugin for Cursor
* [Copilot plugin](/ai-tools/copilot-plugin) — Copilot Chat OTEL export to Weave


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.