Metadata-Version: 2.4
Name: cybervisor
Version: 0.25.0
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.1.0
Requires-Dist: google-antigravity>=0.1.0
Requires-Dist: httpx>=0.27.0
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

`cybervisor` is an autonomous CLI supervisor for development runs. It executes a customizable multi-stage pipeline with Gemini CLI, Claude Code, Codex, OpenCode, or Cursor, 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 (logs are cleared before each run so they always reflect the current execution)
- 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
- 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`](https://docs.astral.sh/uv/)
- One of:
  - `gemini` on `PATH`
  - `claude-agent-sdk` Python package (included as a Cybervisor dependency; Claude authentication is resolved by Claude Code through normal env, settings, and login credentials)
  - `codex` on `PATH`
  - `opencode` on `PATH`
  - `cursor-agent` on `PATH`
  - `antigravity` agent via the bundled `google-antigravity` SDK (no separate install needed)
- `~/.cybervisor/config.yaml` with verifier settings

## Installation

Install the CLI onto your `PATH`:

```bash
uv tool install cybervisor
```

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 your global default agent:

```bash
cybervisor use claude
```

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

```yaml
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

# Per-stage agent tool overrides (top-level, not under llm)
# stage_agents:
#   "Design Delivery": gemini
#   "Review Delivery Docs": gemini

# Usage reporting (optional)
# usage_reporting:
#   enabled: true
#   endpoint: https://elasticsearch.example.com
#   api_key: your-api-key
#   index: cybervisor-usage
#   user: alice@example.com
```

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-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 per-stage agent overrides (`stage_agents` in `~/.cybervisor/config.yaml`), cleanup paths, max iterations, iteration counter resets (`reset_iterations`), per-stage model overrides, per-stage write protection (`read_only_paths`), and contract authoring, see the [Pipeline Authoring Guide](docs/pipeline-authoring.md) and [Configuration Reference](docs/configuration.md). For permission enforcement behavior per agent (including native OpenCode permissions via `OPENCODE_CONFIG_CONTENT`, the `enforcement_mode` marker and health-check warnings for Cursor, and serve startup troubleshooting for OpenCode), see the [Troubleshooting Guide](docs/troubleshooting.md#write-protection-read_only_paths).

### 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** — If no prompt is provided and every stage in the effective slice has a self-contained `prompt_template` (one that does not reference `{objective}`), the task runs without an objective prompt using the configured templates.
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, `agent_tool`, `stage_models`, `stage_agents`, `usage_reporting`, `server`, etc.) come from the workspace-local file, and the home-directory config is not loaded. 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. The daemon reloads `~/.cybervisor/config.yaml` (or the workspace-local `.cybervisor/config.yaml`) at the start of each task, so changes to `agent_tool`, `stage_agents`, `stage_models`, `usage_reporting`, and verifier settings take effect on the next submission without restarting the daemon. 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-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

# Batch submit: process all .md files in a directory sequentially
cybervisor submit --path prompts/                      # each .md file becomes a separate task
cybervisor submit --path prompts/ --task-id batch      # IDs: batch_1, batch_2, ...
# Completed files are moved to prompts/completed/; on failure, remaining files stay in place

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

```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, agent tools, 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 agent prompts
- [Runtime and Daemon — User Guide](docs/runtime-user.md) — Daemon mode, live stderr output, skill disable/restore, signals
- [Runtime and Daemon — Developer Reference](docs/runtime-internals.md) — Hook lifecycle, 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
- [Troubleshooting](docs/troubleshooting.md) — Common issues and resolutions

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