cybervisor 0.8.5

Autonomous CLI supervisor for staged AI workflows

cybervisor

cybervisor is an autonomous CLI supervisor for development runs. It executes a customizable multi-stage pipeline with Gemini CLI, Claude Code, or a mock agent, installs runtime hooks for non-interactive execution, enforces structured stage-result contracts, and keeps audit logs in JSONL.

cybervisor works best when it sits on top of a speckit repository. speckit gives the project durable product and planning memory under .specify/, and cybervisor turns that context into an autonomous execution loop with review, correction, and verification stages.

What it does

• Runs a multi-stage pipeline defined in cybervisor.yaml
• Defaults to a robust 5-to-10 stage pipeline depending on the scaffold used
• Supports structured stage-result contracts and artifact-driven routing
• Fails fast when the selected agent CLI or hook verifier credentials are missing
• Writes non-secret hook runtime metadata under .cybervisor/hooks/ for non-mock runs
• Keeps verifier credentials in ~/.cybervisor/config.yaml
• Snapshots .gemini/settings.json or .claude/settings.json and restores them on exit
• Streams live agent output to stderr and persists per-stage logs under .cybervisor/logs/stages/
• Enforces single-instance execution via .cybervisor/instance.lock (see Runtime Behavior); exits with 1 if another instance is already running in the same directory
• Exits with 130 on SIGINT or SIGTERM after cleanup

Requirements

• Python 3.11+
• uv
• One of:
  • gemini on PATH
  • claude on PATH
  • mock mode for local deterministic runs
• ~/.cybervisor/config.yaml with verifier settings for non-mock runs

Installation

Install the CLI onto your PATH:

uv tool install cybervisor

After installation, verify:

cybervisor --version

To update an existing installation later:

uv tool upgrade cybervisor
cybervisor --version

For the full update guide, run:

cybervisor docs updating

Quick Start

Initialize the cybervisor scaffold in your project:

cybervisor init

cybervisor init detects your environment:

• If .specify/ exists, it installs the speckit scaffold (integrated with speckit workflows).
• If .specify/ is missing, it installs the simple scaffold (standalone artifacts in .cybervisor/artifacts/).

Both scaffolds create a cybervisor.yaml file containing the full pipeline configuration, including prompt templates and stage contracts.

Set your global default agent:

cybervisor use claude

Configure your verifier settings in ~/.cybervisor/config.yaml:

agent_tool: claude
llm:
  api_key: your-api-key
  # Optional overrides
  # base_url: https://api.openai.com/v1
  # model: gpt-4o

Run the supervisor:

cybervisor "Create a 360 feedback system"
printf "Create a 360 feedback system" | cybervisor run

Usage

# Run with a prompt
cybervisor "Your task description"
cybervisor run "Your task description"
printf "Your task description" | cybervisor run

# Specify a custom config
cybervisor run "Your task" --config custom.yaml

# Control execution flow
cybervisor run "Your task" --start-stage "Implement"
cybervisor run "Your task" --end-stage "Review Code"
cybervisor run "Your task" --end-before "Verify"

# Set default agent
cybervisor use gemini

# Validate your configuration
cybervisor validate
cybervisor validate --show-guidance

Treat cybervisor validate as the local readiness gate before merge or execution. A passing result means the config is not only parseable, but also satisfies the stricter contract-authoring checks for route safety, complete routed examples, and authored prompt/guidance synchronization.

User-facing workflow or specification changes should be documented in tracked files under docs/ and, when relevant, this README. Do not leave those changes only in local working directories such as specs/ or .cybervisor/artifacts/, because they are not part of the committed project history.

Recommended with speckit

The strongest setup is pairing cybervisor with speckit. speckit manages the long-lived product memory (specs, plans, tasks) in .specify/, while cybervisor provides the autonomous execution engine to drive those workflows.

Development

If you are contributing to cybervisor:

uv sync
uv run mypy --strict src
uv run pytest

Release helper:

./scripts/publish.sh patch  # or minor, major

The script requires a clean git working tree, bumps the package version, refreshes uv.lock, builds and publishes the package, then creates a release commit and annotated git tag like v0.7.1.

Repository Layout

src/cybervisor/        Core CLI package
assets/hooks/          Hook prompt assets and fixtures
scripts/               Demo and utility scripts
templates/demo/        Demo project scaffold
tests/                 Unit and integration coverage
.specify/              Constitution and repo-specific scripts
AGENTS.md              Symlink to constitution
GEMINI.md              Symlink to AGENTS.md
CLAUDE.md              Symlink to AGENTS.md
.cybervisor/           Runtime state (instance.lock, hooks/, logs/)