# nomadop/session-watcher [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/nomadop/session-watcher  
**GitHub Stars:** 5  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nomadop-session-watcher

## Description
EOQ-based context economics for coding agents. Monitors LLM token cache with inventory theory, signals optimal session restart timing via live dashboard and terminal statusline. Zero context pollution — no metric ever enters the model's context.

## Tools
Capabilities this server exposes over MCP:

- **start_watcher** — Start (or reuse) the dashboard server; returns its URL
- **stop_watcher** — Stop the managed server
- **watcher_status** — Report whether the server is running and its URL
- **rotate_session** — Rotate to a new session ID
- **get_bucket_summary** — Return current context bucket structure (files, skills, tools) with metrics
- **get_turn_skeleton** — Render the turns of the capture epoch, one block per turn, as the slots a note can fill
- **submit_turn_notes** — Return the producing session's notes through the slots the skeleton defines
- **prepare_handoff** — Persist selected paths + summary as a handoff package; returns a semantic token
- **load_handoff** — Load a handoff by token, free-text search, or auto-match for the current project
- **turn_page** — Page deeper into the history, newest first; a returned cursor proves more history remains, while its absence does not prove none does
- **turn_search** — Find a literal that occurs verbatim in the transcripts — an identifier, a path, a quoted phrase
- **turn_locate** — Find which turn ranges mention a remembered term, when the original wording is unknown

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "session-watcher": {
    "command": "npx",
    "args": ["-y","@nomadop/session-watcher"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/nomadop-session-watcher/readme_