Claude Code Integration

Trace your Claude Code sessions. 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

pip install staso

uv pip install staso

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

That's it. Start a Claude Code session 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 session 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

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

Traces every Claude Code session on your machine.

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

Traces only sessions in the current project directory.

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 session start. No need to re-run setup.

pip install --upgrade staso

uv pip install --upgrade staso

Re-running Setup

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

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.