Vigil

🧭 vigil · Features · Roadmap · Tasks · Changelog · Metrics

Last Updated: 2026-09-30

Meta-Repository Intelligence Layer A dashboard that gives you and your AI agents a unified view across all your GitHub repositories.

Mission Statement

Vigil bridges human intent and AI execution through enforced documentation standards (ROADMAP, TASKS, METRICS, FEATURES).

Key Outcomes:

Standardized Context: Every repo provides necessary context for immediate contribution
Visible Momentum: Track velocity from strategy to shipped code
Automated Governance: AI maintains documentation health without blocking workflow

Features

📊 Repository Intelligence - Health scoring against Starter / Production / Enterprise profiles, doc tracking, activity monitoring
🏷️ Repo Tiers - Tag each repo T1 (Critical) → T4 (Low) from a badge next to its type icon; filter the dashboard and MCP list_repos by tier
🤖 AI Automation - Gemini-powered summaries, failover, and context-aware doc generation with multi-stage RAG
🔧 One-Click Fixes - PR creation for docs, 10 best practices, 12 community standards
🎯 Interactive Onboarding - 16-step guided tour with spotlight highlighting
🔗 GitHub Integration - OAuth auth, full metadata sync, rate limit monitoring, custom repo paths
📈 Composite Metrics - Testing (60%+ coverage), vulnerabilities, contributor analytics
💬 Per-Repo Chat - Ask a repo what to work on next; the chat can propose doc edits and task check-offs, each applied as a PR
🧠 Claude Code Skill - skills/vigil/ teaches Claude when and how to use Vigil's MCP tools and how to keep TASKS/ROADMAP/FEATURES parseable
🤝 MCP Server - JSON-RPC 2.0 endpoint exposing 10 tools for agent clients (get_open_tasks, get_relationships, propose_relationship, get_repo_health, list_repos, get_repo_details, get_portfolio_overview, search_repos, list_tasks, get_security_summary); connect Claude Code via docs/MCP.md
📱 Mobile Dashboard - Responsive card layout for all screen sizes
🗂️ PMO Mode - Portfolio-wide roadmap progress, plan execution, and DEV-flow handoff at /pmo

Screenshots & diagrams

Regenerated by CI (visual-docs recipe) from the DB-free Playwright suite and docs/diagrams/*.mmd.

Diagrams

Architecture — docs/diagrams/architecture.svg · source docs/diagrams/architecture.mmd

Screenshots

Dashboard — docs/screenshots/dashboard.png

Pmo — docs/screenshots/pmo.png

Repo details — docs/screenshots/repo-details.png

Use it from Claude Code

Connect the MCP server (docs/MCP.md):

claude mcp add --transport http --scope user vigil https://YOUR-VIGIL-HOST/api/mcp --header "Authorization: Bearer $VIGIL_MCP_KEY"

Install the skill so Claude knows when to reach for it ("what should I work on next?", "what depends on this repo?", closing tracked work in the same PR):

mkdir -p ~/.claude/skills/vigil
curl -fsSL https://raw.githubusercontent.com/nitsuah/vigil/main/skills/vigil/SKILL.md -o ~/.claude/skills/vigil/SKILL.md
curl -fsSL https://raw.githubusercontent.com/nitsuah/vigil/main/skills/vigil/reference.md -o ~/.claude/skills/vigil/reference.md

Or, from a clone, copy skills/vigil/ into ~/.claude/skills/ (user-wide) or a project's .claude/skills/.

The skill covers tool selection, the core workflows (triage, cross-repo changes, finishing tracked work), the TASKS.md / ROADMAP.md / FEATURES.md formats the parsers expect, tiers vs. health profiles, and common failure modes.

Repo Tiers

Tiers are a user-assigned importance label, separate from the auto-detected type and from the health profile:

Tier	Label	Use for
T1	Critical	Production / revenue-bearing; fix regressions first
T2	Important	Actively used and maintained
T3	Standard	Useful but not urgent
T4	Low	Experiments, side projects, archives-in-waiting

Click the tier badge next to a repo's type icon (dashed T– when unset) to set or clear it. It is stored per repo (repos.tier), shown on desktop rows and mobile cards, filterable in the filter bar (including "Untiered"), and returned by MCP list_repos / get_repo_health and GET /api/context. Changing it requires a write grant on the repo, like the health profile.

Tech Stack

Frontend: Next.js 16 + React 19 + TypeScript + Tailwind CSS 4
Backend: Netlify Functions (serverless)
Database: Neon Postgres (serverless)
Auth: NextAuth v5 with GitHub OAuth
APIs: GitHub REST API via Octokit, Google Gemini, OpenAI, Anthropic
Testing: Vitest + Playwright E2E

Getting Started

Prerequisites

Node.js 22.x
GitHub OAuth App (for authentication)
Neon Postgres database (free tier)
Google Gemini API key (optional, for AI summaries)

Installation

# Clone the repo
git clone https://github.com/nitsuah/vigil.git
cd vigil

# Install dependencies
npm install

# Set up environment variables (see CONTRIBUTING.md for details)
cp .env.example .env.local
# Edit .env.local with your credentials

# Setup database
npm run setup-db

# Run development server
npm run dev

What’s New

See CHANGELOG.md for recent updates and version history

Quick Links

Project page (30s launch video, built from promo/)
Live Dashboard
Docs
GitHub

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines. Please:

Fork the repo and create a feature branch
Add or improve tests for new features
Run all tests and ensure coverage does not decrease
Open a pull request with a clear description and screenshots if UI changes

For detailed setup instructions, see CONTRIBUTING.md

Docker Validation

# Build the production image without injecting real secrets
docker build -t vigil-devops-check .

# Run unit tests in the test container
docker compose -f config/docker-compose.test.yml run --rm test

# Run unit coverage in the test container
docker compose -f config/docker-compose.test.yml run --rm coverage

Environment Variables

# GitHub OAuth
GITHUB_ID=your_github_oauth_client_id
GITHUB_SECRET=your_github_oauth_client_secret

# NextAuth
NEXTAUTH_SECRET=your_random_secret
NEXTAUTH_URL=http://localhost:3000

# Neon Database (get from Neon console or Netlify)
DATABASE_URL=postgresql://user:pass@host/db

# Google Gemini (optional - for AI summaries)
GEMINI_API_KEY=your_gemini_api_key

# Optional model override
GEMINI_MODEL_NAME=models/gemini-2.5-flash

# Optional fallbacks
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4-turbo-preview
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-sonnet-5

# Optional BYOK overrides (preferred when set)
BYOK_GEMINI_API_KEY=your_user_gemini_key
BYOK_OPENAI_API_KEY=your_user_openai_key
BYOK_ANTHROPIC_API_KEY=your_user_anthropic_key

# Optional provider routing controls
AI_PROVIDER_ORDER=gemini,openai,anthropic
AI_DEPRIORITIZE_GEMINI_ON_QUOTA=true
GEMINI_QUOTA_EXCEEDED=false

# MCP server auth (required for POST /api/mcp)
MCP_API_KEY=your_random_mcp_secret

# GitHub webhook validation (required for POST /api/webhooks/github)
WEBHOOK_SECRET=your_github_webhook_secret

# Optional Netlify
NETLIFY_SITE_ID=
NETLIFY_AUTH_TOKEN=

Project Structure

vigil/
├── app/                    # Next.js app directory
│   ├── page.tsx           # Main dashboard
│   ├── api/               # API routes
│   │   ├── repos/         # Repo management endpoints
│   │   └── sync-repos/    # Sync trigger endpoint
│   └── login/             # Auth pages
├── components/            # React components
├── lib/                   # Shared utilities
│   ├── parsers/          # MD file parsers (roadmap, tasks, metrics)
│   ├── github.ts         # GitHub API client
│   ├── db.ts             # Neon database client
│   ├── ai.ts             # Google Gemini integration
│   └── sync.ts           # Repository sync logic
├── netlify/functions/    # Serverless API endpoints
│   └── sync-repos.ts     # Background sync job
├── templates/            # MD file templates
└── database/            # Database schema & migrations

Standardized MD Files

Vigil expects repos to have these files for full functionality:

README.md - Project overview and setup instructions
ROADMAP.md - High-level objectives and quarterly plans
TASKS.md - Granular task tracking with status
METRICS.md - Test coverage and performance metrics
FEATURES.md - Features organized by category with descriptions
LICENSE.md - Project license
CHANGELOG.md - Version history
CONTRIBUTING.md - Contribution guidelines

See /templates for examples with AI agent instructions.

Health Score

Vigil calculates a composite 0–100 score against a selectable repository maturity profile:

Starter — core hygiene for personal projects, prototypes, and small open-source repos.
Production — balanced expectations for actively deployed or maintained software.
Enterprise — stricter security, governance, testing, and engineering expectations.

The default profile is Production. The profile changes the relative weight of each component rather than inventing arbitrary penalties, while security now measures both control enablement and open findings. A repository with zero reported alerts does not receive a perfect security score when its detection controls are disabled.

Component	Starter	Production	Enterprise	What It Measures
Security	15%	25%	30%	Security controls plus critical/high/code-scanning/secret findings
Testing & Quality	15%	20%	20%	Test framework, coverage, and CI state
Best Practices	20%	20%	20%	CI/CD, pre-commit, linting, branch protection, Docker, Dependabot, etc.
Documentation Health	25%	15%	10%	Presence and health of tracked project docs
Community Standards	5%	10%	15%	Community and contribution standards
Activity & Engagement	20%	10%	5%	Maintenance cadence, open issues, and PR backlog

The health breakdown includes a Starter / Production / Enterprise picker. Changing the profile persists it for the repository and immediately recalculates the score. Scores are displayed as letter grades (A–F) with per-component breakdowns in the detail panel. See FEATURES.md for full details.

API Endpoints

Repository Management

# Get all repositories
GET /api/repos

# Get repository details (tasks, roadmap, docs, practices)
GET /api/repo-details/[name]

# Add a custom repository
POST /api/repos/add
{ "url": "owner/repo" | "https://github.com/owner/repo" }

# Sync a single repository
POST /api/repos/[name]/sync

# Sync all repositories
POST /api/sync-repos

# Hide / restore a repository
POST /api/repos/[name]/hide
POST /api/repos/[name]/unhide

# Per-repo settings (write grant required for tier/profile)
PATCH /api/repos/[name]/update-type            { "type": "web-app" | "game" | "tool" | "library" | "bot" | "research" | "unknown" }
PATCH /api/repos/[name]/update-tier            { "tier": "T1" | "T2" | "T3" | "T4" | null }
PATCH /api/repos/[name]/update-health-profile  { "profile": "starter" | "production" | "enterprise" }

# Health-score / velocity trend for the sparkline
GET /api/repo-details/[name]/trend?fullName=owner/repo

# Fix missing documentation (single file)
POST /api/repos/[name]/fix-doc
{ "docType": "readme" | "roadmap" | "tasks" | "metrics" | "features" | "license" | "changelog" | "contributing" }

# Fix all missing documentation
POST /api/repos/[name]/fix-all-docs

# Fix a best practice or community standard
POST /api/repos/[name]/fix-best-practice
POST /api/repos/[name]/fix-all-practices
POST /api/repos/[name]/fix-all-standards

# Fix a security control (e.g. SECURITY.md, Dependabot)
POST /api/repos/[name]/fix-security

# AI assists
POST /api/repos/[name]/generate-summary
POST /api/repos/[name]/improve-doc        # AI rewrite of an existing doc, previewed as a diff
POST /api/repos/[name]/suggest-features
POST /api/repos/[name]/suggest-roadmap
POST /api/repos/[name]/chat               # per-repo chat (sign-in required)
POST /api/repos/[name]/tasks              # apply a chat task proposal as a PR
PATCH /api/repos/[name]/roadmap-items/[id] # link a roadmap item to a PR / agent task

# Bring-your-own AI key (encrypted at rest)
GET | POST | DELETE /api/settings/ai-key

# AI provider health (?probe=true for a reachability check)
GET /api/health

# Real-time sync event stream
GET /api/repos/[name]/events  # SSE stream

# GitHub webhook (push events → auto-sync)
POST /api/webhooks/github

AI Context & MCP

# LLM-optimized context dump for agent consumption (no auth = default repos; Bearer = full)
GET /api/context
GET /api/context?repo=owner/repo

# MCP capability discovery (no auth required)
GET /api/mcp

# MCP JSON-RPC 2.0 handler (Bearer: MCP_API_KEY)
POST /api/mcp
# Tools: get_repo_health, list_repos, get_repo_details,
#        get_portfolio_overview, search_repos, list_tasks, get_security_summary,
#        get_open_tasks, get_relationships, propose_relationship

Agent Task Queue

See docs/AGENT_TASK_QUEUE_API.md for the full contract.

# Submit a new agent task
POST /api/agent/tasks
{ "type": "string", "payload": { ... }, "priority": "normal" }

# Poll task status / retrieve result
GET /api/agent/tasks/[id]

PMO

# Portfolio-wide roadmap and plan execution overview
GET /api/pmo/overview

# Cross-repo open-task rollup (same filters as get_open_tasks)
GET /api/pmo/tasks?priority=P0,P1&repos=vigil

# Cross-repo relationship map (session-scoped)
GET    /api/relationships
POST   /api/relationships       { source, target, kind, context, evidence? } | { relationships: [...] }
PATCH  /api/relationships/[id]  { confirm?: true, context?, evidence? }
DELETE /api/relationships/[id]

Deployment

Deploy to Netlify:

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod

Docs Index

Every committed Markdown doc in this repo (other than this README, .github/ and templates/), the same set mirrored into the Obsidian vault, so none of them is orphaned.

docs/

Agent Task Queue API — docs/AGENT_TASK_QUEUE_API.md
Overseer Feature Audit — docs/AUDIT.md
Vigil MCP server — docs/MCP.md
Testing Improvement Strategy Prompt — docs/TESTING_STRATEGY_PROMPT.md
Visual docs: diagrams and screenshots that stay current — docs/VISUAL_DOCS.md
DB Scaling Assessment — docs/db-scaling-assessment.md

docs/archive/

Handoff: Agent Task Queue Execution (2026-04-03) — docs/archive/HANDOFF-agent-task-queue-execution-20260403.md
HANDOFF-byok-quota-provider-fallback-20260411 — docs/archive/HANDOFF-byok-quota-provider-fallback-20260411.md

repo root

Vigil Features — FEATURES.md
🗺️ Vigil Roadmap — ROADMAP.md
Tasks — TASKS.md
Changelog — CHANGELOG.md
Metrics — METRICS.md
This is NOT the Next.js you know — AGENTS.md
CLAUDE — CLAUDE.md

database/migrations/

Migration history (frozen) — database/migrations/README.md

promo/

Promo spots — promo/README.md

promo/brag-30s/

brag-30s — storyboard — promo/brag-30s/storyboard.md

skills/vigil/

Vigil — skills/vigil/SKILL.md
Vigil reference — skills/vigil/reference.md

License

See LICENSE file

Author

Austin J. Hardy (@nitsuah)

Community Standards

Shared community policies are centralized in https://github.com/nitsuah/.github:

Contributing: https://github.com/nitsuah/.github/blob/main/CONTRIBUTING.md
Code of Conduct: https://github.com/nitsuah/.github/blob/main/CODE_OF_CONDUCT.md
Security: https://github.com/nitsuah/.github/blob/main/SECURITY.md

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
.husky		.husky
.vscode		.vscode
app		app
components		components
config		config
database		database
docs		docs
e2e		e2e
hooks		hooks
lib		lib
promo		promo
public		public
scripts		scripts
site		site
skills/vigil		skills/vigil
templates		templates
tests		tests
types		types
.coverage		.coverage
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
FEATURES.md		FEATURES.md
LICENSE		LICENSE
METRICS.md		METRICS.md
README.md		README.md
ROADMAP.md		ROADMAP.md
TASKS.md		TASKS.md
auth.ts		auth.ts
build-out.log		build-out.log
build.log		build.log
build2.log		build2.log
netlify.toml		netlify.toml
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
playwright.ci.config.ts		playwright.ci.config.ts
playwright.config.ts		playwright.config.ts
playwright.smoke.config.ts		playwright.smoke.config.ts
playwright.visual-docs.config.ts		playwright.visual-docs.config.ts
postcss.config.mjs		postcss.config.mjs
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Vigil

Last Updated: 2026-09-30

Mission Statement

Features

Screenshots & diagrams

Diagrams

Screenshots

Use it from Claude Code

Repo Tiers

Tech Stack

Getting Started

Prerequisites

Installation

What’s New

Quick Links

Contributing

Docker Validation

Environment Variables

Project Structure

Standardized MD Files

Health Score

API Endpoints

Repository Management

AI Context & MCP

Agent Task Queue

PMO

Deployment

Docs Index

License

Author

Community Standards

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages