cybervisor 0.1.5

Autonomous CLI supervisor for staged AI workflows

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
• 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:

uv tool install -e .

After installation, verify:

cybervisor --version

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

uv run cybervisor --version

Setup

uv sync
cp .env.example .env

Set at least:

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

Usage

Minimal run:

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

Start from a specific stage:

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

Stop before a specific stage:

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

Version and help:

cybervisor --version
cybervisor --help

More detail lives in:

• Configuration
• Runtime behavior
• Demo and Docker
• Adding an adapter

Development

Validation commands used by this repo:

uv run mypy --strict src
uv run pytest

Useful focused runs:

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:

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

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.