Skip to main content

How it works

How Costpilot works

  1. Your AI coding agent (Claude Code, Gemini CLI or Codex CLI) exports usage logs and metrics via OpenTelemetry (OTLP over HTTP/JSON).
  2. The Costpilot Agent hook reads the issue id from the git branch and reports it on every prompt and again when the turn ends (POST /v1/session-map).
  3. The API stores both, computes cost from the price table, and joins issue titles from your tracker mirror.
  4. The Dashboard rolls it up per project, issue, actor, model and more, and compares issues in the Analysis tab.

Why two streams?​

Claude Code offers no way to inject a custom attribute such as an issue id into its telemetry: resource attributes are frozen at process start, and per-event attributes are computed by the tool. The documented workaround is to correlate in the receiving backend by session_id. That is exactly what Costpilot does: the hook sends the session → issue mapping separately and the API joins on the session id both streams carry.

Why a self-hosted server with SQLite?​

The data volume per team is small, one file on a volume needs no managed database, and serverless hosts have no persistent filesystem. The API image also serves the built dashboard, so one service is enough.

Pricing​

Claude Code reports each call's cost, and Costpilot stores it. Next to it the server calculates its own figure from tokens and the LiteLLM price table (bundled local fallback) as a cross-check and as the fallback for tools that report no cost, such as Gemini CLI and Codex CLI. Ingestion payloads only carry tokens and the reported cost, so a price change never requires a change on developer machines.