Skip to main content
Glama
nomadop

session-watcher

by nomadop
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

Session Watcher

LLM context economics, in your terminal.

Session Watcher treats your prompt cache as inventory — it uses EOQ theory to measure whether the current context is still worth carrying, tracking restart pressure so you can decide when to hand off.

What it does

Session Watcher reads your Claude Code transcript in real time and answers one question: is this session still worth carrying?

Most context tools optimize how you consume tokens — Headroom compresses, /compact shrinks, RTK filters. Session Watcher tracks when the cost curve is drifting, giving you the data to decide. They compose: run any pruning strategy you like, SW measures the cost curve so you can decide when to hand off.

SW reads from the transcript, never writes to it. The dashboard and statusline are pure observers; MCP tools return data for you to act on. Metrics stay on your screen, not in the model's context window.

Related MCP server: OpenExp

How it works

Your coding agent (Claude Code)
        │  writes session transcript
        ▼
┌──────────────────────────────────────────┐
│  Session Watcher (in-process MCP server)  │
│  ─────────────────────────────────────── │
│  fold.js     — tail JSONL, fold usage    │
│  measure.js  — B (context belief)        │
│  rate-lamp   — bill premium (br) + gate  │
│  server.js   — Express + SSE dashboard   │
│  statusline  — one-line shell client     │
└──────────────────────────────────────────┘
        │  dashboard  ·  statusline  ·  MCP
        ▼
   Your browser / terminal status bar

Core model: B = cache_read_input_tokens (your context inventory). g = ΔL − ΔB (growth gap). x = L / B (position on the EOQ cost curve). br = mf × pp (bill premium — the percentage you're overpaying relative to optimal).

Lamp thresholds: green (br < 10%), amber (10–24%), red (≥ 25%). See the paper for the full derivation — EOQ inventory theory mapped to LLM prompt caching.

Quick Start

Requires Node.js ≥ 22.16.

# Try without installing — self-contained demo
npx -y @nomadop/session-watcher demo

# Replay your own transcript
npx -y @nomadop/session-watcher replay ~/.claude/projects/<project>/<session>.jsonl

Opens a browser dashboard. The demo uses a pre-built anonymized session; replay uses your real transcript. Both are read-only — nothing is modified or uploaded.

Install

Plugin (recommended)

# 1. Add the marketplace (one-time)
claude plugin marketplace add nomadop/session-watcher

# 2. Install the plugin
claude plugin install session-watcher@session-watcher

Or from within a Claude Code session:

/plugin marketplace add nomadop/session-watcher
/plugin install session-watcher@session-watcher
/reload-plugins

This registers:

  • MCP tools — available in every session

  • SessionStart hook — auto-launches the dashboard server on each session

If you installed or updated in an already-running session, run /reload-plugins to activate.

Statusline

The plugin system does not yet support declaring a statusline. Add to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "<plugin-install-path>/dist/statusline.js"
  }
}

Find your plugin path with:

find ~/.claude/plugins/cache -path '*/session-watcher/*/dist/statusline.js' -print

Or check via claude plugin details session-watcher@session-watcher.

Note: the plugin cache path changes on version update. After updating, re-run the command above and update your statusline path.

One compact line:

Context Buckets

The bucket panel shows exactly which files, skills, and tools are consuming your context budget. Each path carries a token count — check or uncheck to preview how the restart cost changes. The U-curve ghost line updates in real time as you toggle.

Handoff

When it's time to restart, handoff preserves the state you want to keep. Run /sw-handoff to prepare a package — selected paths, working summary, next task. Then /clear, and in the fresh session run /sw-load to restore. Only what you chose is rebuilt — less ramp-up, less waste.

MCP Tools

Server lifecycle

Tool

Description

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

Handoff workflow

Tool

Description

get_bucket_summary

Return current context bucket structure (files, skills, tools) with metrics

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

Tools return data for you to decide on — only handoff injects context back into the model, and only the paths you explicitly selected.

Agent support

Session Watcher is agent-agnostic. The measurement pipeline only needs cache_read_input_tokens from each turn — it doesn't care which agent produced the transcript.

Agent

Driver

Status

Claude Code

JSONL tail (native)

✅

OpenCode

adapter-ready

pending

OpenClaw

adapter-ready

pending

Hermes

adapter-ready

pending

Aider

adapter-ready

pending

Adding a new agent requires implementing one interface: extract cache_read_input_tokens from the agent's session transcript. See lib/extract.js for the Claude Code reference driver. PRs welcome.

Paper

Context Is Inventory: A Rent-or-Buy Model for Prompt-Cached LLM Sessions Longju Cheng (2026) · DOI: 10.5281/zenodo.21236704

The paper derives the full theoretical specification: EOQ→LLM mapping, the 41.4% movable-cost bound, the ski-rental restart strategy, and measurements on 1,016 real session transcripts. See paper/paper.pdf.

Uninstall

claude plugin uninstall session-watcher@session-watcher
# Remove state directory (optional):
rm -rf ~/.session-watcher

Test

npm test              # unit + integration (node:test)
npx playwright test   # E2E (requires running server)

Citation

@unpublished{cheng2026context,
  author = {Longju Cheng},
  title  = {Context Is Inventory: A Rent-or-Buy Model for Prompt-Cached LLM Sessions},
  year   = 2026,
  doi    = {10.5281/zenodo.21236704},
  url    = {https://doi.org/10.5281/zenodo.21236704},
  note   = {Preprint}
}

Privacy

  • No remote telemetry.

  • Transcripts are read locally and never uploaded.

  • Local aggregate usage and handoff records are stored under ~/.session-watcher.

  • No transcript prose or file contents are stored in telemetry.

  • Removing ~/.session-watcher deletes all local state.

License

MIT

Available Tools

3 tools
start_watcherA
Read-only

Start (or reuse) the Session Watcher dashboard server; returns its URL. Never returns metric values.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotation readOnlyHint: true suggests no state mutation, but the description says 'start' which implies a side effect (launching a server). This contradiction lowers transparency. The description does add that it never returns metric values, but does not explain reuse behavior or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and front-loaded, using a single sentence to convey all essential information with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and only readOnlyHint annotation, the description is mostly complete: it states the return (URL) and what it does not return (metric values). However, it omits details on reuse behavior and whether starting creates a new process or reuses an existing one, leaving minor ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description provides no parameter details, which is acceptable as there are none. Baseline for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool starts or reuses a Session Watcher dashboard server and returns its URL, explicitly noting it never returns metric values. This differentiates from siblings like stop_watcher and watcher_status, which are distinct actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage to obtain the watcher URL but lacks explicit guidance on when to use versus stop_watcher or watcher_status, nor does it mention prerequisites or context. Usage is implied rather than clearly directed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stop_watcherB
Read-only

Stop the managed Session Watcher server.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description claims 'Stop' (a mutation) while annotations set readOnlyHint=true, a direct contradiction. No additional behavioral traits disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded, no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing details on behavior (e.g., confirmation, return value, side effects). The contradiction further reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema covers everything. Description adds no extra meaning, which is acceptable; baseline for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Stop' and the resource 'managed Session Watcher server', distinguishing it from siblings 'start_watcher' and 'watcher_status'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives; lacks context such as prerequisites or dependencies.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

watcher_statusA
Read-only

Report whether the Session Watcher server is running and its URL.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint: true, so the description adds value by specifying the output (status and URL) but does not disclose additional behavioral traits beyond that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no extraneous words, front-loaded with the key action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters or output schema. The description fully covers its purpose and output, and sibling tools provide operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description needs no parameter explanation, achieving baseline for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports whether the Session Watcher server is running and its URL, using a specific verb and resource. It distinguishes from sibling tools (start/stop) by focusing on status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking server status, and siblings provide context for start/stop operations. However, it lacks explicit when-not or alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.3.0
    • First observedstart_watcher
    • First observedstop_watcher
    • First observedwatcher_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a distinct purpose: starting, stopping, or checking status of the watcher server. No overlap or ambiguity.

Naming Consistency4/5

All names use snake_case and follow a verb_noun or noun_noun pattern consistently, though 'watcher_status' is a noun phrase while the others are imperative verbs.

Tool Count5/5

Three tools is within the typical 3-15 range and perfectly scoped for the server's purpose of managing a session watcher dashboard.

Completeness5/5

The tool set covers the full lifecycle of the watcher server: start, stop, and status check. No obvious gaps for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • OpenExp

    anthroos
    A
    license
    Not graded
    quality
    C
    maintenance
    Q-learning memory for Claude Code. Persistent memory that learns which context helps you get work done. Memories that lead to productive sessions (commits, PRs, tests) earn higher retrieval rank automatically. 16 MCP tools, hybrid BM25 + vector + Q-value scoring, local-first with Qdrant + FastEmbed.
    59
    MIT
  • ctxray by ctxray

    ctxrayofficial

    ctxray
    A
    license
    Not graded
    quality
    C
    maintenance
    Context intelligence for AI coding sessions. 7 MCP tools to score, compare, compress, build, and scan prompts across 9 AI tools. Rule-based, <5ms/prompt, all analysis runs locally.
    46
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nomadop/session-watcher'

If you have feedback or need assistance with the MCP directory API, please join our Discord server