Installation

Vigil ships as a single static binary — under 5MB, zero runtime dependencies. Install via Homebrew on macOS or Linux.

Verify the installation:

That's it. No language runtimes, no Docker, no cloud accounts. The binary includes the daemon, CLI, and all detection engines. Works on macOS (Apple Silicon + Intel) and Linux (x86_64 + aarch64).

Quick Start

Four steps to full visibility across every AI agent touching your codebase.

Step 1. Start the daemon. It watches your project directory for filesystem changes, git activity, and running processes.

Step 2. Launch your agents. Open Claude Code, start Cursor, spin up Conductor — whatever you use. Vigil detects them automatically.

Step 3. Check status. See every active agent, files they've touched, and any collision warnings.

Step 4. Review the event log. Every file touch, edit, and agent action is captured with timestamps and attribution.

Configuration

Vigil works with zero configuration — no config files needed. All options are passed as CLI flags to vigil watch.

A config file format is planned for a future release.

Universal Capture

Every AI agent that touches your code — whether it's Claude Code with deep hooks integration, Cursor via its extension API, or an unknown process writing files — gets captured in a single unified event stream. No plugins to install, no agents to configure.

How it works: Vigil's daemon combines three detection layers. Layer 1 watches filesystem events (file creates, writes, deletes) and correlates them with running processes to attribute each change to a specific agent. Layer 2 connects to agent–specific APIs — Claude Code's hooks, Cursor's extension bus, OpenTelemetry collectors — for richer metadata like prompt context and tool calls. Every event lands in a local SQLite store with sub–millisecond timestamps.

Collision Detection

When two agents edit the same file within a configurable time window, Vigil flags a collision. This is the most common source of silent bugs in multi–agent workflows — Agent A refactors a function while Agent B adds a new call to the old signature. Without Vigil, you'd only discover the break at runtime.

How it works: The daemon maintains a sliding window (default 30 seconds) over the event stream. When overlapping writes from different agents hit the same file path, a collision record is created linking both sessions. The CLI and menu bar app surface these instantly with file–level detail.

Confidence Scoring

Not all agent outputs are equal. A one–line typo fix is almost certainly correct. A 200–line refactor of code the agent has never seen before is risky. Vigil assigns a confidence score to each agent session based on observable signals — not guesses.

How it works: The scoring engine weighs multiple factors: the ratio of lines read to lines written (agents that read more before writing score higher), whether the agent accessed test files, whether it wrote tests alongside production code, the size and complexity of the diff, and historical accuracy for that agent type. Scores range from 0–100, where anything below 60 triggers a review warning.

Cost Intelligence

AI agents consume tokens, and tokens cost money. Vigil tracks estimated spend per agent, per session, and per time period — giving you a real burn rate instead of a surprise invoice at the end of the month.

How it works: For agents with deep hooks (Claude Code), Vigil captures actual token counts from the API response. For others, it estimates based on file sizes read and written, using published per–token pricing for each model. The vigil cost command breaks down spend by agent, session, and time window.

Hallucination Detection

Agents sometimes import modules that don't exist, call functions with wrong signatures, or reference APIs that were deprecated three versions ago. Vigil catches these patterns by cross–referencing agent output against your actual codebase state.

How it works: After an agent writes a file, Vigil's L3 Trust Intelligence layer runs a series of checks: import resolution (do the imported modules actually exist?), symbol validation (do referenced functions and types exist in the codebase?), and pattern matching against known hallucination signatures. Flagged issues appear in the event log and the menu bar app with a hallucination warning.

Selective Rollback

When an agent goes off the rails, you need to undo its work without losing changes from other agents that were working in parallel. A blanket git reset destroys everything. Vigil's selective rollback targets only the changes from a specific agent session.

How it works: Every write event is stored with a before–and–after snapshot of the affected file region. When you roll back a session, Vigil replays the inverse patches in reverse chronological order, applying only the diffs attributed to that session. Other agents' changes remain intact.

vigil watch

Start the Vigil daemon. It monitors filesystem events, detects running AI agents, and records every action to the local SQLite store.

vigil status

Show a snapshot of the current daemon state: active agents, their sessions, file counts, collision warnings, and overall resource usage. Exits with code 1 if collisions are active, making it useful in CI scripts.

vigil log

Query the event stream. Filter by agent or file path. By default shows the most recent events across all agents.

vigil cost

Show token usage and estimated cost breakdowns. Aggregates by agent, session, or time period. Uses actual token counts from hooked agents and estimates for the rest.

vigil init

Register Claude Code hooks so Vigil can capture richer telemetry — token counts, model selection, and tool calls — beyond what filesystem watching alone provides.

The deepest integration available. Vigil connects directly to Claude Code’s hooks API, capturing prompt context, tool calls, token counts, model selection, and error states in addition to filesystem events. This gives Vigil full visibility into what the agent is thinking, not just what it’s writing.

Setup: Run the hook installer to enable deep integration:

Vigil detects Cursor through its process signature and monitors its file operations via the filesystem watcher. The extension API integration captures additional metadata including active file context, applied edits, and composer session boundaries. No manual setup required — Vigil detects Cursor automatically when it starts.

OpenAI Codex emits OpenTelemetry traces that Vigil’s built-in OTLP collector ingests automatically. This provides structured span data including token usage, model calls, and tool invocations. Combined with filesystem monitoring, Vigil reconstructs a complete timeline of Codex’s actions.

Conductor orchestrates multiple agents across git worktrees. Vigil detects worktree creation and monitors each branch independently, attributing file changes to the correct Conductor-managed agent. Process scanning identifies the parent Conductor process and its child agents for accurate session grouping.

Aider works primarily through git commits, making it straightforward for Vigil to track. The filesystem watcher captures file edits in real time, while the git monitor detects Aider’s characteristic commit patterns to attribute changes and reconstruct session boundaries.

Any process that modifies files in a watched directory is captured, even if Vigil doesn’t have a specific integration for it. Process detection identifies the program name and PID, while the filesystem watcher records every read and write. This is the L1 Universal Capture layer — it works with everything, automatically.

Three Layers

Vigil's architecture is a three–layer stack. Each layer builds on the one below it. L1 works universally with zero configuration. L2 and L3 activate automatically when deeper integrations are available.

Data Model

All data lives in a single SQLite database at ~/.vigil/vigil.db. No cloud, no network calls, no external dependencies. Both the CLI and the menu bar app query this file directly.

The schema centers on two core tables:

Menu Bar App

The Vigil menu bar app is a native macOS application built with Tauri v2 and React. It sits in your menu bar and provides a persistent, always–visible window into agent activity without touching the terminal.

The app reads directly from the daemon's SQLite database — same file, same data, no API layer in between. It uses the same dark theme as the CLI output and this documentation site: dark backgrounds, cyan accents, monospace typography.

Key features of the menu bar app: