claudicle

Claudicle

The chronicles of Claude. Collect and visualize your Claude Code session telemetry — costs, tokens, tool usage, and full conversation transcripts — in a self-hosted web UI.

Why Claudicle?

Claude Code doesn't show you where your money goes. Claudicle gives you a dashboard for API costs, token trends, and tool performance across sessions. It also captures full conversation transcripts so you can review, search, and export any session — whether you're tracking your own usage or monitoring a team.

Installation Guide | Configuration | Contributing

Quick Start

git clone https://github.com/telepenin/claudicle && cd claudicle
cp .env.example .env
docker compose up -d

Configure Claude Code to send telemetry — use the plugin or add the settings manually:

Option A: Claude Code plugin (recommended)

Install the plugin with /plugin marketplace add telepenin/claudicle, then run /claudicle-configure. It writes the required env vars and interactively sets resource attributes (project, developer, team).

Option B: Manual

Add to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
    "OTEL_RESOURCE_ATTRIBUTES": "project=my-project,developer=your-name"
  }
}

Open http://localhost:3000. For full setup details, see the Installation Guide.

Alternative: Install via npm

If you already have ClickHouse running:

npm install -g claudicle

# Install the UI (saves credentials, initializes schema, registers as system service)
claudicle setup ui --user claude --password claude

# Install the OTel Collector on every machine running Claude Code
claudicle setup collector --user claude --password claude

Features

• Dashboard — cost and token trends, top models and tools, events by type, filterable by project/environment/team/developer

• Session browser — searchable list with message counts, subagent and error indicators, date range filtering

• Session detail view — rendered conversations with rich tool visualizations (diffs, code blocks, search results, MCP tools, nested subagent sessions), live tail for active sessions

• Session export — portable .tar.gz archives preserving the ~/.claude/projects/ structure, restore and resume on any machine

Architecture

                   ┌──OTLP HTTP──▶  OTel Collector (:4318) ──────────────────────────────┐
Claude Code ───────┤                                                                       ├──▶  ClickHouse  ──▶  Next.js App (:3000)
                   └──JSONL──▶  ~/.claude/projects/*.jsonl  ──▶  OTel Collector (filelog) ┘

• OTel Collector (otelcol-contrib) — receives OTLP on port 4318 + tails JSONL files, exports to ClickHouse
• ClickHouse (Docker) — stores events, metrics, and session logs
• Next.js App (Docker) — web UI and API routes

What Gets Collected

Source	Data
OTel events	user prompts, tool results (name/duration/success), API requests (model/cost/tokens), errors, tool decisions
OTel metrics	token usage, cost, session count, lines of code, commits, PRs, active time
JSONL logs (optional)	full conversation transcripts — prompts, responses, thinking blocks, tool I/O

Run the OTel Collector locally to enable JSONL log collection. See the Installation Guide.

Roadmap