Skip to main content

See your first session

1. Put the issue key in your branch name​

cd ~/code/my-project
git checkout -b feature/PROJ-123-login

The hook derives the issue id from the branch on every prompt. Branch names that work:

BranchCounted as
feature/PROJ-123-loginPROJ-123
PROJ-123PROJ-123
bugfix/US-02.001-typoUS-02.001
main (no issue key)"No issue", kept under the branch dimension as main

The built-in pattern recognises Jira-style keys and dotted story ids. Your admin can replace it instance-wide or per project in the Admin Area. See Attribution for the details.

2. Use your AI tool like always​

Start Claude Code (or Gemini CLI, Codex CLI, Cursor) from inside the project directory and send one prompt. Two things happen quietly:

  • the tool exports one api_request event per model call to /v1/logs, plus periodic metrics to /v1/metrics;
  • the hook posts { session_id, issue_id: "PROJ-123", branch, repo, agent, reported_at } to /v1/session-map on the prompt (plus project_key when the repository belongs to a project), and again when the turn ends.

The server joins both by session id, stores the prompt as one turn and prices the calls. The hook shows nothing in the tool and never blocks it.

3. Verify from the project directory​

costpilot-agent check
Project /Users/me/code/my-project
  ✓ costpilot-agent is on the PATH: /usr/local/bin/costpilot-agent
Claude Code (claude-code)
  ! no project config here, the global one applies (/Users/me/.claude/settings.json): every project reports, not only this one
  ✓ telemetry: on → https://costpilot.example.com
  ✓ hook: UserPromptSubmit → https://costpilot.example.com/v1/session-map (auth: bearer token)
  ✓ branch feature/PROJ-123-login → issue PROJ-123, project PROJ
  ✓ server: accepted a test mapping (HTTP 200)
  ✓ Claude Code ran the hook 2 min ago: PROJ-123 (feature/PROJ-123-login) → HTTP 200

The ! line is expected with a global setup; it only reminds you that every project on this machine reports. The last line is the proof that the tool itself picked up the config. If it says ! not seen yet, restart the tool and send a prompt. Lines marked ✗ mean something is broken; the troubleshooting page explains each.

4. Find it in the dashboard​

Sign in to your Costpilot instance. Set the date range to Today, then look at the Issue tile: PROJ-123 should be there with the cost of your prompt. Click it to drill down to the turns, sessions and the activity feed of individual calls. The Actor tile shows you, the Model tile the model the tool used, and the Project tile the project your admin registered for the repository or issue key, or "No project".

Telemetry is exported in batches, so allow up to a minute.

5. Turn off demo mode​

If your instance runs with DEMO_MODE=1, do this before developers connect: while the flag is set, the whole database (usage, projects, alerts) is wiped and reseeded on the first request of each UTC day, so real telemetry sent to a demo instance is lost at that point.

  1. Remove DEMO_MODE (or set it to 0) in the environment of your deployment.
  2. Start empty: stop the API, delete the .db file (plus -wal and -shm) on the volume, start again. The first start prints the setup code for the first admin account.

Demo seeding only ever touches an empty database or one that already holds the demo dataset; a database that was never demo-seeded is left alone.

What's next​