cybervisor 0.42.4

Autonomous CLI supervisor for staged AI workflows

cybervisor

Audience: Users and contributors.

cybervisor is an autonomous CLI supervisor for development runs. It executes a customizable multi-stage pipeline with Claude Code, Codex, OpenCode, Cursor, or Antigravity and enforces structured stage-result contracts.

What it does

• Runs a customizable multi-stage pipeline defined in cybervisor.yaml
• Runs trusted shell commands as deterministic, agent-free pipeline gates
• Runs optional trusted commands before and after every stage attempt
• Enforces structured stage-result contracts with artifact-driven routing
• Evaluates agent replies between supported agent turns and after each run without modifying agent settings
• Records contract and verifier decisions in .cybervisor/logs/evaluation-events.jsonl
• Streams live agent output and persists per-stage logs (logs are cleared before each run so they always reflect the current execution)
• Preserves agent-supplied argument names in stage logs while rendering known tools with consistent summary labels
• Cleans up agent-spawned processes after each stage and on pipeline exit
• On retry, prefers resuming the prior agent session (retry continuation) when the adapter supports it; unsupported adapters fall back to a fresh session
• For real harnesses, keeps sessions in their native stores and records the latest session metadata for native inspection; native discovery and Cybervisor --resume support vary by harness (see Native Harness Session History)
• For adapters with an effort channel, forwards any normalized effort string and lets the harness or provider validate it; Cursor rejects every explicit effort structurally
• Stops after the first attempt when a harness deterministically rejects its configuration, while transient failures continue through normal retries
• On explicit --resume restart, continues from the last captured session id when the adapter supports it and metadata matches (resumed stage continuation); falls back to a fresh attempt otherwise
• Leaves agent settings files unchanged
• Does not create .cybervisor/hooks/, hook sockets, or settings snapshots
• 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:
  • claude-agent-sdk Python package (included as a Cybervisor dependency; Claude authentication is resolved by Claude Code through normal env, settings, and login credentials)
  • openai-codex Python package (included as a Cybervisor dependency; its matching wheel bundles the Codex runtime)
  • opencode on PATH
  • cursor-sdk>=1.0.24 Python package (included as a Cybervisor dependency; the platform wheel bundles its own bridge, so no cursor-sdk-bridge binary needs to be on PATH) and harnesses.cursor.api_key in ~/.cybervisor/config.yaml when Cursor is selected
  • antigravity agent via the official agy headless CLI (version 1.1.8+)
• ~/.cybervisor/config.yaml with verifier settings

Installation

Install the CLI onto your PATH:

uv tool install cybervisor

The installation provides one console command, cybervisor. It does not install a separate agent-hook command.

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 the default harness in the active global config:

cybervisor use claude

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

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

# Harness-specific credentials
# harnesses:
#   cursor:
#     api_key: your-cursor-api-key

# Optional global effort and grouped per-stage overrides
# model_effort: medium
# stage_overrides:
#   Plan:
#     harness: codex
#     model: gpt-5.6
#     effort: xhigh
#   "Review Code":
#     effort: high

# Usage reporting (optional)
# usage_reporting:
#   enabled: true
#   endpoint: https://elasticsearch.example.com
#   api_key: your-api-key
#   index: cybervisor-usage
#   user: [e-mail]

# Local usage history (optional)
# usage_recording:
#   enabled: false

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-from "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
cybervisor run "Your task" --start-from "Implement" --resume  # Resume from last captured session

# Set the default harness
cybervisor use claude

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

Use prompt for agent instructions (prompt_template remains accepted) or command for a deterministic shell stage. These executor fields are mutually exclusive. For advanced stage configuration including per-stage runtime overrides, cleanup paths, command gates, iteration controls, model overrides, write protection, and contracts, see the Pipeline Authoring Guide and Configuration Reference.

Pipeline lifecycle hooks

Define user-level lifecycle defaults in the active global configuration, usually ~/.cybervisor/config.yaml:

hooks:
  before_stage: scripts/telemetry.sh
  after_stage: scripts/telemetry.sh

Pipelines inherit each phase independently. A root hooks entry in cybervisor.yaml replaces the corresponding global command, while an explicit phase-level null disables that global default. An omitted, empty, or whole-mapping null pipeline section leaves both phases inherited.

These plural lifecycle hooks are separate from the singular verifier configuration. Effective hooks apply to agent and command stages, retries, routed revisits, standalone runs, daemon tasks, and slices. Cybervisor reloads the active global file at every attempt boundary and captures one stable hook pair for the whole attempt. Cleanup runs before before_stage; after_stage finishes before artifact backup, completion, and routing.

Lifecycle hooks are trusted, unsandboxed commands. They run from the workspace, inherit the Cybervisor environment, can receive routed context, and may repeat. Put stage-selective conditions and idempotency in the script. See the Pipeline Authoring Guide for environment variables, failure behavior, logs, and interruption semantics.

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. Config-driven promptless execution — A command-only slice needs no objective or coding agent. Harness-backed stages can also be promptless when their configured prompt does not reference {objective}.
4. Error — If no prompt is provided and any stage still requires {objective}, the command exits with an error listing the stages that need a prompt.

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 completely replaces ~/.cybervisor/config.yaml when present. All settings (verifier, harness, model_effort, stage_overrides, lifecycle hooks, usage_reporting, server, and so on) come from the workspace-local file; the home config is not loaded. Pipeline configuration (cybervisor.yaml) has no CWD override and 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. Cybervisor reloads ~/.cybervisor/config.yaml (or the workspace-local .cybervisor/config.yaml) before every stage attempt. Global hook changes take effect at the next attempt boundary. Agent stages also pick up changes to harness, model_effort, stage_overrides, and usage_reporting; command stages use the common hook snapshot without constructing or preflighting an agent adapter. Server bind settings (host, port) are fixed for the daemon's lifetime.

cybervisor sandbox launches the daemon inside an isolated Docker container with the current working directory mounted. See Testing and Sandbox — Docker Sandbox Serve for full documentation.

# 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-from Implement
cybervisor submit "Your task" --end-after "Review Code"
cybervisor submit "Your task" --end-before Verify
cybervisor submit "Your task" --start-from "Implement" --resume
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

# Batch submit: process ready .md files sequentially and rescan after successes
cybervisor submit --path prompts/                      # active batches accept later stable plans
cybervisor submit --path prompts/ --task-id batch      # IDs: batch_1, batch_2, ...
# New groups append in filename order; completed plans move to prompts/completed/
# Changing plans are deferred; failure leaves all unprocessed plans in place
# While a batch runs, `cybervisor end --after/--before <stage>` halts the batch,
# leaves the current plan in place, and exits 0 without submitting later plans.

# 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

# Query private local history without a running daemon
cybervisor usage
cybervisor usage --all-workspaces --group-by workspace
cybervisor usage --from 2026-07-01 --stage Implement

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, harnesses, 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

Browse the same guides on the web after building the static site in the workspace cybervisor-docs/ project (npm run sync && npm run dev). Production hosting at docs.cybervisor.ai is optional; see cybervisor-docs/README.md.

• 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 stage prompts
• Runtime and Daemon — User Guide — Daemon mode, live stderr output, skill disable/restore, signals
• Native Harness Session History — Find or resume stage conversations in each harness's native CLI
• Local Usage Metrics — Local history, filters, grouping, privacy, and token coverage
• Runtime and Daemon — Developer Reference — stage evaluation, 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
• Native Session Verification Report — Metadata-only evidence for native session persistence and discovery boundaries
• Troubleshooting — Common issues and resolutions

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