anvil-dev-framework 0.1.6

package/global/tools/README.md

@@ -0,0 +1,178 @@
+# Anvil Tools
+
+Global tools that enhance the Anvil development workflow.
+
+## anvil-hud.py
+
+Terminal dashboard for multi-agent Claude Code visibility. Shows all active Claude Code agents across all projects in real-time.
+
+### Usage
+
+```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
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `r` | Force refresh |
+| `d` | Toggle detailed view (shows tool timeline) |
+| `s` | Open settings panel |
+| `?` | Show help overlay |
+| `m` | Toggle between Focused/Full mode |
+| `1-5` | Jump to panel (Agents/Kanban/Quality/Costs/Coord) |
+| `Tab` | Next panel (in Focused Mode) |
+| `Shift+Tab` | Previous panel (in Focused Mode) |
+| `Esc` | Close any overlay |
+
+### Display Modes (HUD v3)
+
+**Focused Mode** (default)
+- Shows one panel at a time, full-width
+- Tab bar shows available panels
+- Best for quick status checks
+
+**Full Mode**
+- Shows all panels simultaneously
+- Traditional multi-panel overview
+- Best for multi-agent coordination
+
+Toggle with `m` key. Mode persists via config.
+
+### Features
+
+**Agent Cards**
+- Real-time status indicators (active/idle)
+- Project name and Linear issue context
+- Model info (Opus, Sonnet, Haiku)
+- Context usage bar with color coding (green <50%, yellow <80%, red >80%)
+- Current workflow phase
+- Session cost tracking
+- Last activity timestamp
+
+**Detailed View** (press `d`)
+- Recent tool timeline (last 5 tools)
+- Tool execution durations when available
+- Auto-refreshes with main display
+
+**Aggregate Panel**
+- Active agent count
+- "At Risk" count (agents >80% context)
+- Total cost across all sessions
+- Average context usage
+- Phase breakdown (when multiple agents)
+
+**Notifications**
+- Warning at 80% context usage
+- Critical alert at 90% context usage
+- One-time per agent per threshold (not spammy)
+
+### Setup
+
+The HUD requires agent registration via hooks. Add these to your project's `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "session_start": [".claude/hooks/session_start.py --load-context --register-agent"],
+    "post_tool_use": [".claude/hooks/post_tool_use.py --update-agent"],
+    "stop": [".claude/hooks/stop.py --cleanup-agent"]
+  }
+}
+```
+
+Copy the hook files from `project/hooks/` to your project's `.claude/hooks/` directory.
+
+### Configuration
+
+HUD settings are stored in `~/.anvil/hud-config.yaml` (global) or `.anvil/hud-config.yaml` (per-project):
+
+```yaml
+# Billing model: "api" (pay-per-use) or "subscription" (Pro/Max)
+# When "subscription", cost alerts are disabled
+budget:
+  billing_model: subscription  # or "api" for pay-per-use
+  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
+  crit_threshold_pct: 90
+
+# Display mode
+hud:
+  default_mode: focused  # or "full"
+```
+
+**Environment Variables**:
+- `ANVIL_BILLING_MODEL=subscription` — Disable cost alerts for Pro/Max users
+- `ANVIL_HUD_MODE=focused` — Default display mode
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `budget.billing_model` | `api` | `api` (pay-per-use) or `subscription` (Pro/Max) |
+| `budget.agent_warn_threshold` | `5.0` | Cost warning threshold ($) |
+| `budget.agent_crit_threshold` | `10.0` | Cost critical threshold ($) |
+| `context.warn_threshold_pct` | `80` | Context warning (%) |
+| `context.crit_threshold_pct` | `90` | Context critical (%) |
+| `hud.default_mode` | `focused` | Default display mode |
+
+Legacy settings in `.claude/anvil.config.json` are still supported for backward compatibility.
+
+### Architecture
+
+The HUD uses a shared registry at `~/.anvil/agents.json` that all Claude Code sessions can write to:
+
+```
+~/.anvil/
+├── agents.json         # Lightweight registry (all agents)
+└── state/
+    └── {agent-id}.json # Detailed state per agent
+```
+
+**Files:**
+- `global/lib/agent_registry.py` - Registry management API
+- `global/tools/anvil-hud.py` - TUI dashboard
+- `project/hooks/*.py` - Integration hooks
+
+### Recommended Setup
+
+Run the HUD in a split terminal pane:
+
+**Warp**
+1. Right-click → Split pane
+2. Run `uv run global/tools/anvil-hud.py`
+
+**tmux**
+```bash
+# Split vertically
+tmux split-window -h
+uv run global/tools/anvil-hud.py
+```
+
+**iTerm2**
+1. Cmd+D (vertical split)
+2. Run the HUD command
+
+### Troubleshooting
+
+**No agents showing**
+- Verify hooks are configured in `.claude/settings.local.json`
+- Check that hooks have `--register-agent` and `--update-agent` flags
+- Ensure `~/.anvil/` directory exists and is writable
+
+**Stale agents appearing**
+- Agents auto-cleanup after 30 minutes of inactivity
+- Force refresh with `r` key
+- Check if hooks have `--cleanup-agent` on stop
+
+**Context not updating**
+- Verify `post_tool_use.py` has `--update-agent` flag
+- Check that hook is receiving context_window data from Claude Code