--- title: "claude-esp" description: "[![Go Reference](https://pkg.go.dev/badge/github.com/phiat/claude-esp.svg)](https://pkg.go.dev/github.com/phiat/claude-esp)" type: skill canonical_url: https://claudary.paisolsolutions.com/skills/readme-242 source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:36:17.185Z license: CC-BY-4.0 attribution: "claude-esp — Claudary (https://claudary.paisolsolutions.com/skills/readme-242)" --- # claude-esp [![Go Reference](https://pkg.go.dev/badge/github.com/phiat/claude-esp.svg)](https://pkg.go.dev/github.com/phiat/claude-esp) ## Overview # claude-esp [![Go Reference](https://pkg.go.dev/badge/github.com/phiat/claude-esp.svg)](https://pkg.go.dev/github.com/phiat/claude-esp) Stream Claude Code's hidden output (thinking, tool calls, subagents) to a separate terminal in real-time. ![claude-esp screenshot](docs/screenshot.png) Looking for the Rust port? See: [claude-esp-rs](https://github.com/phiat/claude-esp-rs) ## The Problem When using Claude Code interactively, tool outputs and thinking are collapsed by default and require pressing `Ctrl+O` to toggle visibility. This tool lets you watch all that output in a **separate terminal** with a nice TUI, without interrupting your main Claude Code session. ## Features - **Multi-session support** - Watch all active Claude sessions simultaneously - **Hierarchical tree view** - Sessions with nested Main/Agent nodes - **Real-time streaming** - See thinking, tool calls, and outputs as they happen - **Subagent tracking** - Automatically discovers and displays subagent activity - **Agent type labels** - Shows agent types (Explore, code-reviewer, etc.) from `.meta.json` - **Token usage tracking** - Cumulative input/output token counts in the header bar - **Tool execution duration** - Shows how long each tool call took - **Background task visibility** - See background tasks (⏳/✓) under spawning agent - **Filtering** - Toggle visibility of thinking, tools, outputs per session/agent - **Auto-scroll** - Follows new output, or scroll freely through history ## Requirements - Go 1.23 or later ## Installation ```bash # Install directly via go install go install github.com/phiat/claude-esp@latest # Or clone and build from source git clone https://github.com/phiat/claude-esp.git cd claude-esp go build -o claude-esp . # Optional: install to PATH cp claude-esp ~/.local/bin/ ``` ### Pre-built binaries Download pre-built binaries from the [Releases](https://github.com/phiat/claude-esp/releases) page. Available for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64). ## Usage ```bash # In your main terminal: run Claude Code as normal claude # In a second terminal/tmux pane: run the watcher claude-esp ``` ### Options | Option | Description | | ---------- | --------------------------------------------- | | `-s ` | Watch a specific session by ID | | `-n` | Start from newest (skip history, live only) | | `-l` | List recent sessions | | `-a` | List active sessions | | `-p ` | Poll interval in ms (fallback mode only, default 500) | | `-w ` | Active window duration (default `5m`, e.g. `30s`, `2m`) | | `-m ` | Max sessions to show in tree (default 0 = unlimited) | | `-c ` | Auto-collapse sessions inactive ≥ dur (default 0 = disabled, e.g. `2m`) | | `-v` | Show version | | `-h` | Show help | ### Environment Variables | Variable | Description | | ------------- | --------------------------------------------------- | | `CLAUDE_HOME` | Override Claude config directory (default: `~/.claude`) | ### Examples ```bash # Watch all active sessions claude-esp # Skip history, only show new output claude-esp -n # List active sessions claude-esp -a # Watch a specific session claude-esp -s 0b773376 # Faster poll interval (200ms) claude-esp -p 200 # List recent sessions claude-esp -l ``` ## Keybindings | Key | Action | | --------- | ----------------------------------------- | | `t` | Toggle thinking visibility | | `i` | Toggle tool input visibility | | `o` | Toggle tool output visibility | | `x` | Toggle text/response visibility | | `a` | Toggle auto-scroll | | `h` | Hide/show tree pane | | `A` | Toggle auto-discovery of new sessions | | `tab` | Switch focus between tree and stream | | `j/k/↑/↓` | Navigate tree or scroll stream | | `space` | On session: collapse/expand (pins on manual expand) · On agent: toggle visibility | | `s` | Solo selected session/agent (toggle) | | `enter` | Load background task output (when selected)| | `g/G` | Go to top/bottom of stream | | `q` | Quit | ## Auto-Collapse Run with `-c 2m` to automatically collapse sessions that have been idle for 2 minutes. Collapsed sessions show `▸` instead of `▾` in the tree and display the count of hidden subagents (e.g. `📂▸ my-session (+2)`). Children of collapsed sessions are also filtered out of the stream pane — the whole point is to stop sleeping sessions from dominating your view. Press `space` on a collapsed session to expand it manually. Manual expansion **pins** the session — it won't auto-collapse again until it wakes up (receives new activity) and then goes idle once more. Press `s` to solo a session; if it's collapsed, Solo force-expands and pins it so you can see its output. ## How It Works Claude Code stores conversation transcripts as JSONL files in: ``` ~/.claude/projects//.jsonl ``` Subagents are stored in: ``` ~/.claude/projects///subagents/agent-.jsonl ``` Background task outputs are stored in: ``` ~/.claude/projects///tool-results/toolu_*.txt ``` The watcher: 1. Discovers active sessions (modified in last 5 minutes) 2. Uses OS-native filesystem notifications ([fsnotify](https://github.com/fsnotify/fsnotify)) to detect file changes in real-time (inotify on Linux, kqueue/FSEvents on macOS) 3. Falls back to polling (configurable with `-p`) on filesystems that don't support notifications (NFS, some cross-FS WSL2 setups) 4. Debounces rapid writes (50ms window) to efficiently handle burst output 5. Parses JSON lines and extracts thinking/tool_use/tool_result 6. Discovers background tasks and correlates them with spawning agents 7. Renders them in a TUI with tree navigation and filtering ## tmux Setup Recommended tmux layout: ```bash # Create a new tmux session with two panes tmux new-session -s claude \\; \\ split-window -h \\; \\ send-keys 'claude-esp' C-m \\; \\ select-pane -L \\; \\ send-keys 'claude' C-m ``` Or add to your `.tmux.conf`: ``` bind-key C-c new-window -n claude \\; \\ send-keys 'claude' C-m \\; \\ split-window -h \\; \\ send-keys 'claude-esp' C-m \\; \\ select-pane -L ``` Then press `prefix + Ctrl+C` to open a Claude Code workspace. ## Project Structure ``` claude-esp/ ├── main.go # CLI entry point ├── internal/ │ ├── parser/ │ │ └── parser.go # JSONL parsing │ ├── watcher/ │ │ └── watcher.go # File monitoring │ └── tui/ │ ├── model.go # Bubbletea main model │ ├── tree.go # Session/agent tree view │ ├── stream.go # Stacked output stream │ └── styles.go # Lipgloss styling ``` ## Development Built with [Bubbletea](https://github.com/charmbracelet/bubbletea) and [Lipgloss](https://github.com/charmbracelet/lipgloss). Issue tracking was done with [beads](https://github.com/steveyegge/beads). ```bash # Run tests go test ./... # Build go build -o claude-esp . # Build with version injection go build -ldflags "-X main.version=0.4.0" -o claude-esp . ``` ## License MIT --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-242) · https://claudary.paisolsolutions.com