claude-code-watch 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 phiat (https://github.com/phiat/claude-esp)
+Copyright (c) 2026 shuxuecode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# claude-watch
+
+> Stream Claude Code's hidden output (thinking, tool calls, subagents) to a web browser in real-time.
+
+Claude Code writes detailed JSONL logs under `~/.claude/projects/` as it works — including thinking blocks, tool inputs/outputs, subagent activity, and token usage. `claude-watch` tails those logs and streams everything to a local web dashboard, so you can see exactly what Claude Code is doing under the hood.
+
+![](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)
+
+## Features
+
+- **Real-time streaming** — thinking, tool calls, tool results, and text responses appear as they happen
+- **Multi-session** — watch all active Claude Code sessions simultaneously in a tree view
+- **Subagent tracking** — see subagent activity nested under their parent session
+- **Token & cost visibility** — tracks input/output/cache tokens per agent, with context window utilization
+- **Filter controls** — toggle thinking, tool input, tool output, and text visibility independently
+- **Auto-discovery** — automatically picks up new sessions as they start (toggleable)
+
+## Quick Start
+
+```bash
+npx claude-watch
+```
+
+This starts the dashboard at `http://localhost:23000` and opens it in your browser.
+
+It will auto-discover active Claude Code sessions from `~/.claude/projects/` and start streaming immediately.
+
+## Installation
+
+```bash
+npm install -g claude-watch
+```
+
+Then run:
+
+```bash
+claude-watch
+```
+
+## Usage
+
+```
+claude-watch [OPTIONS]
+
+OPTIONS:
+    -p, --port <port>    HTTP port (default: 23000)
+    -h, --host <host>    Bind host (default: 127.0.0.1)
+    -s <ID>              Watch a specific session by ID
+    -n                   Start from newest (skip history, live only)
+    -l [N]               List recent sessions (default 10) and exit
+    -a [N]               List active sessions (default all) and exit
+    -w <dur>             Active window duration (default 5m, e.g. 30s, 2m, 10m)
+    -m <N>               Max sessions to show in tree (default 0=unlimited)
+    -c <dur>             Auto-collapse sessions inactive for this duration (e.g. 2m)
+    -D                   Debug: show raw type:subtype for every JSONL line we'd drop
+    --poll <ms>          Polling interval in milliseconds (default: 500)
+    -v                   Show version
+    --help               Show this help
+```
+
+### Examples
+
+```bash
+# List recent sessions
+claude-watch -l
+
+# List active sessions from last 10 minutes
+claude-watch -a -w 10m
+
+# Watch a specific session
+claude-watch -s abc123-def456
+
+# Live-only mode (don't replay history)
+claude-watch -n
+
+# Custom port and host
+claude-watch -p 8080 -h 0.0.0.0
+
+# Limit tree to 5 most recent sessions, auto-collapse after 2m of inactivity
+claude-watch -m 5 -c 2m
+
+# Debug mode: see every unknown JSONL line type
+claude-watch -D
+```
+
+## How It Works
+
+`claude-watch` monitors the Claude Code project directory (`~/.claude/projects/`) for JSONL log files. Each Claude Code session writes structured JSON lines containing:
+
+- `assistant` messages — thinking blocks, text responses, and tool use requests
+- `user` messages — tool results and user prompts
+- `system` messages — turn duration markers, compaction boundaries
+- `attachment` messages — hook outputs and diagnostics
+- Agent metadata — session titles, subagent type info
+
+The watcher tails these files (via chokidar fsnotify events, with polling fallback), parses each line into structured stream items, and pushes them to the browser over WebSocket. The browser renders them in a terminal-style dashboard with filtering, tree navigation, and token tracking.
+
+## Environment
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_HOME` | Override Claude config directory (default: `~/.claude`) |
+
+## License
+
+MIT
+
+## Acknowledgments
+
+This project was inspired by and developed based on [claude-esp](https://github.com/phiat/claude-esp) by phiat.

package/README.zh-CN.md

@@ -0,0 +1,30 @@
+# claude-watch
+
+claude-watch — 一个 Claude Code 的实时 Web 监控仪表盘。
+
+## 核心作用
+
+Claude Code 在运行时会将详细的 JSONL 日志写入 `~/.claude/projects/` 目录，包括思考内容、工具调用、子代理活动、token 使用量等。这些信息在 Claude Code 的正常界面中并不全部可见。`claude-watch` 的作用就是**读取这些隐藏日志，实时流式传输到本地 Web 仪表盘**，让你能看到 Claude Code 的"幕后"工作细节。
+
+## 架构组成
+
+项目由三个核心模块构成：
+
+1. **`src/parser/parser.js`** — JSONL 日志解析器。将 Claude Code 的 JSONL 行解析为结构化的流项目（thinking、tool_input、tool_output、text、turn_marker、hook_output 等），并提取 token 使用量和模型信息。
+
+2. **`src/watcher/watcher.js`** — 文件监视器。使用 chokidar 监听 `~/.claude/projects/` 下的 JSONL 文件变化（带轮询 fallback），管理多会话和子代理的发现与跟踪，增量读取文件新增内容并触发解析。
+
+3. **`src/server/server.js`** — HTTP + WebSocket 服务器。提供静态页面服务、REST API（会话列表、状态、上下文信息）和 WebSocket 实时推送，将解析后的内容广播到浏览器客户端。启动时自动打开浏览器。
+
+## 主要功能
+
+- **实时流式传输** — 思考过程、工具调用/结果、文本响应实时呈现
+- **多会话监视** — 同时查看所有活跃的 Claude Code 会话
+- **子代理追踪** — 在父会话下嵌套显示子代理活动
+- **Token/成本追踪** — 每个代理的输入/输出/缓存 token 及上下文窗口利用率
+- **过滤控制** — 独立切换 thinking、工具输入/输出、文本的可见性
+- **自动发现** — 新会话启动时自动纳入监控
+
+## 致谢
+
+本项目基于 [phiat](https://github.com/phiat) 的 [claude-esp](https://github.com/phiat/claude-esp) 项目提供思路并开发。

package/bin/claude-watch.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { startServer } = require('../src/server/server');
+const { listSessions, listActiveSessions } = require('../src/watcher/watcher');
+
+const VERSION = '0.0.1';
+
+function printHelp() {
+  console.log(`claude-watch v${VERSION}
+
+Stream Claude Code's hidden output (thinking, tool calls, subagents)
+to a web browser.
+
+USAGE:
+    claude-watch [OPTIONS]
+
+OPTIONS:
+    -p, --port <port>    HTTP port (default: 23000)
+    -h, --host <host>    Bind host (default: 127.0.0.1)
+    -s <ID>     Watch a specific session by ID
+    -n          Start from newest (skip history, live only)
+    -l [N]      List recent sessions (default 10) and exit
+    -a [N]      List active sessions (default all) and exit
+    -w <dur>    Active window duration (default 5m, e.g. 30s, 2m, 10m)
+    -m <N>      Max sessions to show in tree (default 0=unlimited)
+    -c <dur>    Auto-collapse sessions inactive for this duration (e.g. 2m)
+    -D          Debug: show raw type:subtype for every JSONL line we'd drop
+    --poll <ms> Polling interval in milliseconds (default: 500)
+    -v          Show version
+    --help      Show this help
+
+ENVIRONMENT:
+    CLAUDE_HOME     Override Claude config directory (default: ~/.claude)
+`);
+}
+
+function parseDuration(s) {
+  const match = s.match(/^(\d+)(ms|s|m|h)$/);
+  if (!match) throw new Error(`Invalid duration: ${s}`);
+  const val = parseInt(match[1], 10);
+  switch (match[2]) {
+    case 'ms': return val;
+    case 's': return val * 1000;
+    case 'm': return val * 60 * 1000;
+    case 'h': return val * 3600 * 1000;
+    default: throw new Error(`Invalid duration unit: ${match[2]}`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  const options = {
+    port: 23000,
+    host: '127.0.0.1',
+    sessionID: '',
+    skipHistory: false,
+    pollMs: 500,
+    activeWindow: 5 * 60 * 1000,
+    maxSessions: 0,
+    collapseAfter: 0,
+    debugAll: false,
+  };
+
+  // First pass: collect all option values
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '-s':
+        options.sessionID = args[++i] || '';
+        break;
+      case '-n':
+        options.skipHistory = true;
+        break;
+      case '-p':
+      case '--port':
+        if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+          console.error(`Error: ${args[i]} requires a port number`);
+          process.exit(1);
+        }
+        const pv = parseInt(args[++i], 10);
+        if (isNaN(pv)) {
+          console.error(`Error: ${args[i - 1]} requires a numeric port, got '${args[i]}'`);
+          process.exit(1);
+        }
+        options.port = pv;
+        break;
+      case '-h':
+      case '--host':
+        if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+          console.error(`Error: ${args[i]} requires a host address`);
+          process.exit(1);
+        }
+        options.host = args[++i];
+        break;
+      case '-w':
+        try {
+          options.activeWindow = parseDuration(args[++i] || '5m');
+        } catch {
+          options.activeWindow = 5 * 60 * 1000;
+        }
+        break;
+      case '-c':
+        try {
+          options.collapseAfter = parseDuration(args[++i] || '5m');
+        } catch {
+          options.collapseAfter = 5 * 60 * 1000;
+        }
+        break;
+      case '-m':
+        options.maxSessions = parseInt(args[++i], 10) || 0;
+        break;
+      case '-D':
+        options.debugAll = true;
+        break;
+      case '--poll':
+        options.pollMs = parseInt(args[++i], 10) || 500;
+        break;
+      default:
+        break;
+    }
+  }
+
+  // Second pass: execute action flags with fully resolved options
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '-l': {
+        const v = parseInt(args[i + 1]);
+        const limit = !isNaN(v) ? v : 10;
+        if (!isNaN(v)) i++;
+        const sessions = await listSessions(limit);
+        if (sessions.length === 0) {
+          console.log('No sessions found.');
+        } else {
+          const now = Date.now();
+          for (const s of sessions) {
+            const age = Math.round((now - new Date(s.modified).getTime()) / 1000);
+            const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.floor(age / 60)}m ago` : `${Math.floor(age / 3600)}h ago`;
+            const active = s.isActive ? '●' : '○';
+            const id = s.id.length > 40 ? s.id.slice(0, 37) + '...' : s.id;
+            console.log(`${active} ${id}  ${s.projectPath || '?'}  ${ageStr}`);
+          }
+        }
+        return;
+      }
+      case '-a': {
+        const v = parseInt(args[i + 1]);
+        const limit = !isNaN(v) ? v : 0;
+        if (!isNaN(v)) i++;
+        const sessions = await listActiveSessions(options.activeWindow);
+        const result = limit > 0 ? sessions.slice(0, limit) : sessions;
+        if (result.length === 0) {
+          console.log('No active sessions found.');
+        } else {
+          const now = Date.now();
+          for (const s of result) {
+            const age = Math.round((now - new Date(s.modified).getTime()) / 1000);
+            const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.floor(age / 60)}m ago` : `${Math.floor(age / 3600)}h ago`;
+            const id = s.id.length > 40 ? s.id.slice(0, 37) + '...' : s.id;
+            console.log(`● ${id}  ${s.projectPath || '?'}  ${ageStr}`);
+          }
+        }
+        return;
+      }
+      case '-v':
+        console.log(`claude-watch v${VERSION}`);
+        return;
+      case '--help':
+        printHelp();
+        return;
+      default:
+        if (args[i].startsWith('-')) {
+          console.error(`Unknown option: ${args[i]}`);
+          printHelp();
+          process.exit(1);
+        }
+    }
+  }
+
+  startServer(options);
+}
+
+main().catch(err => {
+  console.error(`Fatal error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "claude-code-watch",
+  "version": "0.0.1",
+  "description": "Web-based real-time monitor for Claude Code.",
+  "main": "./src/server/server.js",
+  "bin": {
+    "claude-watch": "./bin/claude-watch.js"
+  },
+  "scripts": {
+    "start": "node bin/claude-watch.js",
+    "dev": "node --watch bin/claude-watch.js",
+    "test": "node --test tests/all.test.js tests/watcher.test.js tests/server.test.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "watcher",
+    "web",
+    "dashboard"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shuxuecode/claude-watch"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "ws": "^8.20.0"
+  }
+}