cybervisor 0.18.1

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 Codex, installs runtime hooks for non-interactive execution, and enforces structured stage-result contracts.

What it does

• Runs a customizable multi-stage pipeline defined in cybervisor.yaml
• Enforces structured stage-result contracts with artifact-driven routing
• Installs runtime hooks for fully non-interactive agent execution
• Streams live agent output and persists per-stage logs
• Cleans up agent-spawned processes after each stage and on pipeline exit
• Snapshots and restores agent settings automatically
• Enforces single-instance execution with a daemon-aware lock
• Daemon mode: Long-running WebSocket server for headless execution
• Daemon client commands: status, submit, attach, cancel, logs, end

Requirements

• Python 3.11+
• uv
• One of:
  • gemini on PATH
  • claude on PATH
  • codex on PATH
• ~/.cybervisor/config.yaml with verifier settings

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

Set your global default agent:

cybervisor use claude

Configure your verifier settings in ~/.cybervisor/config.yaml (created with 0o600 permissions):

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

# Per-stage agent tool model overrides (top-level, not under llm)
# stage_models:
#   Spec: claude-sonnet-4-6
#   "Review Code": claude-opus-4-6

Verify everything is ready:

cybervisor doctor

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-after "Review Code"    # Run up to and including this stage, then stop
cybervisor run "Your task" --end-before "Verify"        # Stop before executing this stage

# Set default agent
cybervisor use gemini

# Restore skills left behind after a crash
cybervisor restore-skills

# 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.

For advanced stage configuration including cleanup paths, max iterations, per-stage model overrides, per-stage write protection (read_only_paths), and contract authoring, see the Pipeline Authoring Guide and Configuration Reference.

Global Flags

Flag	Description
--quiet	Suppress non-error stderr output for all commands
--help	Show help message and exit

Prompt Resolution

When running cybervisor run or cybervisor submit, the task prompt is resolved with the following priority:

1. Positional argument — cybervisor run "Your task description"
2. stdin — printf "Your task" \| cybervisor run
3. Error — If neither is provided, the command exits with an error

If a positional prompt argument is present, stdin is ignored even when piped.

Workspace-Local Config Override

A .cybervisor/config.yaml file in the current working directory takes precedence over ~/.cybervisor/config.yaml for global verifier settings (llm.api_key, llm.base_url, llm.model, agent_tool, stage_models). Pipeline configuration (cybervisor.yaml) has no CWD override — it is always resolved from the project root.

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, cwd: /workspace/project, bounds: end_stage=Verify)
#   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

# Check status of a specific task by ID (matches across all directories)
cybervisor status abc123def456

# Submit a task and stream events until completion
cybervisor submit "Your task description" --config cybervisor.yaml --start-stage Implement
cybervisor submit "Your task" --end-after "Review Code"
cybervisor submit "Your task" --end-before Verify
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
# On submit, the task ID is printed to stderr (e.g. "Task created: abc123def456")
# Use this ID with attach, cancel, logs, or end

# Reconnect to a running or completed task (auto-detects task in current directory)
cybervisor attach

# Reconnect to a specific task by ID to replay buffered events
cybervisor attach my-task-123

# Cancel an active task (auto-detects task in current directory; errors if zero tasks)
cybervisor cancel

# Cancel a specific task by ID (works from any directory)
cybervisor cancel my-task-123

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

# Update the end stage of a running task
cybervisor end --after Verify                   # auto-detect task in current directory; stop after Verify executes
cybervisor end --before Verify                  # auto-detect task in current directory; stop before Verify starts
cybervisor end abc123 --before Verify           # specify task ID explicitly (works from any directory)

# 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.)
• 2 — configuration validation error
• 130 — interrupted (SIGINT/SIGTERM received)

Shell Completions

cybervisor supports two completion modes:

Eval-based (requires argcomplete)

uv tool install 'cybervisor[completions]'
eval "$(register-python-argcomplete cybervisor)"

If cybervisor is already installed without the extra, reinstall with uv tool install 'cybervisor[completions]'. Add the eval line to ~/.bashrc for persistence. This mode provides dynamic completions for stage names, agent tools, and document IDs.

Static file (no dependencies)

source <(cybervisor completion bash)

Add to ~/.bashrc for persistence. This mode covers all subcommands, flags, and static choices (e.g., --template simple|speckit, completion bash) without runtime dependencies.

For full details, see Shell Completions.

Documentation

• Getting Started — Step-by-step tutorial from install to first pipeline run
• Configuration Reference — cybervisor.yaml, ~/.cybervisor/config.yaml, stage fields, CLI commands
• Pipeline Authoring Guide — Designing stages, contracts, routing, and agent prompts
• Runtime and Daemon — User Guide — Daemon mode, skill disable/restore, signals
• Runtime and Daemon — Developer Reference — Hook lifecycle, adapter internals, logs
• WebSocket Protocol — Daemon message schema, connection lifecycle, chunking
• Testing and Sandbox — Smoke tests, mock adapter, Docker, sandbox
• Updating — Install, upgrade, and migration workflows
• Troubleshooting — Common issues and resolutions

For development and contributing documentation, see docs/development.md.