Session Watcher manages the LLM's context as inventory, uses Economic Order Quantity (EOQ) theory to judge whether the current session's context is still worth carrying, and tracks restart pressure to help users decide when to hand off. Its positioning is that of an observation tool: it reads transcripts and never writes, the dashboard and status line are pure observers, and the MCP tools only return data for users to act on themselves.
Purpose It answers one core question: is this session still worth carrying? Most context tools optimize how tokens are consumed (compression, shrinking, filtering), whereas Session Watcher tracks drift in the cost curve and gives you the data to decide when to hand off. The two can be used in combination: run any pruning strategy first, then measure the cost curve with it.
Core model L = cache_read_input_tokens, i.e. the context stock you are "renting"; B is the rebuild baseline, i.e. the session's fixed overhead floor plus the token amount for each file, skill, and tool it introduces, that is, what must be re-read after a restart; g is the smoothed ΔtotalStock − ΔB, representing growth not accounted for by the path. x = L / B is the raw position ratio; the authoritative position is u, which advances on each call by its own share of the restart interval, so it records the path traveled rather than the ratio of today's values, and each marker on the x-axis is read from a reference skeleton fitted to that path. br = mf × pp is the bill premium, i.e. the extra amount paid relative to the ideal restart timing. Restart alerts are handled separately: they read the rent accumulated in the ledger, so no position correction can retract an alert. The indicator light thresholds are the named constants BR_AMBER and BR_RED in lib/bill-regret.js: below amber is green, between the two is amber, and at or above red is red. The full derivation is in the paper, i.e. EOQ inventory theory mapped to LLM prompt caching.
Requirements and quick start Requires Node.js ≥ 22.16. After startup, the browser dashboard opens. Demo mode uses a prebuilt anonymized session; replay mode uses your own real transcripts. Both are read-only and will not modify or upload anything.
Installation method (plugin, recommended) It can be installed via a plugin, or installed within a Claude Code session. It registers: MCP tools (available in every session); a SessionStart hook (points the running watcher at the new session and reports pending handoffs). If it is in an already running sessionTo install or update in, run /reload-plugins to activate.
DSH integration @nomadop/session-watcher-dsh runs Session Watcher in DeepSeek Harness (DSH). It monitors every running session in the loaded host and shares ~/.session-watcher with the Claude Code plugin. It includes: the Session Watcher tab, located in the conversation view bar, which mounts that session's dashboard elements; the composer dock, a pill below the input box that shows the indicator light, billing premium, and reminder clock, with location and context stock shown in a popover; tools, i.e., MCP tools, each of which answers the calling agent's own session, but watcher_status can specify other sessions; skills, sw-handoff, sw-load, and sw-explain, registered with the host; cross-session handoff, where a started or resumed agent receives a message listing the pending handoffs other sessions have prepared for its project; replay, using npx -y @nomadop/session-watcher replay <path> to replay DSH session logs on the dashboard.
Status line The plugin system does not currently support declaring a status line; it must be added manually to ~/.claude/settings.json. You can use a command to find the plugin path, or view it via claude plugin details session-watcher@session-watcher. Note: the plugin cache path changes when the version is updated; after updating, rerun the above command and update the status line path. The status line is displayed as a compact single line.
Context bucketing and handoff The bucketing panel shows which files, skills, and tools are consuming your context budget. Each path comes with a token count; checking or unchecking it previews how the restart cost would change; the U-shaped curve ghost line updates in real time as you toggle. When a restart is needed, the handoff feature preserves the state you want to keep: run /sw-handoff to prepare a package (selected paths, work summary, next task), then /clear, and run /sw-load in the new session to restore. Only what you select is rebuilt, reducing warm-up and waste. Both plugins register the same tools, but rotate_session is registered only by Claude Code; GuaranThe tees page lists the differences between the two in a unified way.
Architecture and Extension The Session Watcher is independent of any specific agent. Everything below the harness layer consumes normalized observations, so it never knows which agent produced a session. To add an agent, you need to write a harness under lib/harness/<agent>/: a source driver (converting that agent's own session evidence into normalized observations), a thin measurement projection adapter based on the shared lib/measurement-projection.js (including an interpreter for that agent's native tools), a conversation source for reading its conversations along with historical turn rules, and a resume statement telling the reader how to open the turn it references. The engine, conversation history, handoff, and all product interfaces are shared and require no changes. For a reference harness, see lib/harness/claude-code/; for a second one, see lib/harness/dsh/.
Paper "Context Is Inventory: A Rent-or-Buy Model for Prompt-Cached LLM Sessions", Longju Cheng (2026), DOI: 10.5281/zenodo.21236704. The paper provides the complete theoretical specification: the EOQ→LLM mapping, the 41.4% movable cost bound, the ski-rental-style restart strategy, and measurements on 1,016 real session transcripts.
Privacy No remote telemetry. Transcripts are read locally and never uploaded. Locally aggregated usage and handoff records are stored under ~/.session-watcher. Transcript bodies and file contents are not stored in telemetry. Deleting ~/.session-watcher clears all local state, except for Turn Notes for DSH sessions that are prepared but not yet successfully committed, which reside in the system temporary directory.
Limitations and Not Yet Provided Specific fees, prices, and paid plans are not provided in the materials; apart from Node.js ≥ 22.16, Claude Code, and DSH, the materials do not mention any other supported hosts for platform support. Results depend on real session transcripts, and the materials provide no quantitative performance promises.
