Contact

Type to explore Drawk studio productions

Discover cross-platform games, mobile apps, architecture articles, and interactive GLSL labs.

← Back to Posts

Thread Cost: Capture-Then-Clear Handoffs and Per-Turn Economics for AI Agent Threads

This article was updated on November 17, 2026 to reflect latest specifications and benchmarks. See revision history below.

TL;DR: Long AI coding conversations get expensive and sluggish because every single turn re-reads the entire conversation history. Across a measured ledger of 292 captures, prompt cache reads alone accounted for 49% of total spend, and turns running at 400K+ context averaged $0.114 per request compared to $0.052 under 100K. Instead of riding a bloated thread until quality degrades, encode a capture-then-clear workflow using deterministic stdlib Python hooks: track real per-turn cost from local harness transcripts, fire alerts at threshold checkpoints, capture a clean state handoff before prompt caches expire, and reset into a fresh ~50K-token thread.

Download the Latest Skill Kit: thread-cost.zip
MIT licensed • 10 self-contained files (SKILL.md, INSTALL.md, 7 stdlib Python 3.8+ scripts, model_prices.json) • 48,912 bytes
SHA-256: a2c6f3f69fc6f15b561a6c795897f8c3639fe65b1db5a6c657b443498d15f7f2
Download thread-cost.zip
flowchart TD subgraph BLOATED["THE LONG-THREAD COST TRAP (400K+ CONTEXT)"] B1["Session Grows Past 400K Tokens"] --> B2["Every Step Re-Reads Full History"] B2 --> B3["53% of Ledger Spend at ~$0.114 / Request"] B3 --> B4["Logs & Screenshots Bloat Subsequent Turns"] B4 --> B5["Context Hits Attention Degradation & Idle Cache Expiry"] end subgraph CAPTURE_CLEAR["CAPTURE-THEN-CLEAR LOOP (40K-100K CONTEXT)"] C1["Threshold Fires: +40K Growth / $15 / 300K / Boundary"] --> C2["Stop New Work: Write Structured Handoff"] C2 --> C3["Register One-Shot SessionStart Handoff Path"] C3 --> C4["Clear Thread or Open Fresh Conversation"] C4 --> C5["Starts Clean at 40K-60K (<$1 Write) & ~$0.052 / Request"] end
┌───────────────────────────────────────────────────────────────────────────┐
│                 LONG THREAD VS. CAPTURE-THEN-CLEAR ECONOMICS              │
├───────────────────────────────────────┬───────────────────────────────────┤
│   CONTINUOUS THREAD (400K+ PEAK)      │   CAPTURE-THEN-CLEAR (~50K RESET) │
├───────────────────────────────────────┼───────────────────────────────────┤
│ • Avg $0.114 per API request          │ • Avg $0.052 per request (<100K)  │
│ • 53% of total measured ledger spend  │ • Single cold write < $1.00       │
│ • Cache reads = 49% of total bill     │ • Starts clean at 40K-60K tokens  │
│ • Prompt cache expires cold on idle   │ • Pre-expiry idle wake stays warm │
│ • Past errors/logs distort judgment   │ • Handoff carries only crisp truth│
└───────────────────────────────────────┴───────────────────────────────────┘

Most teams blame expensive AI coding sessions on the wrong thing. They look at output verbosity or switch off their strongest reasoning model when the bill climbs.

In reality, cost grows with context length, not with work done. Because transformer inference is stateless on the server, every request sends the entire conversation prefix again. Even with server-side prompt caching enabled, re-reading hundreds of thousands of cached tokens dozens of times quickly dwarfs output token costs.

Once you measure real sessions from disk, two surprises jump out immediately:

  1. Cache reads dominate the invoice: Across our 292-capture measured ledger, prompt cache reads made up 49% of spend, 1-hour cache writes made up 23%, and model output tokens were only 13%.
  2. Keeping "warm" 400K+ sessions is a false economy: Captures whose peak context exceeded 400K tokens generated 53% of total spend, averaging $0.114 per request versus $0.052 per request under 100K. Starting a fresh conversation begins around 40K to 60K tokens with a one-time cache write costing well under $1, meaning clearing a bloated session pays for itself almost immediately instead of "wasting the cache".

The Thread Cost skill automates that discipline without asking the model to guess numbers. Deterministic standard-library Python scripts inspect your harness's own local transcripts, surface per-turn spend, respect each model's real prompt-cache TTL, and trigger a capture-then-clear cycle before a thread turns expensive or stale.


Core Architecture: Zero-Token Transcript Accounting

In line with our Zero-Token Architecture and Tiered Delegation standards, the model should never burn reasoning tokens trying to estimate context size or token pricing. Standalone Python 3.8+ scripts do the accounting offline from local transcripts with zero external packages and zero network calls (outside reading an optional local loopback IDE server on 127.0.0.1).

┌───────────────────────────────────────────────────────────────────────────┐
│                     THREAD COST SKILL KIT (10 FILES)                      │
├──────────────────────────────────┬────────────────────────────────────────┤
│  DOCUMENTATION                   │  STDLIB PYTHON 3.8+ RUNTIME (SCRIPTS/) │
├──────────────────────────────────┼────────────────────────────────────────┤
│  • SKILL.md (Rules & Knobs)      │  • thread_usage.py (Session parsers)   │
│  • INSTALL.md (Wire / Uninstall) │  • thread_cost_alert.py (Alerts/Check) │
│                                  │  • thread_idle_capture.py (Idle wake)  │
│  PER-USER CONFIG & STATE         │  • thread_handoff.py (Clear/Compact)   │
│  • ~/.config/thread-cost/        │  • thread_hook_antigravity.py          │
│    config.env (%APPDATA% on Win) │  • thread_hooks_common.py              │
│  • ${XDG_STATE_HOME:-~/.local/   │  • thread_hooks_install.py             │
│    state}/thread-hooks           │  • model_prices.json (Anthropic/OpenAI/│
│    (%LOCALAPPDATA% on Win)       │    Gemini pricing + cache_ttl_min)     │
└──────────────────────────────────┴────────────────────────────────────────┘

All hook state lives outside your git repositories in per-user state directories, and every hook fails silently (prints nothing, exits 0) on error so instrumentation can never interrupt your coding flow.


Per-Model Prompt Cache Lifetimes (TTL Reality)

One subtle trap discovered when measuring real multi-provider sessions is that prompt-cache lifetimes belong to the model, not the harness:

  • Claude models: Prompt caches hold for roughly 60 minutes of inactivity. Wait 50 minutes (while the cache is still warm) to run an idle capture, and the summary reads cleanly at warm cache rates. Wait past 60 minutes, and the entire history pays a cold write.
  • Gemini models: Implicit prompt caching documents no fixed SLA, so we measured it directly across real conversations by bucketing cache-read share (cache_read / prompt) against elapsed time since the prior request. Every gap up to 9.4 minutes returned warm (0.94 to 0.99 cache-read ratio), while every gap from 26.7 minutes onward returned completely cold (0.00). Switching models within the same thread also resets cold (0.00 after just 2.8 minutes when stepping from one Gemini model variant to another) because caches are keyed per model.

Because of that measurement, model_prices.json attaches a per-model cache_ttl_min field (60 for Claude, 10 for Gemini). When you resume a session over 100K context past its active model's cache lifetime, the script notifies the agent that the prompt cache has lapsed so you can capture a handoff and clear rather than paying a cold re-write on stale noise.


Interactive Drop-In SKILL.md Specification

Every generic skill in our catalog is distributed as a self-contained folder with SKILL.md, INSTALL.md, and stdlib Python scripts. Below is the exact SKILL.md included inside thread-cost.zip:

---
name: thread-cost
description: Use to keep agent threads cheap -- when a hook reports the last turn's cost, a $5 cost alert, a "capture now" block or an idle wake; at an iteration boundary (a PR opens or merges, before a long wait); when a thread feels long or expensive; or when asked what a thread cost. Shows per-turn and per-thread cost estimates from the harness's own transcript, alerts in steps, and at a cost or context threshold has the model write a handoff so the user can clear the thread and continue from it. Covers the capture-then-clear rule, the status command for harnesses without hooks, every threshold knob, and installing the hooks on Claude Code and Antigravity.
---

# Thread cost: capture, then clear

Cost grows with context, not with work. Every request re-reads the whole conversation, so a
long thread pays for its past on every step. In one measured ledger (292 captures), cache reads
were 49% of spend, 1h cache writes 23% and output 13%. Captures whose peak context was 400K+
were 53% of spend, at $0.114 a request against $0.052 under 100K. A fresh thread starts at
40-60K and its one cache write costs well under $1, so clearing never "wastes the cache".

`<skill>` below is the folder holding this file; the scripts are in `<skill>/scripts/`. They are
stdlib `python3` (3.8+), read-only towards the harness, and never touch the network except the
optional Antigravity local server on 127.0.0.1.

## The rule

- **Bounce at iteration boundaries.** When a PR opens or merges, or before a long wait (CI, a
  device, a build over an hour), write the handoff (the capture step below), then clear and
  continue from it.
- **Delegate screenshot- and log-heavy work** (device passes, big logs, many screenshots) to a
  subagent that returns a verdict. Anything read in the main thread is paid again on every later
  request.
- **Clear vs compact.** `/clear` (or a new conversation) when the handoff holds everything.
  `/compact` only when a clear would lose uncaptured state: a background agent or CI watch still
  running, an uncommitted worktree, an answer still owed. The model cannot run either; it names
  the one to run and, for `/compact`, why.
- **When a hook says capture:** start no new feature work, do the capture step, make no
  outward-facing writes (no PRs, store, ticket or chat posts), and end with the one line the
  instruction asks for. Re-ask any question that is still open.
- **The cost line:** when the prompt hook supplies last turn's cost, end the reply with it as one
  italic line, as given.

The **capture step** defaults to: write a handoff where the project keeps its notes (what is done,
current state, decisions, open questions, next steps) so a fresh thread can continue from it
alone, and commit it if it lives in a repo. A setup with its own notes system replaces the step
with `thread_capture_step` or `thread_capture_step_file` (see Config).

## What fires

| Trigger | Script | Does |
|---|---|---|
| Every prompt | `thread_cost_alert.py` | Gives the model the previous turn's cost to end the reply with: `_Last turn ~$0.81 (10 requests, opus; 1.2M in / 4K out), context ~76K, thread ~$1.31 (est.)_` (model mix costliest first; tokens in include cache reads). A session's first turn shows on screen at Stop as `First turn ~$...`. Off with `thread_turn_cost_line=0`. |
| Every $5 | `thread_cost_alert.py` | Alert on screen at Stop and to the model at the next prompt. |
| Live context 200K | `thread_cost_alert.py` | One on-screen note at Stop. |
| $15 (then every $15), or live context 300K (then every 100K) | `thread_cost_alert.py` | Blocks the stop once with the capture instruction. Context levels re-arm after a compact. |
| Live context 40K past the session's own start (then every 40K) | `thread_cost_alert.py` | Same capture block, keeping threads small. The baseline is the first main-thread request since the last compact. Also tells the model to record the handoff with `thread_handoff.py set`. Skipped for subagents. Needs a readable transcript (Claude Code). |
| SessionStart after `clear` or `compact` | `thread_handoff.py` | If a handoff was recorded for this cwd in the last 6h and not yet used, tells the new session to read it first. One-shot. |
| Resume past the model's cache lifetime (60 min Claude, 10 min Gemini) on a context over 100K | `thread_cost_alert.py` | The prompt cache has lapsed; the model says so in one line and suggests the handoff and a clear at a boundary. |
| 50 min with no user input (cost >= $1, context >= 60K) | `thread_idle_capture.py` | Wakes the thread once (Claude Code `asyncRewake`) to run the same capture, inside the 1h cache window so the capture reads warm. |

Cost is an API list-price estimate (`scripts/model_prices.json`, Anthropic, OpenAI and Gemini
models, with dated `changes` for intro prices). A subscription bills differently; read it as
relative size. Update the table when prices change (`as_of`).

## Harnesses

| Harness | Cost line, alerts, capture block | Idle wake, resume after clear |
|---|---|---|
| Claude Code | automatic: hooks in `settings.json` | automatic (`asyncRewake`, SessionStart) |
| Antigravity | automatic once a conversation has token data: PreInvocation and Stop hooks through `thread_hook_antigravity.py` (the capture block re-enters the loop once; a new conversation replaces `/clear`, and every message and capture ending says so, with no SessionStart resume step). Token data needs Antigravity's local server running. | no: hooks are synchronous and there is no clear/compact event |
| opencode, Codex, Cursor, a bare terminal | manual: run `status` at iteration boundaries | no |

`status` works in every harness and auto-detects the current session (Claude Code, opencode,
Codex, Antigravity):

```sh
python3 <skill>/scripts/thread_cost_alert.py status      # one line, then OK or CAPTURE NOW: ...
```

Other read-only checks:

```sh
python3 <skill>/scripts/thread_cost_alert.py check --session <id>    # what would fire
python3 <skill>/scripts/thread_cost_alert.py replay --session <id>   # where growth capture fires
python3 <skill>/scripts/thread_idle_capture.py check --session <id>
python3 <skill>/scripts/thread_usage.py report [--session <id>] [--json]   # time, tokens, cost
```

Install and uninstall: `INSTALL.md` beside this file (`scripts/thread_hooks_install.py`).

## Config

Every knob is a flag, an environment variable and a key in the skill's own `KEY=value` file:
`$THREAD_COST_CONFIG`, else `%APPDATA%\thread-cost\config.env` on Windows, else
`${XDG_CONFIG_HOME:-~/.config}/thread-cost/config.env`. Environment wins, then the file, then the
default. No file is needed. The script docstrings (`--help`) list every knob; the common ones:

| Key | Default | Meaning |
|---|---|---|
| `thread_cost_alert_usd` / `thread_cost_alert_step_usd` | 5 / 5 | first alert, then every step |
| `thread_cost_capture_usd` / `thread_cost_capture_step_usd` | 15 / 15 | cost capture |
| `thread_ctx_capture_k` / `thread_ctx_step_k` | 300 / 100 | context capture (K tokens) |
| `thread_ctx_growth_k` | 40 | growth capture over the session start; 0 = off |
| `thread_idle_capture_min` | 50 | idle wake; keep it under the 1h cache TTL |
| `thread_cache_ttl_min` | per model | prompt-cache lifetime for the idle-gap note and the context warning; unset = the last model's `cache_ttl_min` in `model_prices.json` (60 for Claude; 10 for Gemini, whose implicit cache has no documented TTL and measured warm at 9 min, cold at 27) |
| `thread_turn_cost_line` | 1 | 0 = no per-turn cost line |
| `thread_capture_step` / `thread_capture_step_file` | built in | the capture step, as one line or a text file |
| `thread_hooks_state_dir` | per-user state dir | hook state (`%LOCALAPPDATA%\thread-hooks`, else `${XDG_STATE_HOME:-~/.local/state}/thread-hooks`) |
| `thread_usage_ledger_dir` / `thread_usage_docs_root` | state dir / git top level | `thread_usage.py snapshot` ledger and doc root |

State lives outside every repo. Any hook failure prints nothing and exits 0, so a hook can never
break a turn.

## Add-ons

A setup with its own capture workflow may keep `addons/<name>.addon.md` beside this file,
recording only its delta (usually the capture step and where its scripts sit). Read this file
first, then the add-on; the add-on wins on conflict.

Sample Flow: Handoff Capture & Clean-Slate Resume

Here is how the hooks collaborate across a live coding session from initial budget threshold to clean resume:

sequenceDiagram autonumber actor Dev as Developer participant Agent as Coding Agent participant Alert as thread_cost_alert.py participant Handoff as thread_handoff.py Dev->>Agent: Continues feature implementation (context grows +40K past start) Agent-->>Alert: Turn Stop hook evaluates transcript tokens & cost Alert-->>Agent: Blocks Stop once: "CAPTURE NOW - write handoff, make no outward writes" Agent->>Handoff: Writes handoff doc & calls thread_handoff.py set <path> Agent-->>Dev: Summarizes captured handoff & asks user to clear / open fresh thread Dev->>Agent: Runs /clear (or starts new conversation) Agent->>Handoff: SessionStart hook checks recent handoff (<6h, unused) Handoff-->>Agent: Injects one-shot pointer to read handoff first Agent-->>Dev: Resumes immediately at ~50K context & <$1 cache write

Installation, Portability & Safe Defaults

The installer follows strict read-only-by-default rules: running it with no flags only audits your environment. Passing --write creates backups first and wires hooks safely, while --uninstall --write reverses every edit cleanly.

  1. Unzip into your harness skills directory (for example ~/.claude/skills/thread-cost, <repo>/.claude/skills/thread-cost, or ~/.agents/skills/thread-cost):
    unzip thread-cost.zip -d ~/.claude/skills/
    
  2. Audit first, then wire hooks (Claude Code settings.json and Antigravity config/hooks.json when present):
    python3 ~/.claude/skills/thread-cost/scripts/thread_hooks_install.py          # dry-run report
    python3 ~/.claude/skills/thread-cost/scripts/thread_hooks_install.py --write  # backs up first, then adds hooks
    
  3. Verify live transcript detection:
    python3 ~/.claude/skills/thread-cost/scripts/thread_cost_alert.py status
    

For harnesses without native hook events (opencode, Codex CLI, Cursor, Windsurf, or terminal agents), drop a short snippet into your AGENTS.md instructing the agent to run python3 <skill>/scripts/thread_cost_alert.py status at iteration boundaries (when a PR opens/merges, before long waits, or roughly every 40K of new context) and execute the capture step whenever it prints CAPTURE NOW.

To customize where your team saves handoffs without forking the skill itself, point thread_capture_step_file in ~/.config/thread-cost/config.env (%APPDATA%\thread-cost\config.env on Windows) to your repo's capture instructions, or place an addons/<name>.addon.md beside SKILL.md. On Windows, swap python3 for py.


Comparison: Unchecked Long Sessions vs. Thread Cost Capture-Then-Clear

Dimension Unchecked Long Thread Thread Cost (capture-then-clear)
Request Cost (Ledger Avg) $0.114 per request at 400K+ context $0.052 per request under 100K context
Spend Distribution 53% concentrated in 400K+ tail turns Reset keeps work in the cheap 40K - 100K band
Idle Cache Risk Whole bloated prefix pays cold write on wake Pre-expiry asyncRewake (Claude) or TTL note avoids blind misses
Token Overhead Re-reads stale logs and screenshots every step Subagent verdicts + crisp handoff strip dead weight
Portability Locked to manual mental vigilance Zero-dependency stdlib Python 3.8+ (macOS, Linux, Windows)
Uninstall / Privacy N/A Clean --uninstall --write, per-user state outside repos, zero network telemetry

Conclusion

Long AI conversations create an illusion of momentum while silently compounding your API cost on every single keystroke. Because cached prompt reads make up nearly half of total spend and peak-context turns consume over half your budget, the fastest way to buy more runway is to stop dragging old context behind you.

Install thread-cost.zip, let deterministic local scripts watch the transcript ledger and cache clocks for you, and bounce cleanly to fresh threads at natural boundaries.


References, Standards & Verified Data

  • 292-Capture Production Spend Ledger: Empirical studio audit measuring API spend breakdown across multi-turn coding threads - prompt cache reads represented 49% of spend, 1-hour cache writes 23%, and model output tokens 13%. Sessions reaching 400K+ peak context accounted for 53% of total expenditure at an average of $0.114 per request vs. $0.052 per request under 100K tokens.
  • Per-Model Cache TTL Measurements: Empirical request-gap audit bucketing cache_read / prompt across real Antigravity sessions: Gemini implicit caching tested warm (0.94 to 0.99) up to 9.4 minutes idle and cold (0.00) from 26.7 minutes onward, as well as cold (0.00) across a 2.8-minute model switch. Claude prompt caches track a 60-minute window (thread_idle_capture.py fires at 50 minutes to capture warm).
  • Context Degradation in Long Windows: Nelson F. Liu et al., "Lost in the Middle: How Language Models Use Long Contexts" (Transactions of the Association for Computational Linguistics, 2024) - Demonstrates accuracy degradation as relevant information shifts across extended prompt contexts.
  • Quadratic Self-Attention Scaling: Ashish Vaswani et al., "Attention Is All You Need" (NeurIPS 2017) - Explains why carrying 400K+ tokens of historical tool logs creates latency, attention dilution, and token tax on every subsequent turn.
  • XDG Base Directory & Windows Per-User Paths: Cross-platform configuration and state isolation via XDG_CONFIG_HOME / XDG_STATE_HOME on POSIX systems and %APPDATA% / %LOCALAPPDATA% on Windows, keeping runtime hook state completely outside version-controlled repositories.

← Back to All Posts