anvil-dev-framework 0.1.6

package/docs/anvil-hud.md

@@ -0,0 +1,469 @@
+# Anvil HUD
+
+> Multi-agent command center for monitoring Claude Code sessions in real-time.
+
+---
+
+## Overview
+
+The Anvil HUD (Heads-Up Display) is a terminal dashboard that provides real-time visibility into all active Claude Code agents across your projects. It shows agent status, context usage, costs, task progress, and quality gate status—all in one place.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              ANVIL HUD                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  ┌─ Agents ─────────────┐  ┌─ Kanban ──────────────────────────────────────┐│
+│  │ swift-falcon-a3f2    │  │  TODO (3)      IN PROGRESS (2)    DONE (5)   ││
+│  │ ████████░░ 78%       │  │  ┌──────────┐  ┌──────────────┐  ┌─────────┐ ││
+│  │ ANV-180 | implement  │  │  │ ANV-182  │  │▸ANV-180     │  │ ANV-175 │ ││
+│  │ $2.34 | 14m ago      │  │  │ ANV-183  │  │ ANV-181     │  │ ANV-174 │ ││
+│  ├──────────────────────┤  │  │ ANV-184  │  │             │  │ ...     │ ││
+│  │ calm-raven-7b2e      │  │  └──────────┘  └─────────────┘  └─────────┘ ││
+│  │ ████░░░░░░ 45%       │  └────────────────────────────────────────────────┤
+│  │ ANV-181 | explore    │  ┌─ Quality ─────┐  ┌─ Costs ─────────────────────┐│
+│  └──────────────────────┘  │ Lint: ✓ Pass  │  │ Total: $4.78               ││
+│                            │ Types: ✓ Pass │  │ Agents: 2 active           ││
+│                            │ Tests: ✓ Pass │  │ Avg context: 61%           ││
+│                            └───────────────┘  └─────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+### Launch the HUD
+
+```bash
+# Start the dashboard
+uv run global/tools/anvil-hud.py
+
+# Start with demo data (for testing)
+uv run global/tools/anvil-hud.py --demo
+```
+
+### Recommended Setup
+
+Run the HUD in a split terminal pane alongside your Claude Code session:
+
+**Warp Terminal**
+1. Right-click → Split pane (or Cmd+D)
+2. Run `uv run global/tools/anvil-hud.py`
+
+**tmux**
+```bash
+tmux split-window -h
+uv run global/tools/anvil-hud.py
+```
+
+**iTerm2**
+1. Cmd+D (vertical split)
+2. Run the HUD command
+
+---
+
+## Display Modes
+
+### Focused Mode (Default)
+
+Shows one panel at a time with a tab bar for navigation. Best for:
+- Quick status checks
+- Single monitor setups
+- When you need maximum panel space
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ [Agents] [Kanban] [Quality] [Costs] [Coord]                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│                    Active Panel Content                         │
+│                    (full width display)                         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Full Mode
+
+Shows all panels simultaneously. Best for:
+- Multi-agent coordination
+- Wide monitor setups
+- Comprehensive overview
+
+Toggle between modes with the `m` key.
+
+---
+
+## Panels
+
+### 1. Agents Panel
+
+Displays all active Claude Code sessions with real-time status.
+
+**Agent Card Information:**
+
+| Field | Description |
+|-------|-------------|
+| Agent ID | Unique identifier (e.g., `swift-falcon-a3f2`) |
+| Context Bar | Visual usage indicator with color coding |
+| Issue | Current Linear/local issue being worked on |
+| Phase | Workflow phase (orient, explore, spec, plan, implement, etc.) |
+| Cost | Session cost (for API billing users) |
+| Last Activity | Time since last tool use |
+
+**Context Color Coding:**
+
+| Color | Usage | Meaning |
+|-------|-------|---------|
+| Green | < 50% | Healthy |
+| Yellow | 50-80% | Monitor |
+| Red | > 80% | At risk of compaction |
+
+**Detailed View** (press `d`):
+- Shows recent tool timeline (last 5 tools)
+- Tool execution durations
+- Helps debug slow operations
+
+### 2. Kanban Panel
+
+Visual task board showing issues organized by status.
+
+```
+┌─ KANBAN BOARD ──────────────────────────────────────────────────┐
+│ Navigation: h/l=columns  j/k=issues  c=claim  m/M=move  n=new   │
+│                                                                 │
+│  TODO (3)           IN PROGRESS (2)      DONE (5)              │
+│ ┌──────────────┐   ┌──────────────┐    ┌──────────────┐        │
+│ │ ANV-182      │   │▸ANV-180  🤖 │    │ ANV-175      │        │
+│ │ ANV-183      │   │ ANV-181     │    │ ANV-174      │        │
+│ │ ANV-184      │   │             │    │ ANV-173      │        │
+│ └──────────────┘   └──────────────┘    │ ANV-172      │        │
+│                                        │ ANV-171      │        │
+│                                        └──────────────┘        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Columns:**
+- **TODO** - Issues ready to start
+- **IN PROGRESS** - Currently being worked on
+- **DONE** - Completed issues
+
+**Issue Indicators:**
+- `!` - High priority (P0/P1)
+- `🤖` - Assigned to an agent
+
+**Kanban Keybindings:**
+
+| Key | Action |
+|-----|--------|
+| `h`/`l` | Move between columns |
+| `j`/`k` | Move between issues |
+| `c` | Claim selected issue |
+| `m` | Move issue right (TODO → IN PROGRESS → DONE) |
+| `M` | Move issue left |
+| `n` | Create new issue |
+| `Enter` | View issue details |
+
+### 3. Quality Panel
+
+Real-time quality gate status for the current project.
+
+```
+┌─ QUALITY GATES ─────────────────────────────────────────────────┐
+│                                                                 │
+│  Lint     ✓ Pass    (0 errors, 2 warnings)                     │
+│  Types    ✓ Pass    (no errors)                                │
+│  Tests    ✓ Pass    (47 passed, 0 failed)                      │
+│  Security ✓ Pass    (0 vulnerabilities)                        │
+│                                                                 │
+│  Last run: 2 minutes ago                                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Gates Tracked:**
+- **Lint** - ESLint/Ruff output
+- **Types** - TypeScript/mypy type checking
+- **Tests** - Vitest/pytest results
+- **Security** - Semgrep/CodeRabbit findings
+
+### 4. Costs Panel
+
+Session cost tracking and attribution.
+
+```
+┌─ COSTS ─────────────────────────────────────────────────────────┐
+│                                                                 │
+│  Total Session Cost:  $4.78                                     │
+│  Active Agents:       2                                         │
+│  Average Context:     61%                                       │
+│                                                                 │
+│  By Agent:                                                      │
+│    swift-falcon-a3f2   $2.34  (49%)                            │
+│    calm-raven-7b2e     $2.44  (51%)                            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Note**: Cost tracking is for API billing users. For Claude Pro/Max subscriptions, set `billing_model: subscription` to hide cost warnings.
+
+### 5. Coordination Panel
+
+Multi-agent coordination status.
+
+```
+┌─ COORDINATION ──────────────────────────────────────────────────┐
+│                                                                 │
+│  Active Agents: 2                                               │
+│  Potential Conflicts: 0                                         │
+│                                                                 │
+│  File Locks:                                                    │
+│    src/auth.ts       swift-falcon (write)                      │
+│    src/utils.ts      calm-raven (read)                         │
+│                                                                 │
+│  Branch Status:                                                 │
+│    feature/ANV-180   swift-falcon (active)                     │
+│    feature/ANV-181   calm-raven (active)                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Coordination Features:**
+- Active agent tracking
+- File lock detection
+- Branch ownership
+- Conflict warnings
+
+### 6. GitHub/CI Panel
+
+GitHub and CI pipeline status.
+
+```
+┌─ GITHUB/CI ─────────────────────────────────────────────────────┐
+│                                                                 │
+│  Open PRs: 2                                                    │
+│    #34  feat: statusline improvements     ✓ Checks passing     │
+│    #35  fix: auth timeout                 ⏳ Running            │
+│                                                                 │
+│  CodeRabbit:                                                    │
+│    #34: 3 comments, 0 blocking                                 │
+│    #35: Review pending                                          │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Keybindings
+
+### Global
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit HUD |
+| `r` | Force refresh |
+| `m` | Toggle Focused/Full mode |
+| `d` | Toggle detailed view |
+| `s` | Open settings panel |
+| `?` | Show help overlay |
+| `Esc` | Close any overlay |
+
+### Navigation (Focused Mode)
+
+| Key | Action |
+|-----|--------|
+| `1` | Switch to Agents panel |
+| `2` | Switch to Kanban panel |
+| `3` | Switch to Quality panel |
+| `4` | Switch to Costs panel |
+| `5` | Switch to Coordination panel |
+| `Tab` | Next panel |
+| `Shift+Tab` | Previous panel |
+
+### Kanban Navigation
+
+| Key | Action |
+|-----|--------|
+| `h`/`l` | Move between columns |
+| `j`/`k` | Move between issues |
+| `c` | Claim selected issue |
+| `m` | Move issue right |
+| `M` | Move issue left |
+| `n` | Create new issue |
+| `Enter` | View issue details |
+
+---
+
+## Configuration
+
+Settings are stored in `~/.anvil/hud-config.yaml` (global) or `.anvil/hud-config.yaml` (per-project):
+
+```yaml
+# Billing model
+budget:
+  billing_model: subscription  # "api" or "subscription"
+  agent_warn_threshold: 5.0    # Warn at $5 (api only)
+  agent_crit_threshold: 10.0   # Critical at $10 (api only)
+
+# Context thresholds
+context:
+  warn_threshold_pct: 80       # Yellow at 80%
+  crit_threshold_pct: 90       # Red at 90%
+
+# Display settings
+hud:
+  default_mode: focused        # "focused" or "full"
+  refresh_interval: 2          # Seconds between refreshes
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANVIL_BILLING_MODEL` | Set to `subscription` to hide cost alerts |
+| `ANVIL_HUD_MODE` | Default display mode (`focused` or `full`) |
+
+---
+
+## Setup Requirements
+
+### Agent Registration
+
+The HUD requires hooks to register agents. Add to your project's `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "session_start": [".claude/hooks/session_start.py --register-agent"],
+    "post_tool_use": [".claude/hooks/post_tool_use.py --update-agent"],
+    "stop": [".claude/hooks/stop.py --cleanup-agent"]
+  }
+}
+```
+
+### Using --with-hooks
+
+When initializing a new project with Anvil, use the `--with-hooks` flag to automatically set up HUD integration:
+
+```bash
+./scripts/init-project.sh /path/to/project --with-hooks
+```
+
+This creates symlinks to the framework hooks that handle agent registration.
+
+---
+
+## Issue Tracking Integration
+
+The HUD works with both Linear and local issue tracking:
+
+### With Linear
+
+If `.claude/linear.yaml` exists, the Kanban panel shows issues from your Linear team:
+
+```yaml
+# .claude/linear.yaml
+team_key: ANV
+team_id: 1cd0d0ff-8ff2-4548-8edd-936c7c143332
+```
+
+### With Local Issues
+
+If no Linear configuration exists, the HUD uses local JSON storage:
+
+```bash
+# Create local issues via CLI
+uv run global/tools/anvil-issue.py create --title "My task"
+
+# Issues stored in ~/.anvil/issues/index.json
+```
+
+See [Local Issue Tracking](local-issues.md) for complete documentation.
+
+---
+
+## Architecture
+
+### File Structure
+
+```
+~/.anvil/
+├── agents.json           # Lightweight registry (all agents)
+├── issues/
+│   └── index.json        # Local issue storage
+├── state/
+│   └── {agent-id}.json   # Detailed state per agent
+└── hud-config.yaml       # HUD configuration
+```
+
+### Data Flow
+
+```
+┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
+│  Claude Code    │─────▶│  Agent Registry │◀─────│   Anvil HUD     │
+│  (with hooks)   │      │  (agents.json)  │      │  (dashboard)    │
+└─────────────────┘      └─────────────────┘      └─────────────────┘
+         │                                                  │
+         ▼                                                  ▼
+┌─────────────────┐                              ┌─────────────────┐
+│  anvil-state    │                              │  Issue Provider │
+│  (.claude/)     │                              │  (Linear/Local) │
+└─────────────────┘                              └─────────────────┘
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `global/tools/anvil-hud.py` | Main HUD application |
+| `global/lib/agent_registry.py` | Registry management API |
+| `global/lib/issue_provider.py` | Issue provider abstraction |
+| `global/lib/local_provider.py` | Local JSON issue storage |
+| `global/lib/linear_provider.py` | Linear API adapter |
+
+---
+
+## Troubleshooting
+
+### No agents showing
+
+1. Verify hooks are configured in `.claude/settings.local.json`
+2. Check that hooks have `--register-agent` flag
+3. Ensure `~/.anvil/` directory exists and is writable
+4. Start a Claude Code session and run a command
+
+### Stale agents appearing
+
+1. Agents auto-cleanup after 30 minutes of inactivity
+2. Force refresh with `r` key
+3. Check if stop hook has `--cleanup-agent` flag
+4. Manually clear: `rm ~/.anvil/agents.json`
+
+### Context not updating
+
+1. Verify `post_tool_use` hook has `--update-agent` flag
+2. Check that Claude Code is sending context_window data
+3. Restart the HUD with `q` then relaunch
+
+### Kanban not loading issues
+
+1. Check if Linear is configured: `cat .claude/linear.yaml`
+2. For local issues, verify: `ls ~/.anvil/issues/`
+3. Check issue provider detection: run `/orient` and note provider
+
+### Cost tracking shows $0
+
+1. For subscription users, this is expected (costs not tracked)
+2. For API users, ensure hooks are capturing cost data
+3. Check `budget.billing_model` in config
+
+---
+
+## Related Documentation
+
+- [Local Issue Tracking](local-issues.md) - CLI for local issues
+- [Session Workflow](session-workflow.md) - Daily workflow patterns
+- [Command Reference](command-reference.md) - All Anvil commands
+- [Anvil Init](anvil-init.md) - Project initialization with hooks
+
+---
+
+*The HUD is designed for multi-agent visibility but works equally well for single-agent sessions.*