anvil-dev-framework 0.1.7 → 0.1.9

package/global/tools/README.md

@@ -176,3 +176,156 @@ uv run global/tools/anvil-hud.py
 **Context not updating**
 - Verify `post_tool_use.py` has `--update-agent` flag
 - Check that hook is receiving context_window data from Claude Code
+
+---
+
+## ralph-watch
+
+Live terminal monitor for Ralph autonomous execution sessions. Shows real-time progress, event stream, and Linear subtask status.
+
+### Usage
+
+```bash
+# Watch current directory session
+python3 global/tools/ralph-watch
+
+# Compact single-line display
+python3 global/tools/ralph-watch --compact
+
+# Custom state file location
+python3 global/tools/ralph-watch --state /path/to/.claude/ralph-state.json
+
+# Hide event stream
+python3 global/tools/ralph-watch --no-events
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `r` | Force refresh |
+| `e` | Toggle event stream |
+| `c` | Toggle compact mode |
+
+### Display Modes
+
+**Full Mode** (default)
+- Progress bar with completion percentage
+- Linear subtask status (if enabled)
+- Recent event stream
+- Warnings for circuit breaker and checkpoints
+
+**Compact Mode** (`--compact` or press `c`)
+- Single-line status display
+- Shows: task name, status, iteration, progress, duration
+- Ideal for embedding in tmux status bar
+
+### Features
+
+- **Real-time Updates**: 1-second polling of Ralph state file
+- **Progress Tracking**: Visual progress bar with subtask counts
+- **Linear Integration**: Shows Linear subtask completion status
+- **Event Stream**: Recent events with timestamps and icons
+- **Warning Indicators**: Circuit breaker and checkpoint alerts
+
+### Example Output
+
+```
+╔═══════════════════════════════════════════════════════════════════╗
+║ 🐺 Ralph Session Monitor                                          ║
+╠═══════════════════════════════════════════════════════════════════╣
+║ Task: Migration Task
+║ Status: RUNNING │ Iteration: 5 │ Duration: 12:34
+║ Progress: [================        ] 67% (4/6)
+╠───────────────────────────────────────────────────────────────────╣
+║ Linear Subtasks:
+║   ✅ ANV-101: Phase 1 Setup
+║   ✅ ANV-102: Core Implementation
+║   ⬜ ANV-103: Testing
+╠───────────────────────────────────────────────────────────────────╣
+║ Recent Events:
+║   ✅ 2026-01-17T17:30:00 subtask_complete
+║   🔄 2026-01-17T17:25:00 iteration_complete
+╠═══════════════════════════════════════════════════════════════════╣
+║ q:quit  r:refresh  e:events  c:compact                            ║
+╚═══════════════════════════════════════════════════════════════════╝
+```
+
+### Integration with Ralph
+
+The watcher reads from:
+- `.claude/ralph-state.json` - Current session state
+- `~/.anvil/events/current-session.jsonl` - Event stream
+
+Start the watcher in a split terminal while running Ralph:
+
+```bash
+# Terminal 1: Run Ralph
+while :; do cat PROMPT.md | npx @anthropic-ai/claude-code --print; done
+
+# Terminal 2: Watch progress
+python3 global/tools/ralph-watch
+```
+
+---
+
+## Ralph Notification System
+
+Additional tools for Ralph visibility:
+
+### ralph_notifier.py
+
+Dispatches notifications for Ralph events.
+
+```bash
+# Show current config
+python3 global/lib/ralph_notifier.py --config
+
+# Toggle notifications
+python3 global/lib/ralph_notifier.py --disable tts
+python3 global/lib/ralph_notifier.py --enable macos
+python3 global/lib/ralph_notifier.py --disable all
+
+# Test notifications
+python3 global/lib/ralph_notifier.py --test-macos "Test message"
+python3 global/lib/ralph_notifier.py --test-tts "Hello from Ralph"
+
+# Dispatch pending events
+python3 global/lib/ralph_notifier.py --dispatch
+```
+
+### ralph_webhooks.py
+
+Sends Ralph events to Slack/Discord webhooks.
+
+```bash
+# Test webhooks
+python3 global/lib/ralph_webhooks.py --test-slack $SLACK_WEBHOOK_URL
+python3 global/lib/ralph_webhooks.py --test-discord $DISCORD_WEBHOOK_URL
+
+# Dispatch to configured webhooks
+python3 global/lib/ralph_webhooks.py --dispatch
+```
+
+### ralph_api.py
+
+HTTP API server with SSE for real-time events.
+
+```bash
+# Start API server
+python3 global/api/ralph_api.py --port 8765
+
+# With API key authentication
+python3 global/api/ralph_api.py --api-key "your-secret-key"
+```
+
+**Endpoints:**
+- `GET /health` - Server health check
+- `GET /status` - Current session status
+- `GET /events` - SSE event stream
+- `GET /history` - Recent event history
+- `GET /sessions` - Past session summaries
+- `POST /control` - Control commands (stop)
+
+See `global/api/openapi.yaml` for full API documentation.

package/global/tools/anvil-hud.py

@@ -82,6 +82,13 @@ try:
 except ImportError:
     CodeRabbitService = None
 
+# ANV-277: CodeRabbit Metrics for weekly stats in HUD
+try:
+    from coderabbit_metrics import CodeRabbitMetrics, WeeklySummary
+except ImportError:
+    CodeRabbitMetrics = None
+    WeeklySummary = None
+
 try:
     from config_service import get_config, get_config_service, HUDConfig
 except ImportError:
@@ -290,12 +297,13 @@ class TaskPanel(Static):
 
 
 class QualityPanel(Static):
-    """Widget displaying quality gate status (ANV-103/104/105, ANV-111-115)."""
+    """Widget displaying quality gate status (ANV-103/104/105, ANV-111-115, ANV-277)."""
 
     agents: reactive[Dict[str, Any]] = reactive({})
     quality_results: reactive[Dict[str, Any]] = reactive({})
     github_status: reactive[Dict[str, Any]] = reactive({})  # ANV-111-113
     coderabbit_status: reactive[Dict[str, Any]] = reactive({})  # ANV-114-115
+    weekly_metrics: reactive[Dict[str, Any]] = reactive({})  # ANV-277: Weekly CR metrics
 
     def compose(self) -> ComposeResult:
         yield Static(id="quality-panel-content")
@@ -316,6 +324,10 @@ class QualityPanel(Static):
         """Update display when CodeRabbit status changes."""
         self._refresh_display()
 
+    def watch_weekly_metrics(self, metrics: Dict[str, Any]) -> None:
+        """Update display when weekly metrics change (ANV-277)."""
+        self._refresh_display()
+
     def _refresh_display(self) -> None:
         """Refresh the quality panel display."""
         content = self.query_one("#quality-panel-content", Static)
@@ -478,6 +490,43 @@ class QualityPanel(Static):
 
             text.append("\n")
 
+        # ANV-277: CodeRabbit Weekly Metrics Summary
+        if self.weekly_metrics:
+            text.append("─" * 36 + "\n", style="dim")
+            text.append("CODERABBIT WEEKLY\n", style="bold cyan")
+
+            total_reviews = self.weekly_metrics.get("total_reviews", 0)
+            total_issues = self.weekly_metrics.get("total_issues_found", 0)
+            total_fixed = self.weekly_metrics.get("total_issues_fixed", 0)
+            avg_issues = self.weekly_metrics.get("avg_issues_per_review", 0)
+            pass_rate = self.weekly_metrics.get("pass_rate", 0)
+            trend = self.weekly_metrics.get("trend", "stable")
+
+            text.append(f"  Reviews: ", style="dim")
+            text.append(f"{total_reviews}\n", style="white")
+
+            text.append(f"  Issues: ", style="dim")
+            text.append(f"{total_issues} found", style="yellow" if total_issues > 0 else "green")
+            text.append(f" / {total_fixed} fixed\n", style="green" if total_fixed > 0 else "dim")
+
+            text.append(f"  Avg/Review: ", style="dim")
+            avg_color = "green" if avg_issues < 2 else "yellow" if avg_issues < 5 else "red"
+            text.append(f"{avg_issues:.1f}\n", style=avg_color)
+
+            text.append(f"  Pass Rate: ", style="dim")
+            pass_color = "green" if pass_rate >= 50 else "yellow" if pass_rate >= 25 else "red"
+            text.append(f"{pass_rate:.0f}%\n", style=pass_color)
+
+            text.append(f"  Trend: ", style="dim")
+            if trend == "improving":
+                text.append("↑ improving\n", style="green")
+            elif trend == "degrading":
+                text.append("↓ degrading\n", style="red")
+            else:
+                text.append("→ stable\n", style="dim")
+
+            text.append("\n")
+
         # Summary
         text.append("─" * 36 + "\n", style="dim")
         ready_count = sum(1 for r in self.quality_results.values() if r.get("ready_to_merge"))
@@ -2377,6 +2426,7 @@ class AnvilHUD(App):
         self.coordination_service: Optional["CoordinationService"] = None
         self.github_service: Optional["GitHubService"] = None  # ANV-111-113
         self.coderabbit_service: Optional["CodeRabbitService"] = None  # ANV-114-115
+        self.coderabbit_metrics: Optional["CodeRabbitMetrics"] = None  # ANV-277: Weekly metrics
         self.issue_provider = None  # ANV-76: Issue provider for Kanban
         self.refresh_timer: Optional[Timer] = None
 
@@ -2393,6 +2443,12 @@ class AnvilHUD(App):
         if not self.demo_mode and CodeRabbitService:
             if not self.config or self.config.integrations.enable_coderabbit:
                 self.coderabbit_service = CodeRabbitService()
+        # ANV-277: Initialize CodeRabbit metrics for weekly stats
+        if not self.demo_mode and CodeRabbitMetrics:
+            try:
+                self.coderabbit_metrics = CodeRabbitMetrics()
+            except Exception:
+                self.coderabbit_metrics = None
         # ANV-76: Initialize issue provider
         if not self.demo_mode and get_provider:
             try:
@@ -2731,6 +2787,24 @@ class AnvilHUD(App):
                 quality_panel.github_status
             )
 
+        # ANV-277: Update CodeRabbit weekly metrics
+        if self.demo_mode:
+            quality_panel.weekly_metrics = self._get_demo_weekly_metrics()
+        elif self.coderabbit_metrics:
+            try:
+                summary = self.coderabbit_metrics.get_weekly_summary()
+                if summary:
+                    quality_panel.weekly_metrics = {
+                        "total_reviews": summary.total_reviews,
+                        "total_issues_found": summary.total_issues_found,
+                        "total_issues_fixed": summary.total_issues_fixed,
+                        "avg_issues_per_review": summary.avg_issues_per_review,
+                        "pass_rate": summary.pass_rate,
+                        "trend": summary.trend,
+                    }
+            except Exception:
+                pass  # Keep previous metrics on error
+
         # Update coordination panel (ANV-106-110)
         coordination_panel = self.query_one("#coordination-panel", CoordinationPanel)
         coordination_panel.agents = agents
@@ -3422,6 +3496,17 @@ class AnvilHUD(App):
             },
         }
 
+    def _get_demo_weekly_metrics(self) -> Dict[str, Any]:
+        """Generate demo CodeRabbit weekly metrics for testing (ANV-277)."""
+        return {
+            "total_reviews": 12,
+            "total_issues_found": 28,
+            "total_issues_fixed": 24,
+            "avg_issues_per_review": 2.3,
+            "pass_rate": 42.0,
+            "trend": "improving",
+        }
+
     def _get_demo_agents(self) -> Dict[str, Any]:
         """Generate demo agent data for testing."""
         now = datetime.now(timezone.utc).isoformat()