Central configuration

Locally the agent only needs the server's endpoint and token. Everything else is configured in the Admin Area of the dashboard (/admin) and served to the agent from GET <endpoint>/v1/agent-config, which the ingestion token covers because the agent has no dashboard login.

Setting (Admin Area)	Effect on the developer machine
Agent → Coding tools	Which tools get telemetry and the hook. A tool that is switched off loses its costpilot config.
Agent → Log tool details	Claude Code's `OTEL_LOG_TOOL_DETAILS` (tool and MCP server names).
Agent → Default issue key pattern	Regex matched against the branch name wherever no project pattern applies: a project without one, or a repository that belongs to no project. Ships with the pattern built into the agent (`PROJ-123`, `US-02.001`).
Projects → Repositories	A session in one of these repositories (`owner/name` from the `origin` remote, case-insensitive) belongs to the project: `project_key` is reported and the project's issue key pattern is used, if it has one.
Projects → Issue key pattern	Optional regex matched against the branch name, e.g. `PLAT-\d+`. Left empty, the default issue key pattern applies and the project is identified by its repositories only.

The dashboard side of projects (how cost is grouped) is described in Projects.

How changes reach the machines

Projects and the default issue key pattern are read by the hook on every prompt. The answer is cached in ~/.costpilot/agent-config.json for 5 minutes (the request itself times out after 1 second), so a change applies within that time without anyone doing anything.
Tools and tool details end up in the tools' settings files. On the next prompt the hook compares the setup with the one it applied last and, if an admin changed it, re-applies it to the global settings, exactly as init would. This only happens when a global settings file already reports to this server. The tools read their settings at startup, so the change takes effect with their next restart.
Project-level settings (init --project) are never rewritten automatically: they usually live in the repository and would show up as local changes. Run costpilot-agent sync --project there instead. The global scope is also left alone when it reports to a different server.
After an agent upgrade that writes more than the version before (the turn-end hook, for instance), the hook re-applies the setup to the global settings once. Project-level setups need init or sync --project again; check points it out.
costpilot-agent sync applies the current config right away, without waiting for the cache.

Offline behaviour

When the server cannot be reached the last cached config is used. Without one (first run offline, or a server without /v1/agent-config) the hook falls back to the built-in issue pattern and init to its defaults. If an admin switches off every tool, the hook removes itself; re-enabling tools later then needs a manual init on each machine.

Payload

{
  "setup": { "tools": ["claude-code", "codex"], "logToolDetails": true },
  "projects": [
    { "projectKey": "PLAT", "name": "Platform Core", "issueKeyPattern": "PLAT-\\d+", "repositories": ["acme/api"] },
    { "projectKey": "OPS", "name": "Operations", "issueKeyPattern": "", "repositories": ["acme/infra"] }
  ],
  "defaultIssueKeyPattern": "[A-Z][A-Z0-9]+-\\d+(?:\\.\\d+)*",
  "turnEndReports": true
}

The pattern is optional, the issueKeyPattern field is not: an empty string marks a project without a pattern of its own. turnEndReports: true tells the agent that this server handles turn-end reports; agents only send them when told so, because an older server would take one for another prompt. GET /v1/projects/:projectKey returns a single project in the same shape.

How changes reach the machines​

Offline behaviour​

Payload​

How changes reach the machines

Offline behaviour

Payload