skillassets

package module
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README

vigilante logo

vigilante

Release Go Reference codecov License Release Workflow

vigilante is a sandbox-first orchestration layer for coding agents.

Treat the model as untrusted by default. Vigilante is the control plane that turns GitHub issues into a guarded issue-to-PR pipeline: one git worktree per task, deterministic lifecycle management, scoped execution, and a durable operator trail through issue comments, session state, and pull requests.

It is not the model itself. Vigilante schedules work, prepares isolated worktrees, launches a supported coding-agent CLI, tracks progress, and recovers or cleans up stalled sessions so a repository behaves like a controlled worker instead of a loose collection of scripts.

Docs · Sandbox Design · Closed Issues · Releases · Contributing

Why Vigilante Exists

Coding agents need broad tool access to be useful. That also means they can read the wrong files, use the wrong credentials, or leave behind hard-to-audit state if you run them with ambient access.

Vigilante reduces that risk by making the orchestrator responsible for enforcement:

  • one isolated git worktree per issue
  • issue-driven execution with progress reported back to GitHub
  • repository-aware implementation skills selected from local context
  • local session tracking for cleanup, resume, redispatch, and recovery
  • optional package-hardening checks for supported Node.js repositories

How It Works

Vigilante keeps the flow short and explicit:

  1. Watch a local repository tied to a GitHub remote.
  2. Read open issues and select only eligible work.
  3. Create a fresh git worktree and issue branch.
  4. Launch a supported coding-agent CLI in that worktree.
  5. Track progress through issue comments, local session state, and PR status.
  6. Clean up or recover the run without duplicating work.

GitHub is the only fully implemented issue-tracking backend today. The backend interfaces are designed so support for systems such as Linear and Jira can be added without rewriting the orchestration loop.

Guardrails That Matter

  • Worktree isolation. Every issue gets its own branch and worktree so the main checkout stays untouched.
  • Operator-visible lifecycle. Start, progress, failure, and PR state are reflected through GitHub comments and local Vigilante state.
  • Provider-neutral orchestration. Works with supported headless coding-agent CLIs including codex, claude, gemini, and opencode.
  • Recovery tooling. resume, redispatch, and cleanup are first-class flows, not ad hoc scripts.
  • Rate-limit awareness. Vigilante monitors GitHub API budget and delays additional work when quota gets tight.

Sandbox Positioning

Vigilante already isolates work at the git-worktree layer today. SANDBOX.md describes the next isolation layer: running each coding-agent session inside a repo-scoped Docker container with proxy-mediated GitHub access and short-lived credentials.

In other words:

  • Current state: isolated worktrees, local session tracking, host-executed agent CLI
  • Planned sandbox mode: containerized execution, stronger credential scoping, repo-bounded GitHub proxying

See SANDBOX.md for the design and current status.

Install

Install with Homebrew:

brew install --cask aliengiraffe/spaceship/vigilante

Upgrading through Homebrew restarts the managed service for you, so brew upgrade --cask vigilante alone is enough — no follow-up vigilante service restart is needed. On a machine that has not run vigilante setup -d yet there is no service to restart and the install still succeeds.

Or install from PyPI with pip, pipx, or uv. The wheels ship the same prebuilt (and, on macOS, signed) vigilante binary the GitHub release carries — no Go toolchain and no Python wrapper involved:

pipx install vigilante-cli   # or: pip install vigilante-cli / uv tool install vigilante-cli

The distribution is named vigilante-cli (the vigilante name on PyPI belongs to an unrelated project); the installed command is still vigilante. Wheels exist for macOS arm64, macOS x86_64, and Linux x86_64 — on other platforms (Windows, Linux arm64) the install fails with pointers to Homebrew and the releases page. Homebrew remains the recommended path on macOS; pip/pipx suit Linux hosts, containers, and Python-managed toolchains. Note that pip delivers the binary only — the requirements below still apply.

Requirements:

  • git
  • gh authenticated against the GitHub account Vigilante should operate with
  • one supported coding-agent CLI installed locally: claude (the default), or codex, gemini, or opencode selected with --provider

Bootstrap the local machine and install the managed service. --provider defaults to claude:

vigilante setup -d

For per-issue Claude model selection, add one of the human-managed labels claude:sonnet, claude:opus, or claude:fable. For example, labeling an issue claude:opus routes it to Claude and launches that session with --model opus; resumes keep the model captured when the session started, and the coding-agent launch comment echoes the active model alias.

Quick Start

Register a repository and let Vigilante manage the issue-to-PR loop:

vigilante watch ~/path/to/repo

Typical first-run flow:

brew install --cask aliengiraffe/spaceship/vigilante
vigilante setup -d
vigilante watch ~/hello-world-app
vigilante daemon run --once

Useful follow-up commands:

vigilante list
vigilante list --running
vigilante status
vigilante logs
vigilante service restart

Key Commands

  • vigilante setup: verify dependencies, install bundled skills, and install or refresh the managed service
  • vigilante watch <path>: register a local repository for issue monitoring
  • vigilante clone <repo> [<path>]: clone a repository and auto-add it to the watch list
  • vigilante list: show watched repositories and optionally active runs
  • vigilante status: show service health, watched repos, sessions, and rate-limit state as a live dashboard on a terminal (--plain for plain text; piped and redirected output is plain text automatically)
  • vigilante logs: inspect daemon and per-issue logs
  • vigilante resume, vigilante redispatch, vigilante cleanup: recover or restart stuck work safely
  • vigilante daemon run: run the watcher loop in the foreground

Additional Capabilities

Fork Mode

Use fork mode when the authenticated GitHub identity should open pull requests from a fork instead of pushing issue branches directly to the upstream watched repository.

vigilante watch --fork ~/hello-world-app

Use --fork-owner with --fork when the fork should live under a bot or organization account. For the full behavior, see DOCS.md.

Package Hardening

Vigilante includes a deterministic package-hardening scan for watched repositories classified with the nodejs tech stack. It checks lockfile presence, audits npm dependencies when applicable, and reviews CI install posture without relying on an LLM.

For trigger conditions, findings, and remediation flow, see DOCS.md.

More Docs

The full reference lives in DOCS.md, including:

  • installation details and development mode
  • full command reference and expected behaviors
  • backend architecture and current implementation status
  • local state layout, logs, and recovery workflows
  • package hardening behavior and config
  • GitHub integration, worktree strategy, and service behavior
  • CI, releases, and implementation notes

Maintainers cutting a release should start with docs/releasing.md, which covers macOS code signing and notarization, the required secrets, and how to verify a published binary.

Documentation

Overview

Package skillassets embeds the runtime assets that ship inside the vigilante binary: the built-in coding-agent skills under skills/ and the canonical repository label manifest.

Vigilante

This is the module root of vigilante, a sandbox-first orchestration layer for coding agents. Vigilante turns GitHub issues into a guarded issue-to-PR pipeline: one git worktree per task, deterministic lifecycle management, scoped credentials, and a durable operator trail through issue comments, session state, and pull requests.

Vigilante is a command-line program, not a library. The orchestration logic lives in internal packages and is intentionally not part of the public API, so there is nothing here to import beyond the embedded assets above. Install and usage documentation lives in README.md and DOCS.md; the sandbox threat model is described in SANDBOX.md.

The command entry points are: 

cmd/vigilante   the vigilante CLI and daemon
cmd/gh-sandbox  the sandboxed gh wrapper used inside containers

Index

Constants

This section is empty.

Variables

View Source 
var LabelsManifest embed.FS

LabelsManifest contains the canonical Vigilante repository label definitions.

View Source 
var Skills embed.FS

Skills contains built-in runtime skill files for installed binaries.

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gh-sandbox command
Command gh-sandbox is a lightweight gh CLI mirror for sandbox containers.
 Command gh-sandbox is a lightweight gh CLI mirror for sandbox containers.
vigilante command
Command vigilante is the sandbox-first orchestration CLI and daemon for coding agents.
 Command vigilante is the sandbox-first orchestration CLI and daemon for coding agents.
internal
app
Package app implements the vigilante command surface: argument parsing, the subcommand handlers behind the CLI, and the operator-facing reporting such as `vigilante status` and `vigilante logs`.
 Package app implements the vigilante command surface: argument parsing, the subcommand handlers behind the CLI, and the operator-facing reporting such as `vigilante status` and `vigilante logs`.
backend
Package backend defines the issue-tracker abstraction vigilante orchestrates against: the IssueTracker and LabelManager interfaces plus the tracker-neutral types (work items, labels, progress comments) that cross that boundary.
 Package backend defines the issue-tracker abstraction vigilante orchestrates against: the IssueTracker and LabelManager interfaces plus the tracker-neutral types (work items, labels, progress comments) that cross that boundary.
backend/github
Package github implements the backend.IssueTracker and backend.LabelManager interfaces for GitHub, driving the authenticated `gh` CLI rather than talking to the REST API directly so vigilante inherits the operator's existing gh credentials and configuration.
 Package github implements the backend.IssueTracker and backend.LabelManager interfaces for GitHub, driving the authenticated `gh` CLI rather than talking to the REST API directly so vigilante inherits the operator's existing gh credentials and configuration.
backend/linear
Package linear implements the backend.IssueTracker interface for Linear, mapping Linear issues onto the tracker-neutral work-item types vigilante dispatches against.
 Package linear implements the backend.IssueTracker interface for Linear, mapping Linear issues onto the tracker-neutral work-item types vigilante dispatches against.
blocking
Package blocking classifies why a session stopped making progress and turns that into the structured blocked reason vigilante records in session state and reports back on the issue.
 Package blocking classifies why a session stopped making progress and turns that into the structured blocked reason vigilante records in session state and reports back on the issue.
build
Package build holds the version metadata stamped into the binary at link time by GoReleaser.
 Package build holds the version metadata stamped into the binary at link time by GoReleaser.
environment
Package environment is the boundary between vigilante and the host: process execution, executable lookup, platform detection, and the access log that records every external command a session ran.
 Package environment is the boundary between vigilante and the host: process execution, executable lookup, platform detection, and the access log that records every external command a session ran.
fork
Package fork implements vigilante's fork-based workflow, where the authenticated identity opens pull requests from a fork instead of pushing branches to the watched upstream repository.
 Package fork implements vigilante's fork-based workflow, where the authenticated identity opens pull requests from a fork instead of pushing branches to the watched upstream repository.
github
Package ghcli wraps the GitHub CLI.
 Package ghcli wraps the GitHub CLI.
hardening
Package hardening provides deterministic JS/TS package manifest checks for pull requests that modify package.json files.
 Package hardening provides deterministic JS/TS package manifest checks for pull requests that modify package.json files.
logging
Package logging provides the daemon's structured logger and the size-bounded rotation that keeps long-running daemon logs from filling the disk.
 Package logging provides the daemon's structured logger and the size-bounded rotation that keeps long-running daemon logs from filling the disk.
logtime
Package logtime formats timestamps for operator-facing output.
 Package logtime formats timestamps for operator-facing output.
provider
Package provider describes the coding-agent CLIs vigilante can launch — Claude Code, Codex, Gemini, and OpenCode — and how to invoke each one for a given task.
 Package provider describes the coding-agent CLIs vigilante can launch — Claude Code, Codex, Gemini, and OpenCode — and how to invoke each one for a given task.
repo
Package repo inspects a local git checkout: discovering its remote and default branch, parsing GitHub remotes into owner/name slugs, and classifying the repository's build tooling so vigilante can pick the matching implementation skill.
 Package repo inspects a local git checkout: discovering its remote and default branch, parsing GitHub remotes into owner/name slugs, and classifying the repository's build tooling so vigilante can pick the matching implementation skill.
runner
Package runner drives a single coding-agent session end to end: issue implementation, conflict resolution, and CI remediation.
 Package runner drives a single coding-agent session end to end: issue implementation, conflict resolution, and CI remediation.
sandbox
Package sandbox orchestrates containerized coding-agent execution.
 Package sandbox orchestrates containerized coding-agent execution.
sandbox/container
Package container manages Docker container lifecycle for sandbox sessions.
 Package container manages Docker container lifecycle for sandbox sessions.
sandbox/proxy
Package proxy implements the sandbox reverse proxy that intercepts gh CLI commands from sandbox containers and enforces repository-scoped access.
 Package proxy implements the sandbox reverse proxy that intercepts gh CLI commands from sandbox containers and enforces repository-scoped access.
sandbox/token
Package token implements HMAC-signed sandbox session tokens.
 Package token implements HMAC-signed sandbox session tokens.
service
Package service installs and controls the vigilante daemon as a native operating-system service: a launchd job on macOS and a systemd unit on Linux.
 Package service installs and controls the vigilante daemon as a native operating-system service: a launchd job on macOS and a systemd unit on Linux.
skill
Package skill installs and resolves the coding-agent skills that tell an agent how to implement an issue in a given repository shape.
 Package skill installs and resolves the coding-agent skills that tell an agent how to implement an issue in a given repository shape.
state
Package state is vigilante's durable record: watch targets, per-issue sessions, and the configuration the daemon reads on every scan.
 Package state is vigilante's durable record: watch targets, per-issue sessions, and the configuration the daemon reads on every scan.
telemetry
Package telemetry exports vigilante's operational events over OpenTelemetry: command invocations, workflow milestones, and downstream rate limiting.
 Package telemetry exports vigilante's operational events over OpenTelemetry: command invocations, workflow milestones, and downstream rate limiting.
testutil
Package testutil provides the shared fakes vigilante's tests use in place of the host: a scripted environment.Runner that answers commands from a fixture map, and a discarding writer.
 Package testutil provides the shared fakes vigilante's tests use in place of the host: a scripted environment.Runner that answers commands from a fixture map, and a discarding writer.
worktree
Package worktree manages the per-issue git worktrees that isolate one task from another, along with the deterministic branch names and paths derived from an issue number and title.
 Package worktree manages the per-issue git worktrees that isolate one task from another, along with the deterministic branch names and paths derived from an issue number and title.
Package scripts contains no Go implementation.
 Package scripts contains no Go implementation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.