---
title: Claude Code Integration
description: Trace Claude Code CLI sessions -- every turn, tool call, LLM interaction, and subagent.
---

# Claude Code Integration

Trace your Claude Code CLI sessions. Every turn, tool call, LLM interaction, and subagent shows up on your Staso dashboard -- with tokens, latency, and errors.

No code changes. One setup command.

## Setup

```bash
pip install staso
```

**Interactive** -- the wizard guides you through each step:

```bash
staso setup
```

**Or with flags** for scripted/CI setup:

```bash
staso setup --target claude-code \
  --api-key ak_... \
  --workspace my-workspace \
  --environment default \
  --agent-id my-agent
```

Start a Claude Code session. Traces flow automatically.

## What Shows Up on the Dashboard

Each conversation turn becomes a trace:

| Span | Kind | What It Captures |
|------|------|-----------------|
| **Turn** (root) | `agent` | Total duration, prompt, model, final response, aggregated token usage |
| **LLM calls** | `llm` | Model, input/output/cache tokens, content, response ID, duration |
| **Tool calls** | `tool` | Tool name, input, output, exact execution duration |
| **Subagents** | `agent` | Agent type, duration, aggregated LLM token usage |

All turns from the same Claude Code session are grouped together.

## Setup Options

| Flag | Default | Description |
|------|---------|-------------|
| `--api-key KEY` | *required* | Staso API key (`ak_...`). Falls back to `STASO_API_KEY` env var |
| `--workspace SLUG` | `default` | Workspace identifier |
| `--environment ENV` | `default` | Environment tag |
| `--agent-id ID` | | Agent ID shown on dashboard |
| `--scope` | `global` | `global` writes to `~/.claude/settings.json`, `project` writes to `.claude/settings.local.json` |
| `--auto-sync` | | Auto-sync hook config on each session start |

## Scope

**Global** (default) traces every Claude Code session on your machine:

```bash
staso setup --target claude-code --api-key ak_... --scope global
```

**Project** traces only sessions in the current directory:

```bash
staso setup --target claude-code --api-key ak_... --scope project
```

## Hook Events

Claude Code provides 10 hook events for comprehensive tracing:

| Event | What It Does |
|-------|-------------|
| `SessionStart` | Initialize session state, auto-sync hooks if enabled |
| `UserPromptSubmit` | Start a new turn, record prompt and transcript position |
| `PreToolUse` | Record tool start time for duration calculation |
| `PostToolUse` | Send tool span with input, output, and precise duration |
| `PostToolUseFailure` | Send tool span with error status and error message |
| `Stop` | Parse transcript for LLM spans, send turn span with aggregated data |
| `StopFailure` | Send turn span with error status when session stops with error |
| `SubagentStart` | Record subagent start time |
| `SubagentStop` | Send subagent span with LLM data from subagent transcript |
| `SessionEnd` | Clean up session state |

## LLM Span Extraction

Claude Code hooks parse the JSONL transcript file to extract individual LLM calls. Each LLM call becomes its own span with:

- Model name (e.g. `claude-sonnet-4-20250514`)
- Input tokens, output tokens, total tokens
- Cache read tokens, cache creation tokens
- Response content and response ID
- Duration (estimated from transcript timestamps)

## Status

Check your current configuration:

```bash
staso status --target claude-code
```

## Upgrading

```bash
staso update
```

This upgrades the staso package and syncs your hook configuration. Or manually:

```bash
pip install -U staso
staso sync
```

To enable automatic syncing on each session start:

```bash
staso sync --enable-auto-sync
```

## Uninstalling

Remove all Staso hooks from Claude Code and clean up state files:

```bash
staso uninstall --target claude-code
```

This removes hook entries and `STASO_*` env vars from `~/.claude/settings.json` (or `.claude/settings.local.json` for project scope) and deletes cached state files.
