session-watcher

Session Watcher

LLM context economics, in your terminal.

Session Watcher treats your prompt cache as inventory — it uses EOQ theory to measure whether the current context is still worth carrying, tracking restart pressure so you can decide when to hand off.

Documentation ·

npm ·

Paper ·

llms.txt

Quick Start ·

Install ·

DSH ·

How It Works ·

Context Buckets ·

Handoff ·

MCP Tools ·

Agents ·

Cite

---

What it does

Session Watcher reads your Claude Code transcript in real time and answers one question: is this session still worth carrying?

Most context tools optimize how you consume tokens — Headroom compresses, /compact shrinks, RTK filters. Session Watcher tracks when the cost curve is drifting, giving you the data to decide. They compose: run any pruning strategy you like, SW measures the cost curve so you can decide when to hand off.

SW reads from the transcript, never writes to it. The dashboard and statusline are pure observers; MCP tools return data for you to act on.

How it works

Your coding agent (Claude Code)
        │  writes session transcript
        ▼
┌───────────────────────────────────────────────────────┐
│  Session Watcher (in-process MCP server)              │
│  ───────────────────────────────────────────────────  │
│  harness/claude-code  — read rows, emit observations  │
│  measurement/engine   — B (context belief), epochs    │
│  session-watcher      — apply frames, run operations  │
│  rate-lamp            — rent ledger + wallet clock    │
│  server.js            — Express + SSE dashboard       │
│  statusline           — one-line shell client         │
└───────────────────────────────────────────────────────┘
        │  dashboard  ·  statusline  ·  MCP
        ▼
   Your browser / terminal status bar

The harness layer is the only part that knows Claude Code: it reads transcript rows, decides the active branch, and emits normalized observations. Everything below it — measurement, dialogue history, handoff — consumes those observations and carries no transcript format, no row shape, and no tool name of any particular agent.

Core model: L = cache_read_input_tokens — the context stock you are renting. B is the rebuild baseline: the session's overhead floor plus the tokens of every file, skill and tool it has pulled in, which is what a restart would have to re-read. g is the growth no path accounts for, a smoothed ΔtotalStock − ΔB. x = L / B is the raw position ratio; the authoritative position is u, which every call advances by its own fraction of the restart interval that held while it ran, so the position records the path travelled rather than a ratio of today's numbers, and each landmark on the x axis is read off the reference skeleton fitted across that path. br = mf × pp is the bill premium — how much you are overpaying relative to ideal restart timing. The restart reminder is separate: it reads the rent the ledger has accumulated, so no revision of the position can withdraw one.

Lamp thresholds are the named constants BR_AMBER and BR_RED in lib/bill-regret.js: below the amber one the lamp is green, between them amber, at or above the red one red. See the [paper](#paper) for the full derivation — EOQ inventory theory mapped to LLM prompt caching.

Quick Start

Requires Node.js ≥ 22.16.

# Try without installing — self-contained demo
npx -y @nomadop/session-watcher demo

# Replay your own transcript
npx -y @nomadop/session-watcher replay ~/.claude/projects//.jsonl

Opens a browser dashboard. The demo uses a pre-built anonymized session; replay uses your real transcript. Both are read-only — nothing is modified or uploaded.

Install

Plugin (recommended)

# 1. Add the marketplace (one-time)
claude plugin marketplace add nomadop/session-watcher

# 2. Install the plugin