Getting started
This tutorial takes you from nothing to a Costpilot dashboard that shows the cost of your own AI coding sessions per issue. It has three steps and takes about 15 minutes:
- Run Costpilot: start the server, locally or in the cloud, and look at the demo data.
- Connect your tools: install the Costpilot Agent on a developer machine and point Claude Code, Gemini CLI, Codex CLI or Cursor at your server.
- See your first session: work on a branch with an issue key and watch it appear in the dashboard.
If something does not show up, the troubleshooting page walks through the checks in the order that finds the problem fastest.
Who does what
Costpilot has two parts, and usually two people set them up:
| Part | Runs where | Set up by |
|---|---|---|
| Costpilot server (API + dashboard) | One service with a volume, or your laptop | Admin / platform team, once |
Costpilot Agent (costpilot-agent CLI) | Every developer machine | Each developer, once per machine |
If you are a developer and your team already runs a Costpilot server, skip straight to Connect your tools. You need two values from your admin: the server URL and, if the server requires one, the ingestion token. To look at the dashboard yourself you also need an account, which an admin creates with an invite link.
If you are an Engineering Manager who only wants to read the dashboard, see Reading the dashboard.
What you need
- Node.js 20 or newer on the machines involved. Check with
node --version. - At least one AI coding tool installed and started once: Claude Code, Gemini CLI, Codex CLI or Cursor.
- Issue keys in branch names, such as
feature/PROJ-123-login. That is how Costpilot knows which issue a session belongs to. Branches without a key still count, under the branch name.