Codex plugin

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.

The 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.

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

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.

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:

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

$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).

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.

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

Add the marketplace:

codex plugin marketplace add weave-os/weave

Open the plugin browser with /plugins and install Weave Telemetry
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 and 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):

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

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:

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 — lines generated by Codex
AI output percentage — portion of output from Codex
AI efficiency index — impact on productivity
AI tool costs — Codex spend per engineer (credit volume from telemetry, priced at the rate you configure)
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. 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

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.

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.

No AI skills scores after install

Confirm you chose Trust all and continue at the hook review prompt
Check [hooks.state] in ~/.codex/config.toml for a trusted_hash
Restart Codex after trusting
Until hooks are trusted, tokens, prompt counts, and tool calls still flow; prompt text and agent messages are missing

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.

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.

Codex — cost configuration and OpenAI-direct API usage
Claude Code plugin — the equivalent per-machine plugin for Claude Code
Cursor plugin — the equivalent per-machine plugin for Cursor
Copilot plugin — Copilot Chat OTEL export to Weave

Get started

Releases

Features

Weave Router

Integrations

Reports

Metrics

Analysis

Annotations

Export

Tutorials

Skeleton group medium 6

Codex plugin

What’s tracked

What it unlocks

Prerequisites

Setup

Hook trust prompt

Personal install command

Optional Codex marketplace plugin

Manual / telemetry-only configuration

Content categories

Fleet / MDM rollout

Uninstall

Metrics enabled

Cost tracking

Sync frequency

Troubleshooting

Data privacy

Get started

Releases

Features

Weave Router

Integrations

Reports

Metrics

Analysis

Annotations

Export

Tutorials

Skeleton group medium 6

​What’s tracked

​What it unlocks

​Prerequisites

​Setup

​Hook trust prompt

​Personal install command

​Optional Codex marketplace plugin

​Manual / telemetry-only configuration

​Content categories

​Fleet / MDM rollout

​Uninstall

​Metrics enabled

​Cost tracking

​Sync frequency

​Troubleshooting

​Data privacy

​Related integrations

What’s tracked

What it unlocks

Prerequisites

Setup

Hook trust prompt

Personal install command

Optional Codex marketplace plugin

Manual / telemetry-only configuration

Content categories

Fleet / MDM rollout

Uninstall

Metrics enabled

Cost tracking

Sync frequency

Troubleshooting

Data privacy

Related integrations