Metadata-Version: 2.4
Name: cybervisor
Version: 0.18.3
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: 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, 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`](https://docs.astral.sh/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`:

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

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 cleanup paths, max 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).

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

`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

# 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

- [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, 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).
