# cybervisor

`cybervisor` is an autonomous CLI supervisor for development runs. It executes a default 5-stage pipeline with Gemini CLI, Claude Code, or a mock agent, supports customizing stages in YAML config, installs runtime hooks for non-interactive execution, enforces optional stage-result contracts, and keeps audit logs in JSONL.

## What it does

- Runs the default five ordered stages: `Spec`, `Review Spec`, `Implement`, `Review Code`, `Verify`
- Allows custom stage lists in `cybervisor.yaml`
- Supports optional 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 and settings snapshots under `.cybervisor/hooks/` for non-mock runs
- Keeps verifier credentials in inherited `CYBERVISOR_LLM_*` env vars instead of persisting them under `.cybervisor/hooks/`
- Snapshots `.gemini/settings.json` or `.claude/settings.json` and restores the exact pre-run content on exit
- Streams live agent output to stderr and persists per-stage logs under `.cybervisor/`
- 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_LLM_API_KEY` for non-mock runs

Optional local env loading is supported from `.env` in the working directory. `cybervisor` reads only `CYBERVISOR_LLM_BASE_URL`, `CYBERVISOR_LLM_API_KEY`, and `CYBERVISOR_LLM_MODEL`, and does not override variables already exported in the shell.

## Install

Install the CLI onto your `PATH`:

```bash
uv tool install -e .
```

After installation, verify:

```bash
cybervisor --version
```

Developer fallback if you do not want to install the CLI globally:

```bash
uv run cybervisor --version
```

## Setup

```bash
uv sync
cp .env.example .env
```

Set at least:

```bash
CYBERVISOR_LLM_API_KEY=...
# Optional overrides
# CYBERVISOR_LLM_BASE_URL=https://api.openai.com/v1
# CYBERVISOR_LLM_MODEL=auto
```

## Usage

Minimal run:

```bash
cybervisor "Create a 360 feedback system" --config cybervisor.yaml
```

Start from a specific stage:

```bash
cybervisor "Create a 360 feedback system" --start-stage "Implement"
```

Stop before a specific stage:

```bash
cybervisor "Create a 360 feedback system" --start-stage "Implement" --end-before "Verify"
```

Version and help:

```bash
cybervisor --version
cybervisor --help
```

More detail lives in:

- [Configuration](docs/configuration.md)
- [Runtime behavior](docs/runtime-behavior.md)
- [Demo and Docker](docs/demo-and-docker.md)
- [Adding an adapter](docs/adapters/adding-an-adapter.md)

## Development

Validation commands used by this repo:

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

Useful focused runs:

```bash
uv run pytest tests/integration/test_pipeline_e2e.py
uv run pytest tests/unit/test_hooks.py tests/unit/test_pipeline.py tests/unit/test_signals.py
```

Release helper:

```bash
./scripts/publish.sh
```

That script bumps the version in `pyproject.toml` with a `patch` release by default, refreshes `uv.lock`, removes the old `dist/`, builds fresh artifacts, and publishes them with `uv publish`. Pass `minor` or `major` to change the bump type.

## Specs Directory

Feature folders under `specs/` are archival implementation artifacts after delivery. The current source of truth for runtime behavior is the checked-in code plus the main project docs and constitution.

## Repository layout

```text
src/cybervisor/        Core CLI package
src/cybervisor/core_hooks/ Hook runtime and verifier logic
scripts/               Demo bootstrap and end-to-end scripts
templates/demo/        Demo project scaffold
tests/                 Unit and integration coverage
specs/                 Speckit feature artifacts
.specify/              Constitution, templates, and repo scripts
AGENTS.md              Symlink to .specify/memory/constitution.md
GEMINI.md              Symlink to AGENTS.md
CLAUDE.md              Symlink to AGENTS.md
```

## Agent docs

The agent mandate files are symlinked by design:

- `AGENTS.md` -> `.specify/memory/constitution.md`
- `GEMINI.md` -> `AGENTS.md`
- `CLAUDE.md` -> `AGENTS.md`

If mandate content needs to change, update `.specify/memory/constitution.md`, not the symlinks.
