⚡ Vigil

Your PRs Never Sleep. Neither Does Vigil.

_{AI-powered PR lifecycle management for the terminal}

Why Vigil? · Features · Agents · Quick Start · Dashboard · Configuration · Contributing

---

👁️ The Problem

The PR lifecycle is death by a thousand interrupts. Push code, wait for CI, read reviews, fix nits, push again, update descriptions, fill in verification evidence, respond to comments, request re-review. Repeat until merge or madness.

Vigil watches your pull requests so you don't have to.

It monitors every open PR across all your repos, classifies their state in real-time, and dispatches AI agents to handle the mechanical work — fixing review feedback, rebasing branches, responding to comments, filling in evidence templates. You stay in flow. Vigil keeps the watch.

🗡️ What You Get

	Capability	Description
🔴	Real-Time State Machine	5 states — hot, waiting, ready, dormant, blocked — updated live as GitHub signals change
🤖	6 Specialized Agents	Triage, Fix, Respond, Rebase, Evidence, Learning — in-process via Claude SDK, no external services
🎯	HITL + YOLO Modes	Approve every action, or let confident ones auto-execute. Toggle with y anytime
🖥️	SilkCircuit TUI	Card-based dashboard, scrollable detail view, action panel — Ink 6 + React 19
🔔	Desktop Alerts	CI failures, blocking reviews, conflicts — click to open the PR. Non-intrusive by default
🧠	Post-Merge Learning	Captures reviewer patterns, common fixes, response templates — gets smarter every merge
🔍	Fuzzy Search	/ to filter PRs instantly across titles, repos, branches, authors
🌊	Smart Polling	Two-pass fetch with updatedAt short-circuit — skips repos where nothing changed

🚦 How It Works

Push code
  → Vigil detects new/updated PR
  → Triage agent reads ALL signals (CI, reviews, conflicts, templates)
  → Action agents dispatch IN PARALLEL
    ├── 🔧 Fix patches code from review feedback
    ├── 💬 Respond replies to reviewers, pushes back on scope creep
    ├── 📋 Evidence fills verification sections
    └── 🔀 Rebase resolves conflicts with main
  → Fix pushes commit → triggers new CI → loop continues
  → PR reaches READY → you merge
  → Learning agent captures patterns for next time

Every PR is classified into one of five states:

State	Meaning	What Triggers It
🔴 Hot	Needs attention now	Failing CI, blocking reviews, merge conflicts
🟡 Waiting	Ball is elsewhere	Reviews pending, CI running
🟢 Ready	Ship it	All checks pass, approved, no conflicts
⚪ Dormant	Gone quiet	No activity in 48h+
🟣 Blocked	Can't proceed	Draft, policy block, dependency

🤖 Agents

Six agents. Each does one thing well.

Agent	Model	What It Does
🔍 Triage	Haiku	First responder — classifies events, decides which agents to wake up
🔧 Fix	Sonnet	Reads review feedback + CI logs, applies code fixes, pushes commits
💬 Respond	Sonnet	Drafts contextual replies, defends scope, requests re-review
🔀 Rebase	Sonnet	Rebases onto latest base, resolves conflicts intelligently
📋 Evidence	Haiku	Fills verification/regression evidence in PR templates
🧠 Learning	Haiku	Extracts patterns post-merge — feeds forward into future triage

All agents run in-process via the Claude Agent SDK. No subprocesses, no external services, no containers. Git operations are scoped to worktrees for safety.

📦 Installation

Prerequisites

• Bun >= 1.1.0
• GitHub CLI (gh) — authenticated
• ANTHROPIC_API_KEY environment variable
• (Optional) terminal-notifier for click-to-open notifications on macOS

From Source

git clone https://github.com/hyperb1iss/vigil.git
cd vigil
bun install
bun run build
bun run link  # Symlinks to ~/.local/bin/vigil

🚀 Quick Start

vigil                                    # All your PRs, all repos
vigil --repo owner/repo                  # Focus on one repo
vigil --repo owner/repo --repo org/lib   # Multiple repos
vigil --mode yolo                        # Auto-execute confident actions
vigil --no-agents                        # Dashboard only, no AI
vigil --demo                             # Mock data for visual testing

🖥️ The Dashboard

Built with Ink and the SilkCircuit Neon design language. Cards, colors, vim motions, mouse support.

⌨️ Keybindings

Navigation

Key	Action
↑↓←→ / hjkl	Navigate PRs
Tab / Shift+Tab	Next / previous
Enter	Open detail view
Esc	Back
/	Search
g / G	Top / bottom
o	Open in browser

Controls

Key	Action
v	Cards ↔ list
s	Sort: activity ↔ state
y	HITL ↔ YOLO
r	Force refresh
?	Help overlay
q	Quit

Detail View — j/k scroll, Tab pages, a opens actions, o or click opens PR in browser.

Action Panel — 1-9 approve, a approve all, n skip.

🎭 Modes

🛡️ HITL — The default. Every agent action shows up in the action panel first. You approve with a keypress. Nothing happens without your say-so.

🚀 YOLO — Confident actions auto-execute. Uncertain ones still pause. Destructive operations (force push, merge, close, delete branch) always require confirmation — even in YOLO.

Toggle anytime with y.

🔔 Notifications

Lightweight desktop alerts for the things that actually matter:

Event	Desktop Alert
🔴 CI failure	✅
🔴 Changes requested	✅
🔴 Merge conflict	✅
🟡 Ready to merge	—
⚪ New comment	—

Click a notification → opens the PR in your browser. First-poll alerts are suppressed so you don't get blasted on startup.

{
  "notifications": {
    "enabled": true,
    "onCiFailure": true,
    "onBlockingReview": true,
    "onReadyToMerge": true,
    "onNewComment": false
  }
}

⚙️ Configuration

Path	Purpose
$XDG_CONFIG_HOME/vigil/config.json	Global config
$XDG_DATA_HOME/vigil/knowledge.md	Learning knowledge base
$XDG_CACHE_HOME/vigil/	Poll cache + snapshots
.vigilrc.json	Per-repo overrides

.vigilrc.ts execution is disabled by default for safety. Enable it explicitly with VIGIL_ALLOW_TS_CONFIG=1.

🧠 Learning

The Learning agent captures patterns from every merged PR — reviewer tendencies, common CI failure fixes, response templates. Stored as human-readable markdown. Edit it, seed it, or let it grow.

🏗️ Architecture

gh search prs --author=@me --state=open
  → Poller (30s, updatedAt short-circuit)
    → Differ (snapshot → granular events)
      → State Machine (5 states)
        → Zustand Store → Ink TUI
        → Orchestrator → Agents (parallel)
          → Desktop notifications

Layer	Stack
Runtime	Bun
TUI	Ink 6 + React 19
AI	Claude Agent SDK
State	Zustand vanilla
GitHub	gh CLI
Git	simple-git
Lint	Biome 2
Types	TypeScript 5.9 strict

🛠️ Development

bun run dev          # Watch mode
bun run build        # Bundle to dist/
bun run check        # Typecheck + lint + test
bun run lint:fix     # Auto-fix
bun test             # 166 tests, 95% coverage
bun run typecheck    # Types only

🤝 Contributing

Contributions welcome! Run bun run check before submitting.

1. Fork it
2. Branch it (git checkout -b feat/amazing-thing)
3. Conventional commit it
4. PR it

⚖️ License

Apache 2.0 — use it, extend it, build on it.

---

  

<sub>If Vigil is keeping watch, give it a ⭐ or buy me a Monster Ultra Violet ⚡️

✦ Built with obsession by Hyperbliss Technologies ✦</sub>