Understanding Token Costs

What determines cost, how to check what you actually spent, and a command to estimate in advance

NexusArchitect runs many sub-agents in a single command. Naturally, you may wonder “how much will this cost?” — but no concrete dollar figures can be given here. Costs vary significantly depending on codebase size, profile selection, and cache hit rate.

Instead, this page explains the factors that drive cost and how to measure them in your own environment.

What determines cost

Number of phases executed (profile)

This is the biggest lever. mvp runs 3 phases; full runs 23 — so the difference scales roughly at that ratio. Start with mvp, then expand scope only when needed to keep costs down.

Which models run (model tiering)

The system is designed to use the cheapest model capable of each task. Work that only reads and summarizes files uses haiku; structured generation uses sonnet; opus is reserved for tasks requiring judgment (mini-plan authoring and Epic consistency checks). A full assignment table is on the implement-backlog page.

Codebase size

The architect side reads existing code, so line count maps directly to input tokens. That said, it does not read every line — it uses structural inspection tools and sampling to read only a subset.

Prompt cache hit rate

Input tokens served from cache are billed at 0.1× the normal rate. Continuous work within the same context gets cheaper over time; large mid-session rebuilds increase cost.

Viewing actual costs

The plugin ships with a built-in hook that records token usage automatically. No configuration is required — simply running the plugin accumulates records in work/token-usage.json and work/token-usage.jsonl.

/architect:report-token-cost --once

This displays total cost, per-phase cost, and per-model cost, broken down by input / output / cache read / cache write. Daily trends and per-session costs are also available. These are measured actuals, not estimates.

Estimating in advance

To estimate work you have not run yet, use the following command.

/architect:estimate-token-cost <target-path>

It approximates token volume from line counts, prices each phase using the model tier assignments, and reports three ranges: typical / low / high. Results are written to reports/05_estimate/token-cost-estimate.md.

Ways to reduce cost

Run incrementally — rather than running full from the start, use mvp to get as far as it can take you before deciding whether to go further
Narrow the scope — use --out and explicit target paths to limit how much code is read
Preserve context — continuing work within the same session context improves prompt cache hit rate
Be deliberate about stopping points — progress is preserved if you stop mid-run, so splitting work across sessions does not increase re-execution cost (interruption and resume)