---
title: Understanding Token Costs
description: >-
  What determines cost, how to check what you actually spent, and a command to
  estimate in advance
seo:
  image: /ogp.png
---
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

1. **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.

2. **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](/skills/backlog/implement).

3. **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.

4. **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`.

:::warning[Treat estimate ranges as wide]
The coefficients used for estimation are initial values that have not been calibrated against real measurements. The high and low bounds can differ by roughly 3×.
After running several times and accumulating actuals in `work/token-usage.json`, estimates will be corrected using those measured values.
:::

:::note[If you are using a subscription plan]
`estimate-token-cost` adjusts its output format based on your billing method.
For API/Console pay-as-you-go usage it reports in USD; for Claude subscription plans it reports token consumption and explicitly notes that the cost draws from your usage limit rather than incurring a dollar charge.
:::

## 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](/concepts/resume))