Token usage?

[sumitgupto]

Would anybody know the token usage pattern vis a vis the repo size? and the incremental token usage as and when code is changed/graph updated?

[Lum1104]

Good question — we don't ship per-run token telemetry yet, but the pipeline's shape makes the cost predictable.

Full run (/understand) cost is dominated by Phase 2 (file-analyzer). Files are batched ~25 per subagent, up to 5 in parallel. Cost scales roughly linearly with total lines of source code analyzed, since every file's contents are read once. Anything beyond ~100 files hits a gate that asks you to scope with a subdirectory — that's the practical sweet spot today.

On top of that there's a fixed overhead per run from 4–5 review/assembly agents (scanner, assemble-reviewer, architecture, tour, optional --review reviewer). Their cost depends on the final graph size (#nodes + #edges), not file count. The default reviewer is a deterministic Node script and costs zero tokens — you only pay for the LLM reviewer if you pass --review.

Incremental updates (when the commit hash changes):

• Phase 2 only re-runs on files in git diff <last>..HEAD — so the file-analysis cost is proportional to the diff, not the repo.
• BUT Phases 3–5 (assemble-review, architecture, tour) always re-run on the full merged graph, because layer/tour assignments can shift when files change. So there's a floor cost per incremental update, proportional to total graph size — not zero.

Practical advice:

• Use /cost in Claude Code after a representative run to see actuals for your specific repo.
• For very large repos, run /understand <subdir> per area instead of the whole tree — the merge tooling already supports combining subdomain graphs.
• Per-run telemetry is a reasonable feature ask — happy to take a PR or expand this into an issue if it'd help you budget.

[xerudro]

I tested it yesteday on a project written in go, unfinished yet, and after the first few batches finished, like first 5, only for the go files, it consumed almost 3$ and i think it scanned only 3-4% of the whole project, so it is not less token optimized.

[ja-kjub]

"For very large repos, run /understand per area instead of the whole tree — the merge tooling already supports combining subdomain graphs."

On a big project we can't relocate files into a directory, and key files are scatered across tree. Can we feed a /understand list.md or something that holds the information about the files to be considered for --review ?