What can you do with this server?

This server manages the lifecycle of the Session Watcher dashboard server. * start_watcher: Start (or reuse) the dashboard server and get its URL. It never returns metric values. * stop_watcher: Stop the managed dashboard server. * watcher_status: Check whether the server is running and get its URL.

Which integrations are available for this server?

Adapter-ready integration for Hermes coding agent (pending implementation) to monitor session transcripts and provide restart recommendations.

session-watcher

by nomadop

Overview Schema Source Related Servers Discussions Admin

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.

Related MCP server: ctxray

How it works

Your coding agent (Claude Code)
        │  writes session transcript
        ▼
┌───────────────────────────────────────────────────────┐
│  Session Watcher (in-process MCP server)              │
│  ───────────────────────────────────────────────────  │
│  harness/claude-code  — read rows, emit observations  │
│  measurement/engine   — B (context belief), epochs    │
│  session-watcher      — apply frames, run operations  │
│  rate-lamp            — rent ledger + wallet clock    │
│  server.js            — Express + SSE dashboard       │
│  statusline           — one-line shell client         │
└───────────────────────────────────────────────────────┘
        │  dashboard  ·  statusline  ·  MCP
        ▼
   Your browser / terminal status bar

The harness layer is the only part that knows Claude Code: it reads transcript rows, decides the active branch, and emits normalized observations. Everything below it — measurement, dialogue history, handoff — consumes those observations and carries no transcript format, no row shape, and no tool name of any particular agent.

Core model: L = cache_read_input_tokens — the context stock you are renting. B is the rebuild baseline: the session's overhead floor plus the tokens of every file, skill and tool it has pulled in, which is what a restart would have to re-read. g is the growth no path accounts for, a smoothed ΔtotalStock − ΔB. x = L / B is the raw position ratio; the authoritative position is u, which every call advances by its own fraction of the restart interval that held while it ran, so the position records the path travelled rather than a ratio of today's numbers, and each landmark on the x axis is read off the reference skeleton fitted across that path. br = mf × pp is the bill premium — how much you are overpaying relative to ideal restart timing. The restart reminder is separate: it reads the rent the ledger has accumulated, so no revision of the position can withdraw one.

Lamp thresholds are the named constants BR_AMBER and BR_RED in lib/bill-regret.js: below the amber one the lamp is green, between them amber, at or above the red one red. 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 — points the running watcher at a new session and announces pending handoffs

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

DSH plugin

@nomadop/session-watcher-dsh runs Session Watcher inside DeepSeek Harness (DSH). It watches every running session of the host it loads into and shares ~/.session-watcher with the Claude Code plugin.

dsh plugin --profile <name> add @nomadop/session-watcher-dsh

The Session Watcher tab — a view in the conversation view strip that mounts the dashboard's elements for that session.
The composer dock — a pill below the composer showing the lamp, the bill premium and the alert clock, with the position and the context stock in its popover.
Tools — the MCP tools, each answering for the calling agent's own session, except that watcher_status can name another.
Skills — sw-handoff, sw-load and sw-explain, registered with the host.
Handoff across sessions — an agent that starts or resumes gets a message listing the pending handoffs other sessions prepared for its project.
Replay — npx -y @nomadop/session-watcher replay <path> plays a DSH session log back on the dashboard.

See the DSH plugin docs for the profile to add it to, what the tab and the dock show, the surface they are supported on, and handoffs that cross between the two hosts.

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

Both plugins register the same tools, except for rotate_session, which only Claude Code registers. The Guarantees page tables them once, with where the two hosts differ.

Agent support

Session Watcher is agent-agnostic. Everything below the harness layer consumes normalized observations, so it never learns which agent produced the session.

Agent	Driver	Status
Claude Code	JSONL tail (native)	✅
DSH (DeepSeek Harness)	session event log (native)	harness ✅ · plugin ✅
OpenCode	adapter-ready	pending
OpenClaw	adapter-ready	pending
Hermes	adapter-ready	pending
Aider	adapter-ready	pending

Adding a new agent means writing a harness for it under lib/harness/<agent>/: a source driver that turns that agent's own session evidence into normalized observations, a thin measurement projection adapter over the shared lib/measurement-projection.js with the interpreters for the agent's native tools, the dialogue source and history turn rules that read its conversation, and the recovery sentences that tell a reader how to open a turn it cites. The engine, dialogue history, handoff, and every product surface are shared and need no change. See lib/harness/claude-code/ for the reference harness and lib/harness/dsh/ for a second one. 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. Read it at the DOI above.

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, except the Turn Notes a DSH session prepared and has not yet submitted successfully, which sit under the system temp directory.

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

Name	Required	Description	Default
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

Name	Required	Description	Default
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

Name	Required	Description	Default
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.

3 tool updatesv0.3.0Jul 17, 2026
- First observedstart_watcher
- First observedstop_watcher
- First observedwatcher_status

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4/5.0

Scored 2026-07-17 16:17 across 3 tools

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

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

TeamShared C
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
1001
PAPI: Persistent Adaptive Project IntelligenceOAuth
io.github.getpapi
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Coding Agents Autonomous Agents
211
NASC — Networked AI Session ContinuityOAuth
com.archerionlabs
Shared memory across AI dev tools: each session hands its context to the next, not starting cold.
Knowledge & Memory Developer Tools
2
todox
io.github.beydemirfurkan
Memory for coding agents: the decisions, the dead ends, and where the last session stopped.
Coding Agents Knowledge & Memory Developer Tools
12

Related MCP Servers

memoir-mcp
Knowledge & Memory Developer Tools Autonomous Agents
bighippoman
A
license
A
quality
D
maintenance
Structured session journals for AI agents. Persistent memory across sessions -- no more repeating dead ends.
Updated 7 months ago (2026-03-06 13:35 UTC)
8
36 npm
MIT
ctxrayofficial
Developer Tools AI & Machine Learning
ctxray
A
license
Not graded
quality
B
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.
Updated 4 months ago (2026-06-24 02:33 UTC)
47
MIT
claude-engram
AI & Machine Learning Developer Tools Knowledge & Memory
20alexl
A
license
B
quality
B
maintenance
Persistent memory and session intelligence for AI coding assistants. Auto-tracks mistakes, decisions, and context via hooks. Mines your full session history for patterns, predictions, and cross-session search.
Updated 18 days ago (2026-09-27 03:41 UTC)
21
16
MIT
io.github.420247jake/session
Knowledge & Memory Developer Tools
420247jake
A
license
Not graded
quality
D
maintenance
Never start from zero. Persistent session intelligence for AI coding assistants.
Updated 7 months ago (2026-03-09 04:31 UTC)
57 npm
1
MIT

Session Watcher

What it does

How it works

Quick Start

Install

Plugin (recommended)

DSH plugin

Statusline

Context Buckets

Handoff

MCP Tools

Agent support

Paper

Uninstall

Test

Citation

Privacy

License

Available Tools

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

memoir-mcp

ctxrayofficial

claude-engram

io.github.420247jake/session