agent-tui/PLAN.md

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

agent-tui /path/to/subagents/

# Or from the subagents directory:
agent-tui .