Docs / Getting started / Overview

Overview

Token Controller is cost accounting and management control for AI agents. Agents report token entries, rules place them on tickets and projects, and each period closes against the bill your provider actually sent. Token budgets on people, tickets and projects close the loop: plan, record, compare, correct. Every part is optional. This page explains the pieces and gets a first token entry placed.

Browse the docs

Getting started

Collect

Attribute

Account

Report

Self-hosting

Reference

I manage peopleCreate the organization, connect the bill, invite people, close the first period. I manage agentsInstall the Claude Code mod or the CLI, submit a first token sheet, 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 telemetry event per model call: cost, tokens, model, session, request and message IDs, person, organization, repository. No text.	The agent's own OpenTelemetry exporter, pointed at your organization's ingest URL. Nothing installed on laptops.
Token entries	One agent session: tokens, cost, model, time range, a one-line summary, and the postings to tickets or projects.	Automatic from cloud, CI and support agents, through the GitHub Action or the token entries endpoint. From a person's machine through the Claude Code mod or the CLI, handed in on a token sheet.
Bills	The provider's figure for one period: gross, discount, credit and net.	Anthropic and OpenAI admin APIs, a CSV upload, manual entry, or the bills endpoint.

Join keys. Telemetry and token entries share the session and message IDs. Token entries and bills share the period: the token entries of a period must add up to its bill. A token entry never needs telemetry to exist, and telemetry never needs a token entry to be counted. When both exist they are joined, never counted twice.

Quick start for people managers

About fifteen minutes, once. You need an admin login at Anthropic or OpenAI to connect the bill; everything else is inside Token Controller.

Create the organization.
Sign up at tokencontroller.com/signup. Pick your cost source, the way your provider charges you: an Enterprise plan at API rates, Team plan seats, Console, a cloud marketplace, or none yet. This decides what the close reconciles against, and the cost sheet will say so in plain words.
Connect the bill.
Under Bills, add an Anthropic Enterprise Analytics key or a Console admin key, or an OpenAI admin key. The first pull loads the current and previous period. No provider API? Upload the bill as CSV once per period.
Create your projects.
Label each project with its client, give it 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 their sizes sync every fifteen minutes. If you want the loop, give people, tickets or the project a token budget now, or accept a token forecast once there are past periods to learn from.
Invite people.
Members get a link. When they install the Claude Code mod or the CLI, their sessions turn into draft token entries and the rules you just wrote place them. For everyone on Claude Code at once, paste the telemetry block into managed settings and skip the laptops entirely. Optionally set a cadence, such as weekly; an agent manager whose token sheet is late gets a reminder.
Close the first period.
Once the period's bill is final, a controller opens Close. Some bills take weeks: Anthropic Enterprise figures are final about 30 days after the period ends. Check the unattributed line, reject anything wrong back to its agent manager with a reason, then close the period. With approval on, every token entry in the period has to be approved first. Export the cost sheet as CSV or hand finance the link.

Quick start for agent managers

Two commands. Token entries are drafted as you work and placed by your organization's rules. You review them and submit your token sheet when you say so. If a cadence is set, submit once per cadence period.

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 mod

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

The mod runs in the terminal and in the desktop Code tab. After every turn it records Claude Code's own usage, writes the one-line summary as the session goes, and places the draft token entry. A band above the prompt shows $212 spent · 91% attributed · KD-214. More on the Claude Code mod page.

Review and submit

tc review
  #  when    cost     placed on            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   ?                    unattributed, 2 candidates

tc place 5 KD-231
tc submit
submitted token sheet · 5 token entries · $212.40 · 100% attributed

Telemetry for everyone, 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 mod or the CLI. Organizations that only push telemetry get cost placed on projects, by repository; those that add the mod get tickets.

Concepts in one table

Term	Meaning
Organization	One customer of Token Controller: its people, teams, projects and periods. One account belongs to one organization. It sets an attribution target and whether approval is on.
Project	A body of work made of tickets, with a ticket key pattern and mapped repositories. A client is a label on a project; projects with the same client can be totalled.
Ticket	Any unit of work: a feature, a story, an epic or a bug. Synced from Jira Cloud, Azure DevOps or GitHub Issues, or created by hand. Tickets can sit inside other tickets and can carry a token budget.
Person	A human in the organization. A person belongs to one team at a time.
Team tree	The organization's people arranged as person, team, department, organization. Separate from projects, because one person can work on several projects but sits in one team.
Role	What someone can see; each role includes the one before it. An agent manager submits token sheets and sees their own cost. A people manager reads reports, sets token budgets and cadence, and approves or rejects token entries, for the teams or projects they are assigned. A controller sees everything, runs the close and posts adjustments.
Agent	Anything that calls a model and so costs money: a coding agent on a laptop, a CI automation such as a review bot, a support agent. Token Controller keeps no record of agents, only of the cost they cause. Each token entry names the agent harness, the model and an optional agent name.
Agent manager	Every token entry has exactly one, who answers for its cost. Your own sessions are yours; a CI automation belongs to whoever set it up. A token entry without an agent manager shows as an error until someone takes it.
Token entry	One agent session's account of what it spent and on what work: tokens, cost, model, time range and a one-line summary. Its status is draft, submitted, approved, rejected or locked.
Token sheet	One agent manager's token entries for one cadence period that were not reported automatically. Automatic token entries, from cloud, CI and support agents, are never on a token sheet.
Cadence	The rhythm in which token sheets are due, set by a people manager: weekly, every two weeks, monthly or custom. A token sheet not submitted when its cadence period is over is late, and its agent manager gets a reminder.
Cost center	Who answers for a cost. Every posting lands on one person, its agent manager, and rolls up through the team tree.
Cost object	The work a cost paid for: a ticket, a project or the organization. When no ticket matches, a posting falls back to the project, then to the organization.
Posting	The placement of a token entry, or a share of it, on one cost object with one cost kind: direct, project overhead, organization overhead, personal or unattributed.
Rule	An instruction that turns signals, such as a branch or a repository, into postings. Organization rules run before personal ones.
Token budget	Money a human has planned for a person, a ticket, a project or a period. Typed, or accepted from a token forecast. It is compared with actual cost and never stops spending.
Token forecast	Money Token Controller predicts for a ticket, a project or a period from past cost. It becomes a token budget only when a person accepts it.
Bill	A provider's figure for one period: gross, discount, credit and net. It is the total the token entries must add up to.
Period	One calendar month, open or closed. The close locks its token entries and postings and produces the cost sheet. An adjustment is a signed correction a controller posts to a closed period.
Cost sheet	The locked account of one closed period for the whole organization: cost per project and ticket, adding up to the bill. With approval on, it holds approved cost only.
Unattributed	Spend that no rule or person has placed yet. Always shown as its own line.
Residual	The part of a bill that no token entry explains, such as unmeasured seats, chat usage or a restated bill. Always shown as its own line.

How they fit together is on the Concepts page. The full list is in the glossary.

List value, billed value and money

Every token entry carries a list value: its cost at the provider's published prices, taken from the agent's reported cost or computed from token counts and the price table kept with the period. A billed value exists where a bill or billed telemetry says what was actually charged. Whether list value is money depends on your cost source:

Cost source	The close reconciles against	List value is
Enterprise plan, 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 plan or seat-based plans	Usage credits only; usage inside the seat is not metered in dollars	A share of the seat cost, and the cost sheet says so
Bedrock, Vertex, Foundry	The cloud's export, uploaded as CSV	Approximate