# 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 .
```