cybervisor 0.2.0

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 For Use In Another Project

Install the CLI onto your PATH:

uv tool install cybervisor

After installation, verify:

cybervisor --version

If you prefer pip:

pip install cybervisor

Quick Start In Your Project

In the project you want cybervisor to supervise, bootstrap the default scaffold:

cybervisor init

That creates:

• cybervisor.yaml
• .cybervisor/contracts/prompts/Specify.md
• .cybervisor/contracts/prompts/Review Spec.md
• .cybervisor/contracts/prompts/Plan.md
• .cybervisor/contracts/prompts/Tasks.md
• .cybervisor/contracts/prompts/Review Code.md
• .cybervisor/contracts/prompts/Verify.md

Export your verifier credentials in that project shell, or create a local .env file there:

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

Then run cybervisor from that project directory:

cybervisor "Create a 360 feedback system"
# equivalent explicit form
cybervisor run "Create a 360 feedback system"

cybervisor expects cybervisor.yaml in the current working directory by default, writes runtime files under .cybervisor/, and patches the selected agent's local settings during the run so the packaged hook can enforce autonomy and contract rules. For the standalone default scaffold, planning and implementation handoffs live in stage contract artifacts under .cybervisor/contracts/artifacts/, and each run resets both .cybervisor/contracts/artifacts/ and any leftover .cybervisor/artifacts/ state before the first stage starts.

Usage

cybervisor "Create a 360 feedback system"
cybervisor run "Create a 360 feedback system"

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

What You Need In The Target Project

• A cybervisor.yaml file in the project root, or --config pointing to one
• gemini or claude installed on PATH for real runs, or mock for deterministic local testing
• CYBERVISOR_LLM_API_KEY set for non-mock runs
• Write access to the project directory so cybervisor can create .cybervisor/

Develop cybervisor Itself

If you want to contribute to this repository rather than use the packaged CLI in another repo:

uv sync
uv run cybervisor --version

Local env for this repo can be bootstrapped from:

cp .env.example .env

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
assets/hooks/          Hook prompt assets and fixtures
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.