Concepts
Token Controller is cost accounting for AI agents, with management control on top. This page explains the ideas the rest of the docs build on. Every term is defined in the glossary.
Browse the docs
Getting started
Attribute
Account
Reference
Two sides that must match
As in double-entry bookkeeping, there are two sides, and they must add up to the same total.
| Side | What it is |
|---|---|
| Token entries | Every agent session produces one: tokens, cost, model, agent harness, time range, a one-line summary, and the ticket or project it was for. Token Controller collects these. |
| Bills | Your providers send one figure per period for the whole organization, with every client and project mixed together. |
Once the token entries add up to the bill, the bill can be split down to the work that caused it.
Some token entries arrive automatically: cloud agents, CI agents, a support agent that answers email. Usage that exists only on a person's machine is handed in on a token sheet, the way hours go on a timesheet.
Every cost is booked twice
A timesheet books hours both to a person and to a ticket. Token Controller does the same with cost.
| Booked to | Answers | How it is built |
|---|---|---|
| Cost center | Who answers for it? | Every token entry has exactly one agent manager. You are the agent manager of your own sessions. A tech lead is the agent manager of the CI automations they set up. People sit in the team tree: person, team, department, organization. Every node of that tree is a cost center. |
| Cost object | What did it pay for? | A ticket, a project or the organization. Tickets can sit inside other tickets, so a project's cost is the sum of its tickets. A client is a label on a project; projects with the same client can be totalled. |
The two trees are separate on purpose. A developer can work on three projects for three project managers but sits in one team. Tech leads and heads of department read cost through the team tree. Project managers, directors of delivery and account managers read it through tickets, projects and clients, whoever caused it.
When no ticket matches, a posting falls back to the project, then to the organization. A token entry without an agent manager shows as an error to people managers until someone takes it.
Agents
An agent is anything that calls a model and so costs money. Token Controller keeps no record of agents, only of the cost they cause. Each token entry names the agent harness (Claude Code, Codex), the model, and an optional agent name, a label such as "review bot" so the same automation on several projects can be totalled.
Cost kinds
Every posting carries one cost kind.
| Cost kind | Meaning |
|---|---|
| Direct | Placed on a ticket. |
| Project overhead | Project work that belongs to no single ticket, such as research, discovery or setup. |
| Organization overhead | Work that belongs to no project, such as dependency updates or internal tooling, when nobody made a ticket for it. |
| Personal | A person's own learning and experiments. |
| Unattributed | Spend that no rule or person has placed yet. Always shown as its own line. |
Every token, accounted for
All of the bill is always accounted for. Whatever is not placed shows as unattributed, and whatever no token entry explains shows as residual. Neither is ever hidden.
Attribution is the share placed on tickets and projects. Expect 70 to 80 percent at first, improving month by month. Each organization sets its attribution target; the default is 80 percent.
Every figure says what it is: billed, a list-price estimate, or an unknown model.
The loop
On top of the accounting sits the classic budgeting loop: plan, record, compare, correct.
- Plan.
A token budget on a person (for example 1,500 EUR a month), a ticket, a project or a period. You type it, or accept a token forecast: what Token Controller predicts from what similar work cost before, with the ticket system's size figure as one input.
- Record.
Token entries come in and rules place them.
- Compare.
Actual against token budget, per person, ticket and project, broken down to tickets.
- Correct.
Overruns and underruns both get a look. An overrun may be a problem. An underrun may mean someone can teach the others, or that the next token forecast should be lower. History feeds the next token forecast, so a new client project can be quoted from what similar work cost before.
Every part of the loop is optional. You can use Token Controller only to collect token entries and match them to the bill, and add token budgets later. A token budget never stops spending; there are no spend alerts and no spend caps.
Where Token Controller ends
Token Controller ends at the cost sheet: the locked account of one closed period. Charging a client for what is on it (pass-through) happens in your own invoicing tool.
Any provider, any agent
Bills come from several kinds of cost source: subscriptions, seats, usage at API rates, API keys, cloud marketplaces (Bedrock, Vertex, Foundry) and tools that resell model usage. Token Controller treats them all the same way.
Coding agents came first because their session files sit on the developer's machine. Any agent that can report home works, including remote and support agents.
Local first
The CLI is fully useful with no service connected, including an export for reporting by hand in a spreadsheet. The local tool and the service talk over a documented protocol, so the local tool can connect to any compatible service, or none. Transcripts never leave the machine.