> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 플러그인

> Agent Lens에서 Claude Code 세션을 추적하여 관측성을 확보하고 디버깅하세요.

Claude Code용 Weave 플러그인은 모든 Claude Code 세션을 자동으로 트레이스하고 구조화된 데이터를 Agent Lens로 전송합니다. 코드를 변경하지 않아도 모든 턴, 도구 Call, 서브에이전트가 로깅됩니다. 이 트레이스를 활용해 세션을 디버깅하고, 도구 사용 내역을 감사하고, 여러 run에 걸친 비용과 지연 시간을 모니터링하세요.

이 가이드에서는 플러그인을 설치하고, Agent Lens에서 Claude Code 트레이스를 확인하고, 플러그인을 설정하고, 플러그인 라이프사이클을 관리하는 방법을 안내합니다.

<Note>
  이 플러그인은 Weights & Biases Weave 플러그인이며, CoreWeave Forge 버전은 아직 제공되지 않습니다. Agent Lens와 Weave는 동일한 트레이스 데이터를 공유하므로 플러그인이 전송한 트레이스는 Agent Lens에 표시됩니다.
</Note>

<Warning>
  이 플러그인은 Claude Code 세션 데이터를 Agent Lens로 전송합니다. 이 데이터에는 사용자 프롬프트, Claude 응답, 도구 입력 및 출력, Claude Code 도구가 읽은 파일 내용, 셸 명령어 및 출력, 가져온 URL 및 페이지 콘텐츠가 포함될 수 있습니다.

  PII 제거 및 민감한 데이터 마스킹 기능은 제공되지 않습니다. 보안 또는 규정 준수 요구 사항상 이 데이터를 Agent Lens로 전송할 수 없다면 이 플러그인을 설치하지 마세요.
</Warning>

<h2 id="prerequisites">
  사전 요구 사항
</h2>

* [Node.js](https://nodejs.org/) v18 이상(`npm` 포함)
* 설치 및 인증이 완료된 [Claude Code](https://claude.ai/code)
* CoreWeave Forge 계정 및 `WANDB_API_KEY` 환경 변수로 설정된 [API 키](https://forge.coreweave.com/settings#apikeys)
* 트레이스를 수신할 Agent Lens 프로젝트(`[YOUR-TEAM]/[YOUR-PROJECT]`)

<h2 id="install-the-plugin">
  플러그인 설치
</h2>

CLI를 설치하고 설치 프로그램을 실행해 Claude Code에 플러그인을 등록한 다음, Claude Code 세션을 시작하면 트레이싱이 시작됩니다.

<Steps>
  <Step title="CLI 설치">
    ```bash lines theme={"system"}
    npm install -g weave-claude-code
    ```
  </Step>

  <Step title="설치 프로그램 실행">
    ```bash lines theme={"system"}
    weave-claude-code install
    ```

    설치 프로그램은 다음 작업을 수행합니다.

    * `~/.weave-claude-code/settings.json`을 생성합니다.
    * Claude Code에 플러그인을 등록합니다.
    * Agent Lens 프로젝트(`[YOUR-TEAM]/[YOUR-PROJECT]`)와 Forge API 키가 아직 설정되어 있지 않으면 입력을 요청합니다.

    CI, 부트스트랩 스크립트 등 자동화된 시스템에서 입력 요청을 건너뛰려면 실행하기 전에 환경 변수를 설정하세요.

    ```bash lines theme={"system"}
    WEAVE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT] \
    WANDB_API_KEY=[YOUR-API-KEY] \
    weave-claude-code install --non-interactive
    ```

    비대화형 모드에서도 설치 프로그램은 설정 파일을 생성하고 플러그인을 등록합니다. 이때 환경 변수의 `WEAVE_PROJECT`와 `WANDB_API_KEY`를 사용하며, 둘 중 하나라도 없으면 경고를 표시합니다.
  </Step>

  <Step title="Claude Code 시작">
    ```bash lines theme={"system"}
    claude
    ```

    이제부터 플러그인이 세션을 자동으로 트레이스합니다. 프롬프트를 한두 개 실행한 다음 Agent Lens 프로젝트를 열어 트레이스가 표시되는지 확인하세요.
  </Step>
</Steps>

<h2 id="view-claude-code-traces-in-agent-lens">
  Agent Lens에서 Claude Code 트레이스 보기
</h2>

Claude Code 세션을 한 번 이상 실행한 후 Agent Lens UI에서 프로젝트를 여세요.

1. [CoreWeave Forge](https://forge.coreweave.com)로 이동하여 제품 메뉴에서 Agent Lens를 선택한 다음, 사이드 메뉴 상단의 프로젝트 선택기에서 프로젝트를 선택하세요.
2. 사이드 메뉴에서 **Conversations**를 선택하세요.
3. **Conversations** 탭을 선택하면 프로젝트에 저장된 모든 에이전트 대화를 확인할 수 있습니다.
4. 대화를 선택하면 전체 대화 트리를 자세히 살펴볼 수 있습니다.

Conversation 탭에 대한 자세한 내용은 [에이전트 활동 보기](/ko/products/agent-lens/conversations/view-activity)를 참조하세요.

사용자 프롬프트마다 [GenAI 시맨틱 규칙](https://opentelemetry.io/docs/specs/semconv/gen-ai/)을 따르는 OTEL 트레이스가 하나씩 생성됩니다. 트레이스에는 다음과 같이 전체 턴 계층 구조가 표시됩니다.

```text theme={"system"}
invoke_agent claude-code               (루트, 사용자 프롬프트당 트레이스 1개)
├─ chat <model>                        (해당 턴 내의 각 LLM Call)
├─ execute_tool <tool_name>            (Read, Bash, Grep 등의 각 도구 Call)
└─ invoke_agent <subagent_type>        (Agent 도구를 통해 호출된 서브에이전트)
   ├─ chat <model>
   └─ execute_tool <tool_name>
```

루트 `invoke_agent claude-code` span은 최상위 에이전트 이름을 사용하며, 기본값은 `claude-code`입니다. 이 이름은 `agent_name` 설정이나 `WEAVE_AGENT_NAME` 환경 변수로 변경할 수 있습니다([플러그인 설정](#configure-the-plugin) 참조). 서브에이전트는 자체 유형 이름을 그대로 유지합니다.

멀티턴 대화는 서버 측에서 대화 ID를 기준으로 연결되므로, 여러 트레이스에 걸친 대화의 흐름을 따라갈 수 있습니다. 각 span에는 토큰 사용량, 모델 이름, 도구 입력 및 출력, 소요 시간, 프롬프트와 응답의 텍스트 내용이 포함됩니다. 트레이스되는 데이터에 대한 자세한 내용은 GitHub의 [What Gets Traced](https://github.com/wandb/weave-claude-code/blob/main/README.md#what-gets-traced)를 참조하세요.

<h2 id="configure-the-plugin">
  플러그인 설정하기
</h2>

설치 후에는 `weave-claude-code config` 명령어로 플러그인 설정을 확인하거나 변경할 수 있습니다.

```bash lines theme={"system"}
# 현재 설정을 모두 표시합니다.
weave-claude-code config show

# Weave 프로젝트를 설정합니다.
weave-claude-code config set weave_project [YOUR-TEAM]/[YOUR-PROJECT]

# Forge API 키를 설정합니다.
weave-claude-code config set wandb_api_key [YOUR-API-KEY]

# (선택) Conversations 탭에 표시되는 에이전트 이름을 지정합니다.
weave-claude-code config set agent_name [YOUR-AGENT-NAME]
```

기본적으로 대화는 Conversations 탭에서 `claude-code`라는 에이전트 이름으로 표시됩니다. 팀이나 프로젝트를 구분하는 등 다른 이름을 사용하려면 `agent_name`을 설정하세요. 이름은 비워 둘 수 없으며, 앞뒤 공백은 자동으로 제거됩니다.

환경 변수는 설정 파일보다 우선 적용됩니다.

```bash lines theme={"system"}
export WEAVE_PROJECT=[YOUR-TEAM]/[YOUR-PROJECT]
export WANDB_API_KEY=[YOUR-API-KEY]
export WEAVE_AGENT_NAME=[YOUR-AGENT-NAME]
```

<h2 id="agent-lens-skills">
  Agent Lens 스킬
</h2>

설치를 마치면 모든 Claude Code 세션에서 Agent Lens 전용 스킬 세 가지를 바로 사용할 수 있습니다.

| 스킬 | 명령어 | 설명 |
| - | - | - |
| 설치 | `/weave:weave-install` | 설치 및 설정 과정을 대화형으로 단계별 안내합니다. 새 머신에서 설정하거나 문제가 생긴 설정을 진단할 때 사용하세요. |
| 상태 | `/weave:weave-status` | 현재 플러그인 상태를 확인하고 문제가 있으면 설명합니다. `weave-claude-code status`를 실행하는 것과 같지만, Claude가 출력을 해석해 무엇을 수정해야 하는지 알려 줍니다. |
| 설정 | `/weave:weave-config` | Claude Code를 벗어나지 않고 플러그인 설정을 조회하거나 업데이트합니다. |

`weave:weave-config` 스킬을 사용하면 Claude Code 안에서 Agent Lens 값을 설정할 수 있습니다.

```text theme={"system"}
/weave:weave-config set weave_project [YOUR-TEAM]/[YOUR-PROJECT]
/weave:weave-config set wandb_api_key [YOUR-API-KEY]
/weave:weave-config set agent_name [YOUR-AGENT-NAME]
```

<h2 id="check-plugin-status">
  플러그인 상태 확인
</h2>

다음 CLI 명령어로 플러그인 상태를 확인하거나 문제를 해결할 수 있습니다.

```bash lines theme={"system"}
weave-claude-code status
```

각 줄에는 `✓`(정상), `✗`(조치 필요), `-`(아직 활성화되지 않았지만 오류는 아님) 중 하나가 표시됩니다.

Agent Lens에 대화가 표시되지 않으면 데몬 로그를 확인하세요.

```bash lines theme={"system"}
weave-claude-code logs
```

로그를 실시간으로 확인(tail)하려면 다음 명령을 실행하세요.

```bash lines theme={"system"}
weave-claude-code logs --follow
```

로그 파일은 `~/.weave-claude-code/logs/daemon.log`에서도 확인할 수 있습니다.

<h2 id="uninstall">
  제거
</h2>

Claude Code에서 플러그인을 제거하려면 다음 명령을 실행하세요.

```bash lines theme={"system"}
weave-claude-code uninstall
```

로그 디렉터리를 유지하려면 `--keep-logs` 옵션을 지정하세요.