Metadata-Version: 2.4
Name: cybervisor
Version: 0.42.6
Summary: Autonomous CLI supervisor for staged AI workflows
Author: crzidea
Project-URL: Homepage, https://github.com/crzidea/cybervisor
Project-URL: Repository, https://github.com/crzidea/cybervisor
Project-URL: Issues, https://github.com/crzidea/cybervisor/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: agent-client-protocol>=0.9.0
Requires-Dist: claude-agent-sdk>=0.2.87
Requires-Dist: cursor-sdk>=1.0.24
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai-codex>=0.144.4
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: setproctitle>=1.3.4; platform_system != "Windows"
Requires-Dist: websockets>=11.0
Provides-Extra: completions
Requires-Dist: argcomplete>=3.1; extra == "completions"

# 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](docs/runtime-user.md#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`](https://docs.astral.sh/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`:

```bash
uv tool install cybervisor
```

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

After installation, verify:

```bash
cybervisor --version
```

To update an existing installation later:

```bash
uv tool upgrade cybervisor
cybervisor --version
```

For the full update guide, run:

```bash
cybervisor docs updating
```

## Quick Start

Initialize the `cybervisor` scaffold in your project:

```bash
cybervisor init
```

Set the default harness in the active global config:

```bash
cybervisor use claude
```

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

```yaml
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: alice@example.com

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

Verify everything is ready:

```bash
cybervisor doctor
```

Run the supervisor:

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

## Usage

```bash
# 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](docs/pipeline-authoring.md) and [Configuration Reference](docs/configuration.md).

### Pipeline lifecycle hooks

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

```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](docs/pipeline-authoring.md#pipeline-lifecycle-hooks) 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](docs/testing.md#docker-sandbox-serve) for full documentation.

```bash
# 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`)

```bash
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)

```bash
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](docs/completions.md).

## 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](docs/getting-started.md) — Step-by-step tutorial from install to first pipeline run
- [Configuration Reference](docs/configuration.md) — `cybervisor.yaml`, `~/.cybervisor/config.yaml`, stage fields, CLI commands
- [Pipeline Authoring Guide](docs/pipeline-authoring.md) — Designing stages, contracts, routing, and stage prompts
- [Runtime and Daemon — User Guide](docs/runtime-user.md) — Daemon mode, live stderr output, skill disable/restore, signals
- [Native Harness Session History](docs/runtime-user.md#native-harness-session-history) — Find or resume stage conversations in each harness's native CLI
- [Local Usage Metrics](docs/usage-metrics.md) — Local history, filters, grouping, privacy, and token coverage
- [Runtime and Daemon — Developer Reference](docs/runtime-internals.md) — stage evaluation, adapter internals, logs
- [WebSocket Protocol](docs/websocket-protocol.md) — Daemon message schema, connection lifecycle, chunking
- [Testing and Sandbox](docs/testing.md) — Smoke tests, mock adapter, Docker, sandbox
- [Updating](docs/updating.md) — Install, upgrade, and migration workflows
- [Native Session Verification Report](docs/native-session-verification.md) — Metadata-only evidence for native session persistence and discovery boundaries
- [Troubleshooting](docs/troubleshooting/index.md) — Common issues and resolutions

For development and contributing documentation, see [docs/development.md](docs/development.md).
