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

# Claude Code plugin

> Install the Weave plugin on each machine for per-developer Claude Code telemetry

The Weave Claude Code plugin is a lightweight telemetry hook installed on each developer's machine. It captures per-session, per-developer activity directly from Claude Code's hook events and sends it to Weave.

It works on **any** Claude Code setup — no Anthropic Console account, Team/Enterprise plan, or Admin Settings access required. Use it when you want per-machine install health and individual developer tracking, or to add richer signals on top of [telemetry](/ai-tools/claude-code) you've already set up.

<Note>
  Not sure which Claude Code connection to use? The [Claude Code](/ai-tools/claude-code) page covers managed-settings telemetry and the Admin API key. This page covers the per-machine **Plugin**, which captures the most granular per-developer signals and requires no admin plan. [Weave Router](/router/overview) is a separate product that changes which model serves each request — installing one does not install the other.
</Note>

## What's tracked

The plugin hooks into the Claude Code session lifecycle and reports:

* **Session activity** — session start/end, duration, model, OS, and git branch/remote
* **Prompts** — prompt submissions and (optionally) prompt text for activity classification
* **Tool usage** — tool name, type, inputs, and results, plus tool failures
* **Subagents** — subagent start/stop, subagent type, and each subagent's final reply
* **Agent output** — agent responses and reasoning/thoughts
* **Skills** — which Claude Code skills are invoked
* **Install health** — a per-machine install ping so you can confirm each developer is reporting

## Which sessions are captured

The plugin captures every Claude Code session that runs as the operating-system user it was installed for, because each one fires the same hooks:

* `claude` in any terminal, including the integrated terminal in VS Code or JetBrains
* The Claude Code extension in VS Code and other IDEs
* Claude Code in the Claude Desktop app

It does not capture conversations that don't run Claude Code, such as chats on claude.ai or in the Claude Desktop chat view, or chat panels from other assistants. For GitHub Copilot Chat in VS Code, use the [Copilot plugin](/ai-tools/copilot-plugin).

The install is tied to an operating-system user's `~/.claude` folder. A VS Code window opened in WSL runs Claude Code as the Linux user inside the distribution, which has its own `~/.claude`, so it needs its own install there. See [Windows and WSL](#additional-requirements-for-windows-and-wsl).

## What it unlocks

* **No plan requirement** — works on any Claude Code account, including third-party and self-managed setups where the Admin API and managed settings aren't available
* **Per-developer, per-session granularity** — attribute activity to individual machines and developers rather than org-level aggregates
* **Install health monitoring** — see which machines have the plugin installed and reporting
* **Richer behavioral signals** — tool calls, subagent activity, and agent reasoning that the API-based methods don't expose
* **[AI skills](/reports/ai-skills)** — per-session conversation scoring (planning, verification, ownership, and more) uses the plugin's session-level signals or, on Claude Enterprise, Compliance API session transcripts
* **Easy rollout** — a generated install command for each environment where Claude Code runs, with auto-update built in

## Prerequisites

* Claude Code initialized for the current user, either from the CLI or the Claude Code Desktop integration (the installer looks for `~/.claude`)
* **Node.js 18 or later** in each environment where Claude Code runs. The Windows-to-WSL installer supplies it when missing on Ubuntu 24.04; install it yourself in other WSL distributions.
* A Weave plugin telemetry API key (created in the steps below)

### Additional requirements for Windows and WSL

The Windows-to-WSL installer is a Windows PowerShell wrapper around the existing Linux installer. Prepare both the Windows host and every Linux account where Claude Code runs:

| Where | Required setup |
| - | - |
| Windows host | Windows 10 or 11 with WSL enabled and `wsl.exe` available. Run the installer in **64-bit PowerShell** as the signed-in developer; it cannot inspect that user's distributions when run as `SYSTEM`. Windows Git is read only when the Linux global email is unset. Windows does not need Node.js or a separate Weave plugin package. |
| Each target WSL distribution and Linux user | A registered distribution with `sh`, Bash, and Git available to the target Linux user. Claude Code must have been initialized for that user so `~/.claude` exists. On Ubuntu 24.04, the installer supplies missing `base64`, `curl`, CA certificates, and Node.js 18 or later. Other distributions must already provide `base64`, `curl`, and a compatible Node.js installation. |
| Linux user identity | The target Linux user's **global** Git `user.email` is used when it is set. When it is unset, the installer uses the signed-in Windows user's Git `user.email`. JumpCloud, Intune, and other directory attributes are not read. |
| Network | The Windows host must be able to download the PowerShell installer, and each target WSL distribution must have outbound access to the Weave installer and the configured telemetry endpoint. Ubuntu dependency installation also needs access to its configured package repositories. |

No distribution name is hard-coded: by default, the installer inspects all registered WSL distributions and installs for each default Linux user with an initialized Claude profile. Distributions without a Claude profile or that cannot be probed automatically (for example, utility distributions without Bash) are skipped. Use `-Distribution` and `-LinuxUser` with a saved script when Claude runs in only selected distributions or under a non-default Linux account; a failure to inspect an explicitly selected distribution fails the install. The real-WSL CI test uses **Ubuntu 24.04 on WSL2**; other distributions are not covered by that integration test and must provide all required tools themselves. Automatic dependency installation checks the Linux OS version, not the registered distribution name.

**Correct user attribution is required before installation.** The WSL installer requires Git in the selected Linux account and reads `git config --global --get user.email` there before changing dependencies or plugin files. When that global email is unset, it asks Git for Windows for the signed-in Windows user's global email and uses that address. A Linux global email wins when both are set. A repository-local email, an explicit `--user-email`, JumpCloud, and Intune are not used. Missing Linux Git, or no usable email from either Git, fails that distribution and makes the overall run exit nonzero. It never installs Git or changes its configuration. The installer checks that an email is present and has a valid format; it cannot establish that the address belongs to the correct Weave account. Verify that mapping before deployment. The resolved email is written to the plugin configuration, including when reusing an existing configuration.

In a shell running as the Linux user that Claude Code will use, verify the prerequisites and email before deployment:

```bash theme={null}
command -v sh bash git
test -d "$HOME/.claude"
git config --global --get user.email
```

If that command prints nothing, the installer uses the signed-in Windows user's Git email instead. Git for Windows must be installed for that fallback. To set the Linux address explicitly:

```bash theme={null}
git config --global user.email "developer@company.com"
git config --global --get user.email
```

Windows and Linux usernames may differ. The Windows email is the Git identity of the Windows user who launched the installer.

On **Ubuntu 24.04**, the installer uses `apt-get` to install only missing dependencies (`coreutils` for `base64`, `curl`, `ca-certificates`, and `nodejs`). A compatible Node installation is reused, including one managed by nvm, mise, asdf, Volta, or fnm. Package operations run as Linux root through WSL without a `sudo` password prompt; plugin configuration and hooks are installed as the selected developer. A package installation failure stops that distribution's install. Package repositories must be configured and accessible, and package installation must be permitted by your device policy. Uninstall leaves these system packages in place.

On other distributions, install these dependencies yourself and verify them as the selected Linux user before deployment:

```bash theme={null}
command -v base64 curl node
node --version
```

## Setup

<Steps>
  <Step title="Create a plugin API key in Weave">
    Go to **Data** → **Claude Code** → **Connect**, answer **How do you pay for Claude Code?**, and click **Set up plugin** on the **Plugin** card. If you can't open that page, open **Personal plugin setup** on the **Data** page and choose **Claude Code**. Any signed-in member can click **Create my install command**. That command writes telemetry onto their own Weave account. **Revoke my install command** removes those personal commands. An admin can also click **Create API key** for a shared key that attributes by email. Weave shows the full key once.
  </Step>

  <Step title="Run the install command on each machine">
    Copy the command from the configuration modal and run it on each developer's machine.

    **macOS / Linux:**

    ```bash theme={null}
    curl -fsSL 'https://app.workweave.ai/api/claude_code/plugin/install.sh' | bash -s -- \
      --token 'YOUR_TOKEN' --endpoint 'YOUR_ENDPOINT'
    ```

    **Windows (PowerShell):**

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

    **Windows (Claude Code inside WSL):** choose **Windows (WSL)** in the configuration modal. That command is a separate Windows-side installer; it visits each registered WSL distribution, checks the default Linux user's `~/.claude`, and invokes the Linux installer there. The Windows-native command above only configures Claude running on Windows, even when its project is under `\\wsl.localhost`.

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

    The WSL installer starts stopped distributions when it visits them. It installs for each distribution's default Linux user; Windows and Linux usernames can differ. Use `-Distribution` and `-LinuxUser` with a saved script when you need to target one distribution or a non-default Linux account. VS Code Remote WSL and a WSL terminal share an install when both run Claude as the same Linux user. A distribution without `~/.claude` is skipped. If no selected distribution has an initialized Claude profile, the script prints **No eligible WSL install** and sets `$LASTEXITCODE` to 1. A saved copy run with `-File` exits with that code.

    To route telemetry through your redacting OpenTelemetry Collector, choose
    **Through an OpenTelemetry Collector** in the configuration modal. The
    generated command sets `--telemetry-mode collector` and the collector URL
    for you. The equivalent shell form is:

    ```bash theme={null}
    curl -fsSL 'https://app.workweave.ai/api/claude_code/plugin/install.sh' | bash -s -- \
      --token 'YOUR_TOKEN' --endpoint 'YOUR_ENDPOINT' \
      --telemetry-mode collector --collector-endpoint 'http://127.0.0.1:4318'
    ```

    Remote collectors must use HTTPS. Redact prompt and tool content in the
    collector, but preserve the `weave.token` resource attribute so Weave can
    associate the records with the organization.

    The installer verifies your token, downloads `weave-telemetry.js` to `~/.weave/claude-code-plugin/`, writes config to `~/.weave/claude-code-plugin.json`, and merges Weave hooks into `~/.claude/settings.json`. It then fires an install ping. Direct mode confirms that Weave accepted it; collector mode confirms only collector receipt, so check the collector's Weave exporter for downstream delivery.
  </Step>

  <Step title="Start a session">
    Hooks take effect on the next Claude Code session — no restart needed. Run a session and confirm activity appears in Weave.
  </Step>
</Steps>

The plugin **auto-updates**: when Weave ships a new version, installed plugins pick it up automatically, so you don't need to re-run the installer on every release.

### Content settings

Five content categories control what the plugin sends. They are the same set the [Cursor plugin](/ai-tools/cursor-plugin) and [Codex plugin](/ai-tools/codex-plugin) use. The install command Weave generates already includes your organization's **Telemetry content retention** floor. Members can deny more categories, but can't turn back on a category the organization denies.

| Category | Covers | Install flag |
| - | - | - |
| `prompt_bodies` | Text of the prompts you send to Claude Code | `--prompt-bodies` |
| `agent_messages` | Claude's replies and reasoning | `--agent-messages` |
| `tool_io` | Tool inputs, results, and error messages | `--tool-io` |
| `file_paths` | Working directory and workspace paths | `--file-paths` |
| `git_context` | Branch name, repository remote, and commit state | `--git-context` |

Pass `false` to deny a category, for example `--tool-io false`. `--privacy-mode true` denies all five at once. On Windows, set `WEAVE_PRIVACY_MODE`, `WEAVE_PROMPT_BODIES`, `WEAVE_AGENT_MESSAGES`, `WEAVE_TOOL_IO`, `WEAVE_FILE_PATHS`, or `WEAVE_GIT_CONTEXT` before running install.ps1.

The installer writes these choices to `~/.weave/claude-code-plugin.json`. You can edit the file later; the hook reads it on every event:

```json theme={null}
{
  "privacy_mode": false,
  "content_policy": {
    "prompt_bodies": true,
    "agent_messages": true,
    "tool_io": true,
    "file_paths": true,
    "git_context": true
  }
}
```

`"privacy_mode": true` overrides `content_policy` and denies every category. Setting `WEAVE_PRIVACY_MODE=true` in the environment Claude Code runs in does the same.

Some reports need specific categories:

* **Agent autonomy** and other prompt-pattern metrics need `prompt_bodies`. Weave classifies each prompt from its text, and leaves out sessions with no classified prompt.
* **[AI skills](/reports/ai-skills)** conversation scoring needs `prompt_bodies`. It also uses `agent_messages`: without reply text, Weave scores a session only from its tool calls, and turns where Claude only replied in text add no evidence.
* **Skill usage** records typed `/skill` commands under any setting. From plugin version 43, it also records skills Claude invokes on its own when `tool_io` is denied or privacy mode is on. Earlier versions recorded those only when tool input was allowed. The plugin auto-updates, so installs pick this up without re-running the installer.

### Fleet / MDM rollout

For large teams, pre-deploy `~/.weave/claude-code-plugin.json` (with the token and endpoint) via your MDM, then run the install command without arguments — it reuses the existing config. The installer is idempotent: re-running it updates the hook command and skips events that are already wired up.

On macOS and Linux, the installer must run **as the developer's own user**, not as root. It installs into `$HOME/.weave/` and merges hooks into `$HOME/.claude/settings.json`, so a root-context run either fails because `$HOME` is unset or installs into root's home, where the developer's Claude Code never reads it. MDM tools (Jamf, Kandji, Intune, Fleet, Addigy) run scripts as `root` in a minimal environment by default. If your MDM has a "run as current user" (user-context) option, use it. On macOS, you can otherwise wrap the install command so it runs in the console user's session:

```bash theme={null}
#!/bin/bash
set -euo pipefail

# The actual GUI-logged-in user (not root)
consoleUser=$(/usr/bin/stat -f%Su /dev/console)
if [ -z "$consoleUser" ] || [ "$consoleUser" = "root" ] || [ "$consoleUser" = "loginwindow" ]; then
  echo "No console user logged in; skipping."
  exit 0
fi

# Run the installer as that user, in a login shell so HOME and PATH (nvm/Homebrew) are populated
/usr/bin/sudo -u "$consoleUser" -i /bin/bash -c '
  export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
  curl -fsSL "https://app.workweave.ai/api/claude_code/plugin/install.sh" | bash -s --
'
```

This reuses the pre-deployed `~/.weave/claude-code-plugin.json`. If you don't pre-deploy it, pass `--token` and `--endpoint` (plus any content flags such as `--privacy-mode`) to the install command instead; passing a token rewrites the config file, so don't combine it with a pre-deployed one.

Node.js 18 or later must be installed for the target user, and that user must have run Claude Code at least once so `~/.claude` exists.

#### Windows MDM rollout for WSL

The WSL installer must run as the signed-in Windows user in **64-bit PowerShell**. Running as SYSTEM cannot reach that user's registered distributions, Linux home, or Windows Git email. Select **Windows (WSL)** to download the generated `install-wsl.ps1`, which already carries the API key and organization content policy. When a target Linux account has no global Git email, the install uses that signed-in user's Windows Git email.

For JumpCloud, use its **Windows - Run As Signed In User** template. Save the generated script to a user-accessible location, then invoke it with `-File` so WSL eligibility and installation failures become the PowerShell process exit code:

```powershell theme={null}
$installer = Join-Path $env:LOCALAPPDATA 'Weave\install-wsl.ps1'
& "$env:WINDIR\System32\WindowsPowerShell\v1.0\powershell.exe" `
  -NoProfile -ExecutionPolicy Bypass -File $installer
exit $LASTEXITCODE
```

In Intune, use a platform PowerShell script with **Run this script using the logged on credentials = Yes** and **Run script in 64-bit PowerShell host = Yes**. The installer checks every registered distribution by default. You can save one run log per device from its per-distribution status lines; any eligible distribution failure makes the aggregate exit nonzero. Run the deployment again after a developer adds a new distribution.

An install ping is synthetic and does not prove that Claude invoked the hooks. After rollout, start a real Claude session from both a WSL terminal and VS Code Remote WSL and confirm session activity appears in Weave.

### Claude Code managed settings

Claude Code [server-managed settings](https://code.claude.com/docs/en/server-managed-settings) and managed settings files can deliver the [OpenTelemetry configuration](/ai-tools/claude-code) Weave reads, but they can't install the plugin. The plugin's hooks run `weave-telemetry.js` and read `~/.weave/claude-code-plugin.json`, and both files must exist on each machine, so run the installer per machine as described above.

Two Claude Code [hook policies](https://code.claude.com/docs/en/hooks) stop the plugin's hooks from running:

* `allowManagedHooksOnly` set in managed settings blocks user hooks, including the ones the installer writes to `~/.claude/settings.json`.
* `disableAllHooks: true` turns hooks off. Set in managed settings, it disables every hook. Set in user or project settings, it follows normal settings precedence.

If either applies, the installer and install ping still succeed, but Claude Code sessions send no plugin activity.

## Uninstall

To remove the plugin from a machine, run the install command with `--uninstall`. It removes the merged Weave hooks from `~/.claude/settings.json` (across every event Claude Code supports), deletes `~/.weave/claude-code-plugin/` and `~/.weave/claude-code-plugin.json`, and takes effect for any session started afterwards. The command is idempotent — a second run completes with no files left to clean up.

**macOS / Linux:**

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

**Windows (PowerShell):**

Switches cannot be passed through `iwr ... | iex`, so set the `WEAVE_UNINSTALL` environment variable instead — the script clears it after reading it, so it won't affect a later install in the same session:

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

Or, from a saved copy of `install.ps1`:

```powershell theme={null}
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall
```

**Windows (WSL):** this visits the registered distributions and removes the Linux install only; the Windows-native `-Uninstall` command remains limited to the Windows profile. Use a downloaded copy of `install-wsl.ps1`:

```powershell theme={null}
powershell -ExecutionPolicy Bypass -File install-wsl.ps1 -Uninstall
```

For a one-line uninstall expression, set the WSL uninstall switch before running the script:

```powershell theme={null}
$env:WEAVE_WSL_UNINSTALL='true'; iwr -useb 'https://app.workweave.ai/api/claude_code/plugin/install-wsl.ps1' | iex
```

The install commands also accept `--uninstall` after downloading the script:

```bash theme={null}
curl -fsSL 'https://app.workweave.ai/api/claude_code/plugin/install.sh' -o /tmp/install.sh && bash /tmp/install.sh --uninstall
```

<Note>
  Uninstall does not revoke the plugin API key. Rotate or delete it under **Data → Claude Code → Plugin** if you want every reference to it gone. The next install with a fresh key is a separate step after rotation.
</Note>

## Metrics enabled

Once reporting, the plugin feeds:

* **[AI output percentage](/metrics/ai-output-percentage)** — portion of output from Claude Code
* **[AI efficiency index](/metrics/ai-efficiency-index)** — impact on productivity
* **[Conversation prompt quality](/metrics/conversation-prompt-quality)** — prompt-level signals from captured sessions

## Cost tracking

The plugin doesn't report token usage, so it adds no cost estimate of its own. Claude Code spend comes from [telemetry](/ai-tools/claude-code) or a cost API key. See [cost tracking](/ai-tools/claude-code#cost-tracking) for the full order.

The plugin does make **cost per PR** more accurate. It records which branch and files each prompt worked on, so Weave can attribute that prompt's cost to the right PR instead of linking whole sessions to PRs. See [spend per engineer vs. cost per PR](/ai-tools/claude-code#spend-per-engineer-vs-cost-per-pr).

When the plugin and telemetry both report the same session or prompt, Weave keeps one copy, so running both doesn't double count. See [using them together](/ai-tools/claude-code#using-them-together).

## Sync frequency

Telemetry is sent in real time as each hook event fires during a session.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="terminal" title="Windows diagnostics">
    Run these checks in the same PowerShell session as the install command:

    ```powershell theme={null}
    node --version
    Test-Path "$env:USERPROFILE\.claude"
    Test-NetConnection app.workweave.ai -Port 443
    ```

    Required output:

    * Node reports `v18` or later
    * `Test-Path` reports `True`
    * `TcpTestSucceeded` reports `True`

    Verify the plugin token without printing it:

    ```powershell theme={null}
    Invoke-RestMethod `
      'https://app.workweave.ai/api/claude_code/plugin/install/verify' `
      -Headers @{ Authorization = "Bearer $env:WEAVE_TOKEN" }
    ```

    Required output: `ok: True` and `plugin_kind: claude_code`.

    If installation completed, test delivery end to end:

    ```powershell theme={null}
    node "$env:USERPROFILE\.weave\claude-code-plugin\weave-telemetry.js" --install-ping
    ```

    Required output: `WEAVE_INSTALL_PING:ok`.
  </Accordion>

  <Accordion icon="terminal" title="macOS diagnostics">
    Run these checks in the same terminal session as the install command:

    ```bash theme={null}
    node --version
    test -d ~/.claude && echo "Claude profile exists"
    curl -fsS https://app.workweave.ai/api/claude_code/plugin/version
    ```

    Required output:

    * Node reports `v18` or later
    * The directory check prints `Claude profile exists`
    * The endpoint returns JSON containing `version` and `hash`

    Verify the plugin token without printing it:

    ```bash theme={null}
    WEAVE_TOKEN="$(node -p 'require(process.env.HOME + "/.weave/claude-code-plugin.json").weave_token')"
    curl -fsS \
      -H "Authorization: Bearer $WEAVE_TOKEN" \
      https://app.workweave.ai/api/claude_code/plugin/install/verify
    unset WEAVE_TOKEN
    ```

    Required output: JSON containing `"ok":true` and `"plugin_kind":"claude_code"`.

    If installation completed, test delivery end to end:

    ```bash theme={null}
    node ~/.weave/claude-code-plugin/weave-telemetry.js --install-ping
    ```

    Required output: `WEAVE_INSTALL_PING:ok`.
  </Accordion>

  <Accordion icon="chart-line" title="No activity after install">
    A successful installer prints `Verified telemetry pipe` and `Installation complete`. After that:

    1. Check that `~/.claude/settings.json` contains hooks referencing `weave-telemetry.js`
    2. Fully quit and reopen Claude Desktop or the CLI
    3. Start a new Claude Code session

    If the install ping succeeds but session activity remains missing, confirm Claude Code is running under the same operating-system user that installed the plugin.
  </Accordion>
</AccordionGroup>

## Data privacy

The plugin sends session metadata, tool usage, agent output, and — unless privacy mode is on — prompt text. It does **not** read source files or repository contents beyond what Claude Code passes through the hook events.

## Related integrations

* [Claude Code](/ai-tools/claude-code) — managed-settings telemetry and Admin API key
* [Cursor plugin](/ai-tools/cursor-plugin) — the equivalent per-machine plugin for Cursor
* [Codex plugin](/ai-tools/codex-plugin) — the equivalent per-machine plugin for Codex
* [Copilot plugin](/ai-tools/copilot-plugin) — Copilot Chat OTEL export to Weave
* [OTel collector](/ai-tools/otel-collector) — route telemetry through your own collector


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