weave

Weave Claude Code Plugin

Track Claude Code sessions in Weave for observability and debugging. Every session, turn, tool call, and subagent is automatically logged as a structured trace — no code changes required.

Quick Start

1. Install the CLI

npm install -g weave-claude-code

2. Run the installer

weave-claude-code install

This will:

• Create ~/.weave-claude-code/settings.json
• Register the plugin in Claude Code
• Prompt for your Weave project (entity/project) and W&B API key if not already set

Your W&B API key is available at https://wandb.ai/authorize.

For CI, bootstrap scripts, or other automated systems, you can skip prompts:

WEAVE_PROJECT=my-entity/my-project \
WANDB_API_KEY=<your-api-key> \
weave-claude-code install --non-interactive

In non-interactive mode, the installer still creates config, registers the Claude marketplace, and installs the plugin. It does not prompt for missing values. Instead, it:

• Uses WEAVE_PROJECT and WANDB_API_KEY from the environment when present
• Warns and continues if either value is missing
• Leaves environment-provided values in the environment rather than writing them into settings.json

By default, claude plugin marketplace add clones wandb/weave-claude-code from GitHub. In CI or container sandboxes without git/SSH access to GitHub, pass --source=local to register the marketplace from the npm-installed tree on disk instead:

npm install -g weave-claude-code
weave-claude-code install --non-interactive --source=local

--source=local requires the package to be installed globally via npm first (it reads from $(npm root -g)/weave-claude-code). Upgrades follow the npm cadence; the marketplace ref drift check is skipped for local sources.

3. Restart or launch Claude Code

If Claude Code is already running, reload plugins from inside the session:

/reload-plugins

Otherwise, launch Claude Code from any folder:

claude

Sessions are traced automatically from this point, across all Claude Code sessions on this machine. Tracing is not scoped to a single project. To stop tracing, run weave-claude-code uninstall.

Open your Weave project to see them.

---

Data Disclosure

This plugin sends Claude Code session data to W&B Weave.

That data can include sensitive content, including:

• user prompts
• Claude responses
• tool inputs
• tool outputs
• file paths and file contents read by Claude Code tools
• shell commands and shell output
• fetched URLs and fetched page content

If Claude Code accesses secrets, credentials, proprietary source code, personal data, or other confidential material during a session, that information may be logged to W&B Weave as part of the trace.

PII scrubbing and sensitive-data redaction are not yet implemented in the current version. If you cannot send this data to W&B Weave under your security or compliance requirements, do not install or enable this plugin yet.

---

Configuration

# Show all current settings (env-var overrides are flagged in the output)
weave-claude-code config show

# Read a single setting (resolves env-var overrides)
weave-claude-code config get weave_project

# Set your Weave project
weave-claude-code config set weave_project my-entity/my-project

# Set your W&B API key
weave-claude-code config set wandb_api_key <your-api-key>

# (Optional) Customize the agent name shown in Weave's Agents view (default: claude-code)
weave-claude-code config set agent_name my-team-bot

You can also set these via environment variables — they take precedence over the settings file:

export WEAVE_PROJECT=my-entity/my-project
export WANDB_API_KEY=<your-api-key>
export WEAVE_AGENT_NAME=my-team-bot

This is especially useful with weave-claude-code install --non-interactive, where the installer checks these variables instead of prompting.

---

Sending Traces to a Dedicated or Private W&B Instance

If you use W&B Dedicated Cloud or a self-hosted instance, set WANDB_BASE_URL to point the plugin at your deployment before launching Claude Code:

export WANDB_BASE_URL=https://your-instance.wandb.io

On SaaS, leave WANDB_BASE_URL unset (traces go to https://trace.wandb.ai). Setting it to the SaaS API host https://api.wandb.ai is handled automatically, since that host has no trace-ingest route. To send traces somewhere other than the wandb API host, set WF_TRACE_SERVER_URL, which takes precedence over WANDB_BASE_URL.