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)
  • u (Normalized Position)
  • reference (Reference Skeleton)
• Rate Axis
  • g (Growth Rate)
  • residual
• Cost Axis
  • dhat (Nucleus)
  • xSweet (Sweet Spot)
  • pp (Position Penalty)
  • br (Bill Premium)
  • mf (Movable Fraction)
  • cRatio (Cost Ratio)
  • wallP (Rate Wall Position)
• Operations Axis
  • backstopInterval
  • BR_AMBER
  • BR_RED
  • Lamp States
• Structure Axis
  • pathTotal
  • discardReason
  • scenario (Position Preview)
  • 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

DSH Plugin

• Install
• What gets watched
• The Session Watcher tab
  • Refresh
  • The badge
• The composer dock
• Supported surface
• Tools
• Skills
• Commands
• Handoff across sessions
• Turn Notes
• Replaying a session log