Master of Puppets

Master of Puppets is a VS Code extension that gives you a real-time cockpit for all your Claude Code sessions. It reads session data directly from ~/.claude/projects/ — the JSONL files Claude Code writes locally — without requiring an API key for the core monitoring features. Auto-refreshes every 5 seconds and reacts instantly to file changes via a watcher. The status bar shows a live count of active sessions.

Panels

1. Sidebar — Session Tree

The left activity bar panel. Hierarchy: pinned shortcuts at the top, then projects, then sessions within each project.

• ● = active session, ○ = idle, ⚠ = waiting for tool approval (session blocked on a tool that requires confirmation)
• Hovering a session shows a tooltip with a preview of the first prompt, message/tool call counts, start time, and the full session ID
• Clicking a session opens the Dashboard focused on that session
• Right-click context menu: Delete session, Resume session (opens a terminal with claude --resume <id>), Copy resume command
• Projects that contain active sessions show a green folder icon

2. Sessions — Tiling Panel

The main monitoring view — all sessions on screen simultaneously. Four layout modes:

• master-stack — one primary tile on the left, the rest stacked on the right (Hyprland-style)
• grid, columns, rows

Each tile shows: status dot, session name, model, last activity time, user/assistant messages, tool calls with diffs (Edit/Write) and Bash output, and a context-usage footer with percentage and token counters.

Additional controls:

• Collapse — collapsed sessions drop into a collapsible tray at the bottom; the tray itself has its own toggle
• Tile ordering — click the numbered badge on a tile and type a position to reorder
• ↑/↓ newest — toggles message sort order inside a tile
• Toolbar status bar shows waiting/running/active/idle counts and avg/max context fill across all sessions

3. Dashboard — Session Cards

Detailed per-session card layout with full conversation history.

• Two sections: Active Sessions and Recent Sessions (up to 30 idle sessions)
• Agent parent→child relationship graph shown when one session spawns a sub-agent
• Each card includes: a color-coded context usage bar (green → yellow → red), the current prompt, full message history with tool calls and inline diffs, and an activity badge
• Clicking a session in the sidebar switches to focus view — a single card at full width
• Rename or color-tag sessions by clicking the editable fields in the card header
• Toolbar actions: Delete session, Clear idle sessions, Reset Layout, Sidebar toggle

4. Cost Summary

Per-project, per-session breakdown of token usage and estimated API cost.

• Hierarchy: project → sessions sorted from most to least expensive
• Columns: model, input tokens, output tokens, cache read, cache write, est. cost
• Grand total and a summary line at the top
• A pricing reference table (Opus / Sonnet / Haiku) at the bottom
• Refresh Prices — fetches current prices from platform.claude.com (cached for 24 hours)
• Export to MD — exports the full report as a Markdown file
• Only sessions using an API key (external) contribute costs — subscription sessions show token counts but no estimated cost

5. Tool Stats

Aggregated statistics for every tool Claude used (Bash, Read, Edit, Agent, etc.).

• Columns: tool name, call count, cache read tokens, output tokens, avg output/call, cache write, est. cost
• Click any column header to sort
• Project filter dropdown — view stats for a single project or all projects combined
• Data is cached incrementally in ~/.claude/tool-stats-cache.json — only new JSONL lines are parsed on each refresh
• Rebuild Cache — discards and fully recomputes the cache from scratch
• Export to MD — exports the table as Markdown
• Refresh Prices — updates the pricing data
• The est. cost column is hidden when no API-key sessions are present (subscription-only data)

Installation

From VSIX

code --install-extension master-of-puppets-<version>.vsix

Build from source

npm install
npm run compile
node_modules/.bin/vsce package --allow-missing-repository

Press F5 in VS Code to launch an Extension Development Host without packaging.

Configuration

Data source

All data is read locally from ~/.claude/projects/<encoded-path>/<session-id>.jsonl. Nothing is sent anywhere. The only network request is fetching the pricing table (optional, cached for 24 hours).

Requirements

• VS Code 1.85+
• Claude Code CLI installed and used at least once (so ~/.claude/projects/ exists)