Forge Claude Code Plugin

Trace Claude Code sessions with CoreWeave Forge AgentLens for observability and debugging. Every session, turn, tool call, and subagent is logged as a structured trace, with no code changes required.

Quick Start

1. Install the CLI

npm install -g @coreweave/forge-claude-code

2. Run the installer

forge-claude-code install

This will:

Create ~/.forge-claude-code/settings.json
Register the plugin in Claude Code
Prompt for your Forge 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:

FORGE_TRACE_PROJECT=my-entity/my-project \
WANDB_API_KEY=<your-api-key> \
forge-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 FORGE_TRACE_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/forge-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 @coreweave/forge-claude-code
forge-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)/@coreweave/forge-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 Claude Code project. To stop tracing, run forge-claude-code uninstall.

Open your Forge project in CoreWeave Forge AgentLens to see them.

Data Disclosure

This plugin sends Claude Code session data to CoreWeave Forge AgentLens.

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 CoreWeave Forge AgentLens 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 CoreWeave Forge AgentLens 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)
forge-claude-code config show

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

# Set your Forge project
forge-claude-code config set project my-entity/my-project

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

# (Optional) Customize the agent name shown in CoreWeave Forge AgentLens (default: claude-code)
forge-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 FORGE_TRACE_PROJECT=my-entity/my-project
export WANDB_API_KEY=<your-api-key>
export FORGE_CLAUDE_CODE_AGENT_NAME=my-team-bot

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

Check Status

forge-claude-code status

Each line shows ✓ (OK), ✗ (action needed), or - (not yet active but not an error).

If sessions are not appearing in CoreWeave Forge AgentLens, check the daemon log for errors:

forge-claude-code logs              # last 50 lines (default)
forge-claude-code logs --tail 200   # last N lines
forge-claude-code logs --follow     # tail -f

The log file is also directly at ~/.forge-claude-code/logs/daemon.log.

For more verbose daemon output while diagnosing an issue, enable debug mode:

forge-claude-code config set debug true
# or, just for the current shell session:
export FORGE_CLAUDE_CODE_DEBUG=1

Skills

Once the plugin is installed, three skills are available directly inside any Claude Code session. They use a /forge:forge-* naming pattern (rather than the shorter /forge:install form) to avoid colliding with Claude Code's built-in skills.

`/forge:forge-install`

Walks through the full installation and configuration flow interactively. Use this on a fresh machine or to diagnose a broken setup. Claude will check for the CLI, run the installer, prompt for missing config values, and verify everything is working.

/forge:forge-install

`/forge:forge-status`

Checks the current plugin status and explains any issues. Equivalent to running forge-claude-code status but Claude interprets the output and tells you exactly what to fix.

/forge:forge-status

`/forge:forge-config`

Read or update plugin configuration without leaving Claude Code.

# Show current config
/forge:forge-config

# Set a value directly
/forge:forge-config set project my-entity/my-project
/forge:forge-config set wandb_api_key <your-api-key>

What Gets Traced

The plugin emits OTel spans that follow the GenAI semantic conventions and ships them to the CoreWeave Forge AgentLens observability backend (/agents/otel/v1/traces). Each user prompt produces one OTel trace (the "turn"); multi-turn conversations are stitched together server-side via gen_ai.conversation.id, which is set to the Claude Code session id on every span in the turn.

Spans are built with the CoreWeave Forge SDK. Every span carries the forge.integration.* identity of this plugin; the OTLP resource reports service.name = forge-claude-code and wandb.sdk.name = forge.

invoke_agent claude-code                  (root — one trace per user prompt)
├─ chat <model>                           (each LLM API call within the turn)
├─ execute_tool <tool_name>               (each tool call: Read, Bash, Grep, ...)
└─ invoke_agent <subagent_type>           (subagent dispatched via the `Agent` tool)
   ├─ chat <model>                        (subagent LLM calls)
   └─ execute_tool <tool_name>            (tools the subagent ran)

Subagents (dispatched via Claude Code's Agent tool) are emitted as their own nested invoke_agent span — a direct child of the turn span, sibling of any regular tool calls — not as an execute_tool Agent span. This matches the CoreWeave Forge AgentLens chat view's reference structure, where nested invoke_agent spans render as an agent_start lifecycle marker for the subagent. The spawning tool_use_id is preserved on the inner invoke_agent span as forge.claude_code.subagent.spawning_tool_call_id.

Permission requests appear as forge.permission_request events on the corresponding tool or agent call span; context-window compaction is recorded as weave.compaction.{summary,items_before,items_after} attributes on the turn span open at compaction time (or the next turn if compaction fires between turns).

Each span includes per-call token usage (gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, cache and reasoning token counts), model name (gen_ai.request.model), tool inputs and outputs (gen_ai.tool.call.arguments, gen_ai.tool.call.result), timing, and the textual content of prompts and assistant messages (gen_ai.input.messages, gen_ai.output.messages).

Important: tool inputs and outputs may contain sensitive information. In practice this can include file contents, command output, URLs, fetched content, and other data handled by Claude Code during a session. That information is sent to CoreWeave Forge AgentLens. PII scrubbing/redaction is planned for a future release, but is not available today.

Uninstall

forge-claude-code uninstall

Pass --keep-logs to preserve the log directory.

Dedicated and On-Prem Instances

Only needed for W&B Dedicated Cloud or a self-hosted instance. On SaaS, traces go to https://trace.wandb.ai with no setup.

Set WANDB_BASE_URL to your deployment before launching Claude Code:

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

Traces then go to its trace server at https://your-instance.wandb.io/traces. Setting WANDB_BASE_URL to the SaaS API host, https://api.wandb.ai, still sends traces to https://trace.wandb.ai.

To use a different trace server, set FORGE_TRACE_BASE_URL to its URL. It takes precedence over WF_TRACE_SERVER_URL, which takes precedence over WANDB_BASE_URL.

The daemon reads these variables once, at startup. If it is already running, set them and restart it from the same shell:

export WANDB_BASE_URL=https://your-instance.wandb.io
forge-claude-code restart

Releasing

The release workflow publishes to npm. GitHub marketplace installs use a specific release tag rather than the repository default branch. New releases are cut via two GitHub Actions:

Version Bump — dispatched with a version like 0.1.2. Bumps the version across the repo and creates and pushes the matching v0.1.2 tag.
Publish Package — dispatched with the tag (e.g. v0.1.2). Verifies the tag is consistent and not already published, then builds and publishes to npm.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.githooks		.githooks
.github		.github
.reuse/templates		.reuse/templates
LICENSES		LICENSES
hooks		hooks
scripts		scripts
skills		skills
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
NOTICE		NOTICE
README.md		README.md
REUSE.toml		REUSE.toml
cla.md		cla.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Forge Claude Code Plugin

Quick Start

Data Disclosure

Configuration

Check Status

Skills

`/forge:forge-install`

`/forge:forge-status`

`/forge:forge-config`

What Gets Traced

Uninstall

Dedicated and On-Prem Instances

Releasing

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Forge Claude Code Plugin

Quick Start

Data Disclosure

Configuration

Check Status

Skills

/forge:forge-install

/forge:forge-status

/forge:forge-config

What Gets Traced

Uninstall

Dedicated and On-Prem Instances

Releasing

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`/forge:forge-install`

`/forge:forge-status`

`/forge:forge-config`