https://github.com/phiat/claude-esp
Stream Claude Code's hidden output (thinking, tool calls, subagents) to a separate terminal in real-time
https://github.com/phiat/claude-esp
agents claude go tui
Last synced: 3 months ago
JSON representation
Stream Claude Code's hidden output (thinking, tool calls, subagents) to a separate terminal in real-time
- Host: GitHub
- URL: https://github.com/phiat/claude-esp
- Owner: phiat
- License: mit
- Created: 2026-01-09T02:59:42.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T12:56:26.000Z (4 months ago)
- Last Synced: 2026-03-29T17:26:02.720Z (4 months ago)
- Topics: agents, claude, go, tui
- Language: Go
- Homepage:
- Size: 437 KB
- Stars: 83
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - claude-esp - Go-based TUI that streams Claude Code's hidden output (thinking, tool calls, subagents) to a separate terminal. Watch multiple sessions simultaneously, filter by content type, and track background tasks. Ideal for debugging or understanding what Claude is doing under the hood without interrupting your main session. (Alternative Clients ๐ฑ / General)
- awesome-openclaw-skills - claude-esp - based TUI that streams Claude Code's hidden output (thinking, tool calls, subagents) to a separat... | - | (Code & Developer Tools)
- awesome-claude-code-cn - claude-esp - ๅบไบ Go ็ TUI๏ผๅฐ Claude Code ็้่่พๅบ๏ผๆ่ใๅทฅๅ ท่ฐ็จใๅญไปฃ็๏ผๆตๅผไผ ่พๅฐๅ็ฌ็็ป็ซฏใๅๆถ่ง็ๅคไธชไผ่ฏ๏ผๆๅ ๅฎน็ฑปๅ่ฟๆปค๏ผๅนถ่ท่ธชๅๅฐไปปๅกใ้ๅธธ้ๅ่ฐ่ฏๆ็่งฃ Claude ๅจๅๅฐๅไปไน๏ผ่ไธไผไธญๆญๆจ็ไธปไผ่ฏใ (ๆฟไปฃๅฎขๆท็ซฏ ๐ฑ / ้็จ)
README
# claude-esp
[](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.
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
- **Session events** - Compaction boundaries, hook output, post-edit LSP diagnostics, and PR-link events surfaced inline
- **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
- **Per-agent context size** - Each Main/subagent row shows current context as a percentage of the model's max context window (`Main 18%`, `Explore 9%`). Denominator is the model's *max window* (1M for opus-4-7 / sonnet-4-6, 200k for haiku-4-5), **not** the auto-compact threshold
- **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`) |
| `-D` | Debug: surface raw `type:subtype` for every JSONL line type the parser would otherwise drop |
| `-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