cybervisor 0.9.0

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 — when the daemon is reachable, run checks for active daemon tasks before proceeding; when the daemon is unreachable, falls back to .cybervisor/instance.lock; exits with 1 if another instance is already running in the same directory (see Runtime Behavior)
• Exits with 130 on SIGINT or SIGTERM after cleanup
• Daemon mode (cybervisor serve): Long-running WebSocket server for headless pipeline execution and remote monitoring; supports task cancel, dynamic stop-stage updates, client reconnect with event replay, and background daemonization (see WebSocket Protocol)
• Daemon client commands: Six subcommands (status, submit, attach, cancel, logs, stop-stage) interact with a running daemon over WebSocket; status reports running task IDs and stages from the daemon's active registry; all support --host and --port overrides and exit with meaningful codes

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

Daemon Mode

cybervisor serve starts a long-running WebSocket daemon. Once running, use the client subcommands to submit tasks, monitor progress, and manage the pipeline remotely.

# Start the daemon server (WebSocket on ws://127.0.0.1:8765)
cybervisor serve
cybervisor serve --host 0.0.0.0 --port 9000
cybervisor serve --background   # Run in background via double-fork

# Check daemon connectivity and active tasks (exits 0 when reachable, 1 when not)
cybervisor status
cybervisor status --host 127.0.0.1 --port 8765
# Example output when a task is running:
#   Running task: abc123def456 (stage: Spec)
#   Daemon reachable at ws://127.0.0.1:8765
# Example output when no task is running:
#   No active tasks.
#   Daemon reachable at ws://127.0.0.1:8765
# Example output when daemon is down:
#   Daemon not reachable at ws://127.0.0.1:8765

# Submit a task and stream events until completion
cybervisor submit "Your task description" --config cybervisor.yaml --start-stage Implement
printf "Your task description" | cybervisor submit          # read prompt from stdin
cat task_prompt.txt | cybervisor submit                     # multi-line prompts preserved
cybervisor submit "Your task" --task-id my-task-123   # explicit task ID

# Reconnect to a running or completed task to replay buffered events
cybervisor attach my-task-123

# Cancel an active task
cybervisor cancel my-task-123

# Dump all buffered events as JSON Lines (non-blocking)
cybervisor logs my-task-123

# Update the stop stage of a running task
cybervisor stop-stage my-task-123 --stage Verify

# Override daemon address for any client command
cybervisor submit "task" --host 0.0.0.0 --port 9000

Exit codes for client commands:

• 0 — success
• 1 — failure (daemon unreachable, task not found, invalid state, etc.)
• 130 — interrupted (SIGINT during submit or attach) 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

For self-hosted E2E or verify-stage smoke tests, do not run from the repository root when the goal is to simulate a generated project. Create an isolated demo workspace first, typically with:

./scripts/e2e-demo-simple-project.sh

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, daemon.lock, hooks/, logs/)