# Token cost fundamentals

What a coding agent costs to run and why: the few mechanics behind every token bill, from re-reading and caching to expiry and generation.

Source: https://ai-sw-factory.mellicci.dev/cost

**Diagram:** One reply, in the order its tokens arrive: the re-read context is usually the biggest part, and the cheapest per token.

- Re-read context — everything so far, mostly cache read (context growth)
- → plus
- Fresh input — the new part, read at full rate
- → plus
- Cache write — keeps the prefix for next time (cache lifetime)
- → plus
- Output — generated, one token at a time

This module teaches what a coding agent costs to run and why. Every reply re-reads the whole conversation, part of it comes from a cache, the cache expires, and the model generates new text one token at a time. Those four facts explain most of a token bill.

After this module you can look at a session and say where its tokens went, which habits made it expensive, and what to try first.

## What this module is and is not

It is generic mechanics that hold for any coding agent. Each tip on these pages follows from a mechanism you have just seen, and each names what you give up: cheaper can mean slower, lossier or riskier.

It is not a price list, a vendor comparison or a set of tricks without reasons. Exact rates come from your provider and change, so the pages teach orderings and rules of thumb. Cost is never the only goal; a cheap session that produces the wrong change is not a saving.

## The path through it

Ten concepts in three groups. Read them in order; each builds on the one before.

**Diagram:** The ten concepts in three groups, from what you pay for, through why it behaves as it does, to what you can change.

- Foundations:
  - 01 Tokens, turns and context
  - 02 Why tokens cost differently
- Mechanics:
  - 03 Prompt caching
  - 04 Cache lifetime
  - 05 Context growth
- Practice:
  - 06 Model and reasoning choice
  - 07 Prompts and exploration
  - 08 Automation at scale
  - 09 Measuring cost
  - 10 Your first cost experiment

- **Foundations** define what you pay for: tokens, turns and the context re-read on every call, and why the four kinds of token are priced differently.
- **Mechanics** explain why re-reading is cheap, what breaks it, how long it lasts, and why replies get dearer as a session grows.
- **Practice** turns the mechanics into choices: model, prompts, automation, measurement, and a first controlled experiment.

## The running example

Every page uses the same team as [Module 1](https://ai-sw-factory.mellicci.dev/fundamentals): the `ticket-service` team, four developers with a coding agent each. Their agent spend doubled last month and nobody can say why.

Each concept page diagnoses one driver in that team's work and shows a before and after in token counts, never money. The last page runs one controlled experiment on a real habit.

## See it in your own sessions

One way to make this whole module visible in your own sessions is [Agent Tokenwatch](https://github.com/mellicci/agent-tokenwatch), the author's open-source Node.js command-line tool (`npm install -g agent-tokenwatch`) for Claude Code, Codex CLI and GitHub Copilot CLI. It runs locally and records metadata only: token counts and structure, never prompts, code, transcripts, file paths or tool contents.

A status line in the agent shows the session's tokens and cache health (warm or cold). The `tw-*` skills cover the rest: a retrospective of the current session or a period, an interactive cost coach, a primer on cost drivers and an experiment designer. See also [the project page](https://mellicci.dev/work/agent-tokenwatch).

## Before you start

- Read the pages in order; the later ones assume the vocabulary of the earlier ones.
- Module 1's [How coding agents work](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work) explains the loop this module prices.
- Plan for about 10 minutes per concept.