Metadata-Version: 2.4
Name: cybervisor
Version: 0.8.1
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: pyyaml>=6.0.3
Requires-Dist: setproctitle>=1.3.4; platform_system != "Windows"

# cybervisor

`cybervisor` is an autonomous CLI supervisor for development runs. It executes a customizable multi-stage pipeline with Gemini CLI, Claude Code, or a mock agent, installs runtime hooks for non-interactive execution, enforces structured stage-result contracts, and keeps audit logs in JSONL.

`cybervisor` works best when it sits on top of a `speckit` repository. `speckit` gives the project durable product and planning memory under `.specify/`, and `cybervisor` turns that context into an autonomous execution loop with review, correction, and verification stages.

## What it does

- Runs a multi-stage pipeline defined in `cybervisor.yaml`
- Defaults to a robust 5-to-10 stage pipeline depending on the scaffold used
- Supports structured stage-result contracts and artifact-driven routing
- Fails fast when the selected agent CLI or hook verifier credentials are missing
- Writes non-secret hook runtime metadata under `.cybervisor/hooks/` for non-mock runs
- Keeps verifier credentials in `~/.cybervisor/config.yaml`
- Snapshots `.gemini/settings.json` or `.claude/settings.json` and restores them on exit
- Streams live agent output to stderr and persists per-stage logs under `.cybervisor/logs/stages/`
- Exits with `130` on `SIGINT` or `SIGTERM` after cleanup

## Requirements

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)
- One of:
  - `gemini` on `PATH`
  - `claude` on `PATH`
  - `mock` mode for local deterministic runs
- `~/.cybervisor/config.yaml` with verifier settings for non-mock runs

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

`cybervisor init` detects your environment:
- If `.specify/` exists, it installs the **speckit** scaffold (integrated with `speckit` workflows).
- If `.specify/` is missing, it installs the **simple** scaffold (standalone artifacts in `.cybervisor/artifacts/`).

Both scaffolds create a `cybervisor.yaml` file containing the full pipeline configuration, including prompt templates and stage contracts.

Set your global default agent:

```bash
cybervisor use claude
```

Configure your verifier settings in `~/.cybervisor/config.yaml`:

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

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-stage "Review Code"
cybervisor run "Your task" --end-before "Verify"

# Set default agent
cybervisor use gemini

# Validate your configuration
cybervisor validate
cybervisor validate --show-guidance
```

## Recommended with speckit

The strongest setup is pairing `cybervisor` with `speckit`. `speckit` manages the long-lived product memory (specs, plans, tasks) in `.specify/`, while `cybervisor` provides the autonomous execution engine to drive those workflows.

## Development

If you are contributing to `cybervisor`:

```bash
uv sync
uv run mypy --strict src
uv run pytest
```

Release helper:

```bash
./scripts/publish.sh patch  # or minor, major
```

The script requires a clean git working tree, bumps the package version, refreshes `uv.lock`, builds and publishes the package, then creates a release commit and annotated git tag like `v0.7.1`.

## Repository Layout

```text
src/cybervisor/        Core CLI package
assets/hooks/          Hook prompt assets and fixtures
scripts/               Demo and utility scripts
templates/demo/        Demo project scaffold
tests/                 Unit and integration coverage
.specify/              Constitution and repo-specific scripts
AGENTS.md              Symlink to constitution
GEMINI.md              Symlink to AGENTS.md
CLAUDE.md              Symlink to AGENTS.md
```
