927ecb83fe
Bubble Tea TUI for tailing Claude Code subagent JSONL logs. Features: - Tabbed interface with one tab per agent, sorted by most recent activity - Markdown rendering via glamour (Dracula theme) - Session discovery and filtering with -s flag - Auto-discovers subagents dir from session ID prefix - Live tailing with follow mode, mouse scroll support - Agent name resolution from team config files - Tail-from-bottom: only reads last 200 lines per file on startup
107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# agent-tui — Implementation Plan
|
|
|
|
Go + Bubble Tea terminal UI for watching Claude Code subagent JSONL logs in real-time.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
agent-tui/
|
|
├── main.go # CLI entry, arg parsing, tea.NewProgram
|
|
├── model.go # Bubble Tea model: Init, Update, View
|
|
├── event.go # JSONL event structs + parser
|
|
├── watcher.go # fsnotify directory watcher + line tailer
|
|
├── render.go # Render events as styled terminal lines
|
|
└── styles.go # Lipgloss styles, agent color palette
|
|
```
|
|
|
|
## Layout: Tabbed View
|
|
|
|
```
|
|
┌─[ All ]─[ a39dd48 flickering-toasting-babbage ]─[ a91c770 ... ]──────┐
|
|
│ │
|
|
│ 16:57:14 a39dd48 ◀ TASK: Clean up backend root config files │
|
|
│ 16:57:16 a39dd48 💬 I'll start by reading all four files... │
|
|
│ 16:57:17 a39dd48 📖 Read ~/shopped-monorepo/.../package.json │
|
|
│ 16:57:17 a39dd48 ↩ result: .../package.json │
|
|
│ 16:57:18 a39dd48 ✏️ Edit ~/shopped-monorepo/.../package.json │
|
|
│ 16:57:48 a39dd48 📝 Write ~/shopped-monorepo/.../.env │
|
|
│ 16:58:21 a39dd48 🔧 SendMessage │
|
|
│ 16:58:24 a39dd48 💬 All four backend root config files done... │
|
|
│ │
|
|
│ 16:56:39 a91c770 ◀ TASK: Rename @claude-agent/shared → @shopped... │
|
|
│ 16:56:42 a91c770 💬 I'll work through this systematically... │
|
|
│ 16:56:43 a91c770 📖 Read ~/shopped-monorepo/.../package.json │
|
|
│ ... │
|
|
├────────────────────────────────────────────────────────────────────────┤
|
|
│ 2 agents │ 298 events │ Tab: switch │ f: follow │ q: quit │
|
|
└────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Input
|
|
|
|
**Mouse** (enabled via `tea.WithMouseCellMotion()`):
|
|
- Scroll wheel up/down to scroll the event stream
|
|
- Scrolling up automatically pauses follow mode
|
|
- Click a tab to switch to it
|
|
|
|
**Keyboard:**
|
|
|
|
| Key | Action |
|
|
|-----------|-------------------------------|
|
|
| 1-9 | Switch to agent tab N |
|
|
| 0 / a | Switch to "All" tab |
|
|
| ←/→ | Prev/next tab |
|
|
| j/k ↑/↓ | Scroll up/down |
|
|
| G / End | Jump to bottom + follow |
|
|
| g / Home | Jump to top |
|
|
| f | Toggle follow mode |
|
|
| p | Toggle showing progress events|
|
|
| t | Toggle showing token usage |
|
|
| q / Ctrl+C| Quit |
|
|
|
|
## Event Types Rendered
|
|
|
|
| Type | Icon | Detail shown |
|
|
|-----------------|------|-------------------------------------|
|
|
| User task msg | ◀ | Summary from teammate-message |
|
|
| Assistant text | 💬 | Truncated message text |
|
|
| Read | 📖 | File path |
|
|
| Write | 📝 | File path |
|
|
| Edit | ✏️ | File path |
|
|
| Grep | 🔍 | Pattern |
|
|
| Glob | 📂 | Pattern |
|
|
| Bash | ⚡ | Command (truncated) |
|
|
| Task | 🤖 | Description |
|
|
| SendMessage | 📨 | Recipient + summary |
|
|
| Other tool | 🔧 | Tool name |
|
|
| Tool result | ↩ | File path or size (dimmed) |
|
|
| Progress | (hidden by default, toggle with p) |
|
|
|
|
## Dependencies
|
|
|
|
- github.com/charmbracelet/bubbletea
|
|
- github.com/charmbracelet/lipgloss
|
|
- github.com/charmbracelet/bubbles (viewport)
|
|
- github.com/fsnotify/fsnotify
|
|
|
|
## Key Design Decisions
|
|
|
|
1. **Watcher as tea.Cmd**: File watcher runs in a goroutine, sends `EventMsg` via a channel that gets picked up by a `tea.Cmd` subscriber. New files detected via fsnotify trigger new tailers.
|
|
|
|
2. **Viewport for scrolling**: Use `bubbles/viewport` for the event stream. Auto-scroll when at bottom (follow mode). Pause auto-scroll when user scrolls up.
|
|
|
|
3. **Agent discovery**: Each agent gets assigned a color from a palette on first seen. Agent list is built dynamically from events.
|
|
|
|
4. **Home dir shortening**: Paths starting with $HOME are displayed as `~/...` for readability.
|
|
|
|
5. **Token usage**: Shown as dimmed line under assistant events (toggleable with `t`).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
agent-tui /path/to/subagents/
|
|
|
|
# Or from the subagents directory:
|
|
agent-tui .
|
|
```
|