Claude Code plugin

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 you’ve already set up.

Not sure which Claude Code connection to use? The 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 is a separate product that changes which model serves each request — installing one does not install the other.

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

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

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:

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:

command -v base64 curl node
node --version

Setup

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.

Run the install command on each machine

Copy the command from the configuration modal and run it on each developer’s machine.macOS / Linux:

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

Windows (PowerShell):

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

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

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.

Start a session

Hooks take effect on the next Claude Code session — no restart needed. Run a session and confirm activity appears in Weave.

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

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

#!/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:

$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 and managed settings files can deliver the OpenTelemetry configuration 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 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:

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:

$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 -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 -ExecutionPolicy Bypass -File install-wsl.ps1 -Uninstall

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

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

curl -fsSL 'https://app.workweave.ai/api/claude_code/plugin/install.sh' -o /tmp/install.sh && bash /tmp/install.sh --uninstall

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.

Metrics enabled

Once reporting, the plugin feeds:

AI output percentage — portion of output from Claude Code
AI efficiency index — impact on productivity
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 or a cost API key. See 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. 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.

Sync frequency

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

Troubleshooting

Windows diagnostics

Run these checks in the same PowerShell session as the install command:

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:

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:

node "$env:USERPROFILE\.weave\claude-code-plugin\weave-telemetry.js" --install-ping

Required output: WEAVE_INSTALL_PING:ok.

macOS diagnostics

Run these checks in the same terminal session as the install command:

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:

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:

node ~/.weave/claude-code-plugin/weave-telemetry.js --install-ping

Required output: WEAVE_INSTALL_PING:ok.

No activity after install

A successful installer prints Verified telemetry pipe and Installation complete. After that:

Check that ~/.claude/settings.json contains hooks referencing weave-telemetry.js
Fully quit and reopen Claude Desktop or the CLI
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.

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.

Claude Code — managed-settings telemetry and Admin API key
Cursor plugin — the equivalent per-machine plugin for Cursor
Codex plugin — the equivalent per-machine plugin for Codex
Copilot plugin — Copilot Chat OTEL export to Weave
OTel collector — route telemetry through your own collector

Get started

Releases

Features

Weave Router

Integrations

Reports

Metrics

Analysis

Annotations

Export

Tutorials

Skeleton group medium 6

Claude Code plugin

What’s tracked

Which sessions are captured

What it unlocks

Prerequisites

Additional requirements for Windows and WSL

Setup

Content settings

Fleet / MDM rollout

Windows MDM rollout for WSL

Claude Code managed settings

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

​Which sessions are captured

​What it unlocks

​Prerequisites

​Additional requirements for Windows and WSL

​Setup

​Content settings

​Fleet / MDM rollout

​Windows MDM rollout for WSL

​Claude Code managed settings

​Uninstall

​Metrics enabled

​Cost tracking

​Sync frequency

​Troubleshooting

​Data privacy

​Related integrations

What’s tracked

Which sessions are captured

What it unlocks

Prerequisites

Additional requirements for Windows and WSL

Setup

Content settings

Fleet / MDM rollout

Windows MDM rollout for WSL

Claude Code managed settings

Uninstall

Metrics enabled

Cost tracking

Sync frequency

Troubleshooting

Data privacy

Related integrations