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

> Connect Codex to track AI-assisted development

Connect Codex to track AI-assisted code generation metrics across your team.

## What's tracked

* **Code generation** — AI-generated code from Codex sessions
* **Usage metrics** — How often Codex is used across your team
* **Cost tracking** — Codex spend per engineer
* **Agent messages** — Codex's own replies and reasoning summaries, which power
  [AI skills](/reports/ai-skills) conversation scoring

## Prerequisites

* Active Codex account
* Admin access to your Weave organization
* Node.js 18 or later on each developer's machine (the install command registers a small hook that
  captures agent messages)

## Setup

### Quick install (recommended)

<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** on the **Weave Plugin** card. Then click **Create install command** to
    create a one-time install command.
  </Step>

  <Step title="Run the install command">
    Copy the one-liner from the modal and run it in your terminal:

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

    On Windows (PowerShell):

    ```powershell theme={null}
    $env:WEAVE_TOKEN='wcdxkey_...'; iwr -useb 'https://app.workweave.ai/api/codex/plugin/install.ps1' | iex
    ```

    The installer writes a managed block into `~/.codex/config.toml` that turns on Codex's native
    telemetry export and registers the Weave hooks, and downloads the hook itself to
    `~/.weave/codex-plugin/`.
  </Step>

  <Step title="Restart Codex">
    Restart Codex for the configuration to take effect. Activity should appear in Weave within a few minutes.
  </Step>

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

### Hook trust prompt

The install command registers five Codex hooks (`Stop`, `SubagentStop`, `SessionEnd`, `PreCompact`,
and `UserPromptSubmit`) so Weave can capture agent messages and prompt text. Codex will not run a newly added hook until you
have reviewed it once, so the first time you start Codex after installing you will see a hook review
prompt listing the Weave hook command. Choose **Trust all and continue**.

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

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

### Personal install command (recommended when emails differ)

Org-shared install commands attribute Codex usage by matching the ChatGPT/OpenAI login email to a Weave account. If those emails differ (personal Gmail login, plus-aliases, etc.), usage may not attribute.

On **Data** → **Codex** → **Connect**, use **Create my personal command** instead. If you can't open that page, open **Personal plugin setup** on the **Data** page and choose **Codex**. The generated key is scoped to your Weave account, so your telemetry attributes to you without relying on email matching.

If some Codex logins still cannot be matched, admins see an **unlinked Codex users** banner on the Codex connect page listing unattributed usage from the last 30 days. Link each ChatGPT login email to the right Weave member to attribute usage going forward (historical usage is not backfilled). Admins can also link OpenAI users from the [Members page](https://app.workweave.ai/members) — use the OpenAI icon in each member's connections column instead of linking one at a time on the Codex configure page.

### Optional Codex plugin

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

1. Add the marketplace (employee/private-repo access today; official Codex Plugin Directory coming soon):
   ```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 complete setup

### Manual configuration

If you prefer to configure manually:

<Steps>
  <Step title="Create an install token in Weave">
    Go to **Data** → **Codex** → **Connect** (if Weave asks **How do you use Codex?**, pick your plan and
    click **Install Weave Plugin**), then click **Create install command** to create an install token.
    Save the TOML configuration. You will only see the
    full token once.
  </Step>

  <Step title="Install the configuration file">
    Download or copy the TOML configuration and add it to `~/.codex/config.toml`
    on each developer's machine.
  </Step>

  <Step title="Verify connection">
    Use Codex and check that activity appears in Weave after a few minutes.
  </Step>
</Steps>

<Note>
  If Codex does not include your ChatGPT account identity, add
  `"X-Weave-User-Email" = "user@company.com"` to the `headers` in `config.toml`
  for attribution to work.
</Note>

<Note>
  Manual configuration covers the native telemetry export only, and the generated TOML sets
  `log_user_prompt = false`. Prompt text and agent messages are captured by the Weave hooks, which
  the install command registers. Run it if you want prompt text and [AI
  skills](/reports/ai-skills) conversation scores.
</Note>

## Metrics enabled

Once connected, you can track:

* **[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
* **[AI code review](/metrics/ai-reviewer-comments)** — Automated Codex review activity on GitHub PRs, alongside other AI reviewers
* **[AI skills](/reports/ai-skills)** — Per-conversation scoring of how well engineers work with Codex

## Cost tracking

Codex cost follows the Codex plan you set in **Settings** → **Financial** → **Tool subscription costs**. Per-seat plans (such as Codex Business) are charged per seat. On credit plans, Codex usage consumes credits, and Weave converts credits to dollars per engineer:

* **Credits** are derived from token telemetry (input/cached/output tokens × published per-model rates) for each engineer and day that telemetry covers. For engineer-days without telemetry, Weave uses credits from the Codex Analytics API where available (your real consumption).
* **Dollars**: with usage-based credits, dollars are credits × your \$/credit rate. With a shared credit pool or per-user credits, Weave adds the plan's fixed monthly cost and prices only credits above the included allocation, at your overage rate. Because these rates are ones you configure, set them to match your actual ChatGPT/Codex contract for accurate figures.

This makes Codex cost a **hybrid** — real (or token-estimated) usage volume priced at the rate you provide, rather than a number pulled from an invoice.

### OpenAI direct API usage

If your team also calls the OpenAI API directly (outside Codex), add an **OpenAI admin API key** (`sk-admin-…`, with the `api.usage.read` and `api.management.read` scopes) under **Data** → **OpenAI Admin Key** → **Add API key**. Weave reads usage from the OpenAI Admin Usage API and computes cost as **tokens × published list price** per model.

<Note>
  OpenAI-direct cost is **estimated** — it uses public list prices and does not reflect enterprise discounts, committed-use pricing, or credits. Treat it as directional.
</Note>

## Data privacy

Weave syncs usage metadata and conversation content from Codex:

* Code generation statistics
* Token usage and costs per model
* Tool usage decisions
* User prompt text (used for activity classification; system messages are excluded)
* Agent messages — Codex's replies and reasoning summaries (used for conversation scoring)

**We never access:**

* Source code content or diffs
* File paths or project structure, unless the `file_paths` category is enabled

### Telemetry content categories

What Weave stores is governed by five content categories, the same set the [Claude Code
plugin](/tutorials/weave-plugin-installation) and [Cursor plugin](/tutorials/weave-plugin-installation) use. Each one can
be turned off at install time, and admins can set an organization-wide floor for all of them under
**Telemetry content retention** in organization settings; members can opt out further for
themselves, but not back in past the org floor.

| Category | Covers | Install flag |
| - | - | - |
| `prompt_bodies` | Text of the prompts you send to Codex | `--prompt-bodies` |
| `agent_messages` | Codex's 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` |

All five default to enabled. Pass `false` to any flag to deny that category, for example:

```bash theme={null}
curl -fsSL 'https://app.workweave.ai/api/codex/plugin/install.sh' | bash -s -- \
  --token 'wcdxkey_...' --agent-messages false
```

`agent_messages` is the category that governs the agent prose the hooks capture. With it denied,
Weave still records that Codex responded — timestamps, model, and message length — but stores none
of the text. [AI skills](/reports/ai-skills) conversation scoring reads that text, so denying the
category means Codex sessions are not scored.

`--privacy-mode true` remains available as a single switch that denies all five categories at once —
prompt bodies, agent messages, tool I/O, file paths, and git context — rather than just prompt text.

## Related integrations

* [Claude Code](/ai-tools/claude-code) — CLI-based AI assistant
* [Cline](/ai-tools/cline) — VS Code extension for AI coding
* [Cursor](/ai-tools/cursor) — AI IDE


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