Session Watcher Documentation

Session Watcher observes the cost curve of a Claude Code session and helps you decide when to hand off.

Concepts

• Position Axis
  • L (Effective Context Length)
  • B (Baseline)
  • System Overhead (Floor)
  • x (Position Ratio)
• Rate Axis
  • g (Growth Rate)
  • residual
• Cost Axis
  • dhat (Nucleus)
  • xSweet (Sweet Spot)
  • bp (Bill Premium)
  • mf (Movable Fraction)
  • cRatio (Cost Ratio)
  • wallP (Rate Wall Position)
• Operations Axis
  • rentRate
  • backstopInterval
  • BP_AMBER
  • BP_RED
  • Lamp States
• Structure Axis
  • pathTotal
  • discardReason
  • Bucket Types

Cookbook

• Scope and Limits
• Lamp / bp Interpretation
• When to Restart
• Measurement Bias and Conservative Assumptions
• Handoff Operations
• Configuration and Operations

How It Works

• Pipeline
• Session Lifecycle
  • 1. Hook (session-start)
  • 2. Server bootstrap
  • 3. Polling
  • 4. Segmentation
  • 5. Session rotation
  • 6. Shutdown
• Handoff

Guarantees

• Input Contract
• Measurement Invariants
• Output Semantics
• Persistence Boundary
• Hook Behavior
• MCP Tools
• Degradation