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

# Claude Code Integration

Trace your Claude Code conversations. Every turn, tool call, and LLM interaction shows up on your Staso dashboard -- with token usage, duration, and errors.

No code changes. One setup command.

## Setup

```bash
pip install staso
# or
uv pip install staso
```

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

That's it. Start a Claude Code conversation and traces flow automatically.

## What Shows Up on the Dashboard

Each conversation turn becomes a trace. Within each trace:

| Span | Kind | What It Captures |
|------|------|-----------------|
| **Turn** (root) | `agent` | Total duration, prompt, final response |
| **LLM calls** | `llm` | Model, input/output tokens, cache tokens, duration |
| **Tool calls** | `tool` | Tool name, input, output/error, exact execution duration |
| **Subagents** | `agent` | Agent type, token usage, exact duration |
| **API errors** | `agent` | Error type (rate limit, auth, socket, billing), duration before failure |

All turns from the same Claude Code conversation are grouped together on your dashboard.

## Setup Options

| Flag | Description |
|------|-------------|
| `--api-key KEY` | Staso API key (`ak_...`). Falls back to `STASO_API_KEY` env var. |
| `--workspace SLUG` | Workspace identifier |
| `--environment ENV` | Environment tag (default: `production`) |
| `--agent-id ID` | Agent ID shown on dashboard |
| `--scope {global,project}` | `global` writes to `~/.claude/settings.json`, `project` writes to `.claude/settings.local.json` |

## Scope

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

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

**Project** -- traces only conversations in the current project directory:

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

## Environment Variables

The setup command writes these to your Claude Code settings automatically. You can also set them manually:

| Variable | Purpose |
|----------|---------|
| `STASO_API_KEY` | API key for authentication |
| `STASO_BASE_URL` | Backend URL (override for debugging) |
| `STASO_WORKSPACE_SLUG` | Workspace identifier |
| `STASO_ENVIRONMENT` | Environment tag |
| `STASO_AGENT_ID` | Agent ID on dashboard |
| `STASO_DEBUG` | Set to `1` for debug logging |

## Upgrading

After upgrading the staso package, hook configuration updates automatically on the next conversation start. No need to re-run setup.

```bash
pip install --upgrade staso
```

## Re-running Setup

Safe to run multiple times. It replaces existing Staso hooks without affecting other hooks you've configured.

## Disabling

Remove the Staso hooks from your Claude Code settings file (`~/.claude/settings.json` for global, `.claude/settings.local.json` for project). Delete the `STASO_*` entries from the `env` section and the Staso entries from the `hooks` section.
