Docs / Getting started / Overview

Overview

Token Controller keeps the books for AI agents. Agents hand in receipts, rules post them to clients, projects and tickets, and each month closes against the invoice your provider actually sent. This page explains the pieces and gets a first receipt posted.

Browse the docs

Getting started

Collect

Attribute

Account

Report

Self-hosting

Reference

I run a teamCreate the organization, connect the invoice, invite people, close the first month. I run the agentsInstall the plugin or the CLI, push a first receipt, forget it exists. I host it myselfOne Docker image, one Postgres. The same features as the hosted Team plan.

How the pieces fit

Three things flow into the ledger, and they share the same identifiers so they can be matched against each other.

Input	What it carries	Where it comes from
Telemetry	One event per API call: estimated cost, tokens, model, session, prompt, request and message IDs, user, organization, repository. No text.	The agent's own OpenTelemetry exporter, pointed at your organization's ingest URL. Nothing installed on laptops.
Receipts	One unit of work: tokens, value, time range, one-line summary, the branch and pull request, and the postings to tickets or projects.	The plugin or CLI on the developer's machine, the GitHub Action in CI, or any agent through the receipts API.
Statements	The provider's own billed figure for the period, with discounts and credits.	Anthropic and OpenAI admin APIs, a CSV upload, manual entry, or the statements API.

Join keys. Telemetry and receipts share the session and message IDs. Receipts and statements share person and day. A receipt never needs telemetry to exist, and telemetry never needs a receipt to be counted. When both exist, telemetry is the journal and the receipt is the posting.

Quick start for managers

About fifteen minutes, once. You need an owner login on your Anthropic or OpenAI organization to connect the statement; everything else is inside Token Controller.

Create the organization.
Sign up at tokencontroller.com/signup. Pick how you pay your provider: Enterprise at API rates, Team seats, Console, a cloud marketplace, or none yet. This decides what the close reconciles against, and the statement will say so in plain words.
Connect the statement.
Under Statements, add an Anthropic Enterprise Analytics key or a Console admin key, or an OpenAI admin key. The first pull loads the current and previous month. No provider API? Upload the invoice CSV once a month.
Create a project per client.
Give each project its ticket key pattern, for example ^KD-\d+, and map the repositories that belong to it. Connect Jira Cloud, Azure DevOps or GitHub Issues so tickets and estimates sync every fifteen minutes.
Invite people.
Members get a link. When they install the plugin or CLI, their sessions turn into receipts and the rules you just wrote post them. For a whole team on Claude Code, paste the telemetry block from step 5 of the engineers' guide into managed settings and skip the laptops entirely.
Close the first month.
On the first business day, open Close. Review the unattributed list, send anything wrong back to its developer with a reason, then lock. Export the statement as CSV or hand finance the link.

Quick start for engineers

Two commands. Receipts are drafted when a session ends, filed by your organization's rules, and pushed when you say so.

Install the CLI

# macOS and Linux
brew install tokencontroller/tap/tc

# Windows
winget install TokenController.tc

# connect to your organization with the invite link, or run local-only
tc connect https://tokencontroller.com/i/kestrel-4f2a
tc status
organization  Kestrel Digital       person  m.ortner@kestrel.example
agents        claude-code, codex    rules   5 organization, 2 personal
today         $212.40 spent         91% attributed

Add the Claude Code plugin

# inside Claude Code
/plugin marketplace add tokencontroller/claude-code
/plugin install token-controller

The plugin installs three hooks and a status line. At session start it records the working directory and branch; at session end it asks the agent for one line on what it did, drafts the receipt, and files it. The status line shows $212 spent · 91% attributed · KD-214.

Review and push

tc review
  #  when    value    posted to            by
  1  09:12   $41.87   KD-214 Checkout      rule: ticket key in branch
  2  11:46   $12.10   KD-214 Checkout      rule: ticket key in branch
  3  13:05   $88.30   KD-231 Search        rule: ticket key in PR title
  4  15:20    $9.75   Storefront (project) rule: repository
  5  16:41   $60.38   ?                    unplaced, 2 candidates

tc place 5 KD-231
tc push
pushed 5 receipts · $212.40 · 100% attributed today

Telemetry for a whole team, no install

Claude Code, Codex, Gemini CLI and Copilot CLI can push usage straight to your organization. For Claude Code, an administrator adds this to managed settings. It sends numbers and identifiers only; the ingest endpoint drops any event that carries prompt text.

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://ingest.tokencontroller.com",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer tc_org_…",
    "OTEL_METRICS_INCLUDE_REPOSITORY": "true"
  }
}

What telemetry cannot see. The branch, the pull request and the one-line summary. Those come from the plugin or CLI. Teams that only push telemetry get attribution by repository and person; teams that add the plugin get tickets.

Concepts in one table

Term	Meaning
Organization	The tenant and the billing unit. One account belongs to one organization. It has a plan type, an attribution target and members.
Project	A client or a product inside the organization, with tags, a ticket key pattern and mapped repositories. Optional.
Ticket	A unit of work inside a project, synced from Jira, Azure DevOps or GitHub Issues, or created by hand. May carry an estimate. Optional.
Receipt	Spend from one session or session segment, with tokens, value, summary, evidence and status: draft, pushed, rejected, posted, locked.
Posting	A receipt's assignment to a ticket, a project or the organization, with a share. A receipt can have several.
Rule	An ordered match on a signal, such as a branch pattern or a repository, and a target. Organization rules run before personal rules.
Statement	The provider's billed figure for a period: gross, discount, credit, net, currency, source, revision.
Period	One calendar month per organization. Closing locks receipts and statements. Adjustments after close are separate, signed entries.
Residual	The statement minus everything measured: discounts, unmeasured seats, chat usage, restatements. Always shown, never hidden.

Values, estimates and money

Every receipt carries a value at the provider's list price, computed from a price table pinned to the period. Whether that value is money depends on how you pay:

You pay	The close reconciles against	List value is
Enterprise, usage at API rates	The Enterprise Analytics cost report at list price; the discount is its own line	Money, before discount
Console or API key	The Usage and Cost report, per workspace and day	Money
Team or seat-based plans	Usage credits only; in-allowance usage is not metered in dollars	An allocation, and the statement says so
Bedrock, Vertex, Foundry	The cloud's export, uploaded as CSV	Approximate