Vigil

AI-powered task automation daemon. Polls external task sources for new tasks, invokes Claude Code or Codex to analyze and solve them, classifies complexity into tiers, and takes appropriate actions — creating PRs, pushing branches, or requesting clarification.

How it works

Task Source → Poller → Queue → Agent → Result Parser → PRs / Comments

1. Poll — discovers new tasks from an external source (currently Contember CMS)
2. Queue — manages concurrent processing with configurable limits
3. Solve — creates an isolated git worktree, runs the configured agent with a structured prompt
4. Classify — parses Claude's assessment into tiers:
   • Trivial → merge-ready PR
   • Simple → draft PR for review
   • Complex → branch + detailed analysis
   • Unclear → posts clarifying questions back to source
5. Act — creates PRs via gh CLI, posts comments via the provider API

A React dashboard at localhost:7474 provides real-time monitoring with live output streaming, task cancellation, and retry.

Prerequisites

• Node.js 20+
• claude CLI (Claude Code) or codex CLI installed and authenticated
• gh CLI for PR creation
• Git

Setup

npm install
cp vigil.config.example.json vigil.config.json
# Edit vigil.config.json with your provider credentials and project paths

Configuration

vigil.config.json (validated with Zod):

Field	Description
provider	Task source config — type, credentials, taskBaseUrl for dashboard links
projects	Array of repos to work on — slug, repoPath, baseBranch
polling.intervalSeconds	How often to check for new tasks (default: 60)
polling.since	ISO date to start polling from (avoids processing old tasks)
solver.type	"default" (headless) or "okena" (visible in Okena terminal)
solver.agent	"claude" (Claude Code) or "codex" (OpenAI Codex CLI). Can be overridden per task from the extension.
solver.concurrency	Max concurrent tasks (default: 2)
solver.timeoutMinutes	Per-task timeout (default: 30)
solver.model	Agent model override (optional)
github.createPrs	Enable/disable PR creation (default: true)
github.postComments	Enable/disable posting back to source (default: true)
github.prPrefix	PR title prefix (default: [Vigil])

Running

# Development (hot reload)
npm run dev

# Production daemon (macOS launchd)
make install       # build + link CLI + start daemon
vigil status       # check if running
vigil logs         # tail stdout
vigil logs --err   # tail stderr
vigil stop         # stop daemon
make restart       # rebuild + restart
make uninstall     # stop + unlink

Dashboard: http://localhost:7474

Okena integration

When solver.type is set to "okena", Vigil creates worktrees and runs the configured agent inside visible Okena terminal panes — you can watch and interact as it works. If Okena is unavailable, tasks fail loudly until Okena is reachable again.

Requires Okena's remote server enabled (remote_server_enabled: true in Okena settings).

Solver prompt

The prompt builder (src/solver/prompt-builder.ts) delegates to Almanac skills — specifically /task-start (which chains complexity assessment, branch naming, and tier-appropriate execution) and /commit for conventional commits. This means agents solving tasks follow the same structured workflow and conventions you'd use interactively.

Architecture

src/
  providers/       # Task source abstraction (Contember, future: GitHub, Linear)
  poller/          # Interval-based task discovery
  queue/           # Concurrent task processing
  solver/          # Solver interface, default (headless) + invoker
  extensions/      # Optional integrations (Okena terminal)
  actions/         # PR creation, comment posting
  worktree/        # Git worktree lifecycle
  db/              # SQLite persistence
  server/          # Hono API + static dashboard serving
web/               # React dashboard (Vite)

Adding a provider

1. Implement TaskProvider interface (src/providers/provider.ts)
2. Add provider config to the discriminated union in src/config.ts
3. Register in src/providers/registry.ts