Connect your tools

The Costpilot Agent is a small command-line program that runs on each developer's machine. One init command edits the settings of your AI coding tools so that they export usage telemetry to your Costpilot server, and installs a prompt hook that reports which issue the current session works on. Nothing runs in the background, and if the server is down your tools keep working as usual.

You do steps 1 to 4 once per machine.

What you need

• Node.js 20 or newer.
• At least one supported tool installed and started once.
• The server URL of your Costpilot instance, for example https://costpilot.example.com. Against a local server on http://localhost:8787 you can leave --endpoint out entirely.
• The ingestion token, if your server sets COSTPILOT_INGEST_TOKEN. If there is none, leave --token out.

Tool	Telemetry (tokens, model, tools)	Session → issue hook (prompt, turn end)
Claude Code	OTLP export via OTEL_* env in ~/.claude/settings.json	UserPromptSubmit, Stop
Gemini CLI	OTLP export via telemetry in ~/.gemini/settings.json	BeforeAgent, AfterAgent
Codex CLI	OTLP export via [otel] in ~/.codex/config.toml	UserPromptSubmit, Stop in ~/.codex/hooks.json
Cursor	none, Cursor exposes no token counts to hooks	beforeSubmitPrompt, stop in ~/.cursor/hooks.json

Step 1: Install the agent

npm install -g git+ssh://git@github.com/getcostpilot/agent.git

The package is not on npm yet and the repository is private, so you need access to getcostpilot/agent and a working git login (SSH key or gh auth login). Prefer HTTPS? Use git+https://github.com/getcostpilot/agent.git instead; git then asks for your username and a personal access token with repo scope.

Install globally

Your coding tools call costpilot-agent themselves on every prompt, so it must be on your PATH. A one-off npx run is not enough.

Check that it worked:

costpilot-agent --help

Step 2: Run init

costpilot-agent init --endpoint https://costpilot.example.com --token <your-token>

The agent asks the server which tools your team uses (set by your admin in the Admin Area, see Central configuration), sets up every one of them that is installed on your machine (Claude Code if none is found) and prints what it changed:

Central agent config loaded from https://costpilot.example.com
Claude Code: updated /Users/you/.claude/settings.json
  telemetry endpoint: https://costpilot.example.com
  hook: UserPromptSubmit + Stop (turn end) → session-map @ https://costpilot.example.com
  auth: bearer token
  project: by repository (central config)
  Restart Claude Code for the change to take effect.

Your existing settings stay untouched, and running init again is safe. To set up only specific tools, pass --tool (repeatable):

costpilot-agent init --tool claude-code --tool codex --endpoint https://costpilot.example.com

Step 3: Restart your tools

Close and reopen Claude Code, Gemini CLI or Codex, and reload the Cursor window. The tools read their settings only at startup.

Step 4: Check the setup

costpilot-agent status

For each tool you set up, the global line should show telemetry: on (Cursor: n/a) and hook: installed.

Everyday commands

I want to…	Run
see what is set up	costpilot-agent status
verify that the project in ./ really reports	costpilot-agent check
pick up a change the admin just made	costpilot-agent sync, then restart your tools
set up all supported tools	costpilot-agent init --all
update the agent	run the install command from step 1 again
stop reporting on this machine	costpilot-agent remove --all
uninstall completely	costpilot-agent remove --all, then npm uninstall -g @costpilot/agent

You never run costpilot-agent hook yourself: that is what your tools call on every prompt.

Next: See your first session.