Session Watcher

What nomadop/session-watcher MCP server does

The nomadop/session-watcher MCP server treats prompt-cache tokens as session inventory. It follows a Claude Code transcript as it grows, measures the relationship between cached context and new prompt content, and reports whether carrying the current context is becoming costly. The project applies an EOQ-style model to prompt caching rather than attempting to compress or prune the conversation itself.

The dashboard presents context buckets for files, skills, and tools. Each path includes a token count, and selecting or clearing paths previews how the estimated restart cost changes. A terminal statusline can show a compact view of the current state.

The measurement and display layers are observers. Transcripts are read locally and are not modified or uploaded. Metrics are returned through the dashboard, statusline, or MCP tools instead of being inserted into the model's context.

How it works

The native input is a Claude Code JSONL session transcript. The pipeline extracts cache_read_input_tokens from turns, follows the transcript as new turns arrive, and derives measures such as context inventory, growth gap, EOQ-curve position, and bill premium. The dashboard uses green, amber, and red thresholds for the reported premium: below 10 percent, 10–24 percent, and 25 percent or higher.

A session can be rotated when a restart is appropriate. Before clearing the old session, the handoff workflow can preserve selected paths, a summary, and the next task. A new session can load that package by its returned semantic token, by text search, or by matching the current project. Turn-history tools then inspect the lineage associated with the loaded handoff.

Setup and configuration

Node.js 22.16 or newer is required. For a quick read-only demonstration, run npx -y @nomadop/session-watcher demo. To inspect an existing transcript, use the replay command with the path to a Claude Code JSONL file.

The recommended installation is the Claude Code plugin:

• Add the marketplace with claude plugin marketplace add nomadop/session-watcher.
• Install it with claude plugin install session-watcher@session-watcher.
• Run /reload-plugins if the plugin was added or updated during an existing session.

The plugin registers the MCP tools and a SessionStart hook that launches the dashboard server. Statusline support requires adding a command entry to Claude Code's ~/.claude/settings.json, pointing to the installed dist/statusline.js. The plugin cache path can change after updates, so the path may need to be found again.

Tools and capabilities

The nomadop/session-watcher MCP server provides tools in four groups:

• Lifecycle: start or reuse the dashboard, stop it, check its URL and running state, and rotate the session ID.
• Context and handoff: inspect bucket metrics, create turn-note slots, submit notes, prepare a selected-path handoff, and load one.
• History: page through newer-to-older turns, search for an exact literal, or locate turn ranges containing a term whose original wording is uncertain.

History tools resolve the lineage of the currently loaded handoff and do not take a separate lineage identifier. A cursor from turn_page confirms that more history exists; no cursor is not proof that the history is exhausted.

Limitations and notes

Native transcript support is for Claude Code. The project describes other agents as adapter-ready but pending, including OpenCode, OpenClaw, Hermes, and Aider. Adding another agent requires an extractor for its cache_read_input_tokens data.

The server measures the cost curve and supplies information for a restart decision; it does not replace pruning or compression tools. Only the explicitly selected handoff paths are rebuilt, and handoff is the mechanism that can inject preserved context into a later model session. No remote telemetry is used, and local transcript data remains local.