Agent CLI

costpilot-agent is installed globally on developer machines; see Connect your tools.

Command	Purpose
init [--tool ID ...|--all] [--endpoint URL] [--token SECRET] [--project-key KEY] [--global|--project]	Wire telemetry and the hook. --tool is one of claude-code, gemini, codex, cursor (repeatable); default is every centrally enabled tool with a config dir in ~ (every such tool without central config; Claude Code if none is found). --global (default) writes the user-level config, --project the one in ./. Without --endpoint, keeps the endpoint configured in the same scope or falls back to http://localhost:8787; a first init --project therefore needs --endpoint. --token is the server's COSTPILOT_INGEST_TOKEN; without it, a configured token is kept. --project-key pins the hook to one Costpilot project instead of mapping by repository; kept the same way.
sync [--global|--project] [--endpoint URL] [--token SECRET]	Apply the central agent config to that scope now: enabled and installed tools are (re-)initialised, disabled ones removed. The hook does this on its own for the global scope; use sync --project for project-level setups. Endpoint and token default to what the scope is configured with.
remove [--tool ID ...|--all] [--global|--project]	Undo init in that scope: strips the telemetry config and the hook, leaves everything else in the settings files untouched. Use remove --global when switching to a per-project setup.
status	Show telemetry, endpoint, auth, hook and project pinning per tool and scope.
check [--tool ID ...|--all]	Verify that the project in ./ reports: binary on the PATH, config scope in effect, branch → issue id and project, a test request against the server, and the receipt of the tool's last hook run. Exits 1 when something is broken.
hook --tool ID [--event stop] [--endpoint URL] [--token SECRET] [--project-key KEY]	The hook itself. Called by the tool, not by you: once per prompt and, with --event stop, once when the turn ends. Without --endpoint/--token it falls back to OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_HEADERS, then http://localhost:8787. Leaves a receipt of each prompt run in ~/.costpilot/hook-runs/ for check.

Local files the agent writes

Path	Contents
~/.costpilot/agent-config.json	Cached central config (5 minutes) and the setup last applied to the global scope, per endpoint
~/.costpilot/hook-runs/	One receipt per tool and project: time, session, branch, issue, project key, endpoint, HTTP status or error, and whether the telemetry variables were set. Never the token

Developing the agent

git clone git@github.com:getcostpilot/agent.git
cd agent
npm install            # dev dependencies only
npm test               # node --test
npm run typecheck      # tsc over the JSDoc-typed sources
npm link               # puts costpilot-agent on the PATH, pointing at this checkout

The package has no runtime dependencies. One adapter per tool lives in src/providers/; adding a tool means adding one adapter file and listing it in src/providers/index.js.