11. AI usage

The Usage option of the view switcher in the top bar shows how the team works in the project. It helps you see where the team’s effort goes and improve it, not just measure it.

What each signal means

Talk on the side and Gate reviews are not added to the rest of the tab. Each gate review shows the date and time, the step, the reviewer role (or “Reviewer”), the agent and model, the tokens and the result (“2 ✓ · 1 ✗ · 0 ?”, or “no result” if it failed, timed out or was cancelled). Re-read files also count the files the agent reads with cat, sed or grep in a command. Save summary for the retrospective writes a document in docs/metrics/ with this data and the notable signals, since the last summary or with the whole record.

Background reviewers. If a turn launches a reviewer agent in the background (for example, a code review), its time is the wall-clock time until the reviewer finishes, not only what the agent reports, which does not count the reviewer’s work. Hovering over that time shows the hint “Includes {time} of background reviewer time.”; turns without a reviewer do not change. Background Bash tasks (such as a server) do not count. If you close the app before the reviewer finishes, that time is not added.

It is an indicator, not a bill. It only counts what was done from the app, and only your own work: the record is personal and is not shared through git.

A reading example

Illustrative example. The figures are made up to explain how to read the panel; yours will be different.

A Lyra sprint with one correction round (the test found a problem and the sprint went back to the interview). At the top, the panel shows Tokens 2.4 M (160 k new input · 130 k output), Turns 47, Rework 21% (10 turns that went back to an earlier step) and Context re-read 78%.

By role:

By flow step (the four with the highest spend):

By chat:

How to read it:

• Full Stack Developer, 54% in 22 turns: this is where most is spent, which is normal in a sprint that builds; if it grows from one sprint to the next, check whether the design arrived with gaps.
• Product Owner, 26% in 14 turns: interview, reviews and tests; part of those turns is the repeated test (see by step).
• UI/UX Designer, 11% in 5 turns: the design came out in a few turns and did not need redoing.
• Documentador, 9% in 6 turns: short work; nothing to improve here.
• Implementation, 46% and 1 return: the correction took a large share; check in the acceptance what caused it.
• User test, 1 return: the test was repeated; it is a candidate for the retrospective.
• Design specification, no returns: the correction did not touch the design.
• Interview, 1 return: the new round started with the interview about the problem, as the workflow asks.
• “Build” chat, context 88%: above 85%, each turn pays mostly for the history; next time, do the correction in a new chat.
• “Design” chat, context 52%: no problem.
• Rework 21%: close to the 25% warning; the returns of Implementation and User test explain it.

What to look at in the retrospective

• Which role spends most, and why? — By role. It is normal for whoever builds to spend most; for whoever coordinates, less so.
• Which steps did we go back to most often? — Rework and the returns in By flow step.
• Did any chat go above 85% of context re-read? — By chat. If it happens often, use one chat per phase (chapter 8).
• Were the same files re-read many times? — Re-read files. A context document or a summary can avoid it.
• What do the gate reviews cost? — Gate reviews. If they cost more than they bring, review the gate’s criteria (chapter 5).

Then press Save summary for the retrospective: it leaves this data and the notable signals in docs/metrics/, to have them at hand when you close the sprint.

By sprint, the closing table and Compare models

• Choosing a sprint. The Sprint bar, above the panel, picks Whole project or one sprint. With a sprint chosen, every card and tile counts only its turns, and the line “Sprint N · turns · tokens” appears. Talk on the side and Gate reviews do not depend on the sprint and say so. The sprint is taken from the chat name (“Sprint N - …”): chats without that name count only in “Whole project”.
• “Sprint usage” table in the closing. When you close the sprint, the app adds a section at the end of the closing document with one row per role and step, with its deliverable, and a total with turns, tokens, API equivalent and rework. If the sprint has no recorded data, the closing carries a one-line note instead. The table is written at closing: turns recorded later (pushing to git, end of sprint) are not included, unless you press Update usage in the close with that sprint chosen. That action replaces the section; it does not duplicate it.
• Cut-off line. With a sprint chosen that already has its table, the bar says up to when the closing includes usage, and how many turns were recorded after that. The table total matches the filter total at that moment.
• Summary for the retrospective. With a sprint chosen, Save summary for the retrospective writes the summary of that whole sprint to docs/metrics/, with the same total as the filter.
• Compare models. The card appears after “By model” and “By day”. Choose the step under Step; the drop-down shows how many models ran it. With two or more, it shows for each model the runs, turns, tokens, tokens per run, API equivalent and rework, without marking any as best. If the step has only one model, it says so and does not compare. The view does not start any run or create chats or documents: it only reads what is recorded. Turns with no model reported (for example, from Codex) are not compared, and the card says how many there are.

Sprints are not identical: use the comparison to see cost and effort, not to judge the quality of each model.

Waits and interventions

At the top of Usage there are two tabs: Tokens (everything above, the one that always opens) and Waits and interventions. The second shows how long the flow waited for your answer and how many times your judgement stepped in. The Sprint bar serves both and the choice is kept when you switch tabs; this tab does not show Update usage in the close or the cut-off line, which are about tokens.

• Tiles. Total wait (with the number of waits), Average wait (per wait), Approvals (gates and questions), Permissions (granted and denied) and Corrections (text written before approving).
• By step and role. One row per flow step and role, with the waits, the average and total wait, the approvals, the permissions (with “· N denied” if any) and the corrections, and a Total row. They follow the order of the flow; steps without waits or interventions are not shown.
• Gates that never sent the work back. The gates you approved without correcting anything and without sending the work to an earlier step, with how many times they were approved. If every one had some correction or send-back, it says so.

What counts:

It works the same with Claude Code and with Codex. Questions the agent writes in the chat text, without the question window, do not open a wait. The app also records, without showing them yet, the decisions the delegated role took (chapter 9). The record is personal: it goes in .team-ai-console/waits.jsonl, separate from the token record, and does not travel with git (the app adds it to that folder’s .gitignore). Sprints before 0.4.13 have no waits recorded.

Save summary for the retrospective adds the Waits and interventions section, after the signals: the same table and the list of gates without send-back, for the same period or sprint; without data, a line that says so.

Continuous improvement

Usage is the first step of a cycle that improves the team itself, sprint after sprint:

1. Retrospective. When you close a sprint, look at the panel with the questions above, together with what the sprint closing already recorded (rounds, pending items and decisions taken on your behalf).
2. Usage summary. Save summary for the retrospective leaves the sprint’s data and notable signals in docs/metrics/.
3. Proposals in Improvements. A role (or you) proposes a change to the team itself, for example a new rule in a role’s sheet; the proposals show in the project’s Improvements tab.
4. The catalog team. With Apply to the catalog team, the improvement reaches your own team in Teams and Roles and, through it, future projects.

The details of the proposals and of how they reach the catalog are in chapter 13 (Team improvements: from the retrospective to the catalog).