cybervisor 0.1.3

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"

Version and help:

cybervisor --version
cybervisor --help

Minimal config:

pipeline:
  agent_tool: gemini

stages:
  - name: Spec
  - name: Review Spec
  - name: Implement
  - name: Review Code
  - name: Verify

Notes:

• hook: values are sourced from CYBERVISOR_LLM_* env vars, not from config file literals
• If a stage omits prompt_template, the default template is used
• If stages: is omitted, the default five-stage pipeline is used
• If stages: is provided, cybervisor runs the stages exactly as configured
• Stages may optionally declare a contract for required result artifacts and a next_stage for explicit success-path routing
• When a review stage can route changes_requested to a correction stage, set that review stage's next_stage explicitly for the approved path instead of relying on linear order
• Use --start-stage STAGE_NAME to skip earlier stages and begin execution at the named stage

Review/fix loop example:

pipeline:
  agent_tool: claude

stages:
  - name: Implement

  - name: Review Code
    next_stage: Verify
    prompt_template: |
      Review the implementation.
      Write the final result to .cybervisor/contracts/artifacts/Review Code.yaml.
    contract:
      allowed_statuses: [approved, changes_requested]
      routes:
        changes_requested:
          next_stage: Fix Code
          injections: [summary, details, actions]

  - name: Fix Code
    next_stage: Review Code
    prompt_template: |
      Fix the issues described by the latest review.
      Full contract:
      {latest_contract_yaml}
      Summary:
      {latest_contract_summary}
      Details:
      {latest_contract_details_yaml}
      Actions:
      {latest_contract_actions_yaml}

  - name: Verify

In this pattern:

• Review Code with status: approved goes to Verify
• Review Code with status: changes_requested goes to Fix Code
• Fix Code loops back to Review Code
• If Review Code omitted next_stage: Verify, a linear stage list would otherwise fall through to Fix Code
• Contract prompt guides live at .cybervisor/contracts/prompts/[Stage Name].md

Runtime behavior

For gemini and claude runs, cybervisor:

1. Performs preflight checks.
2. Writes shared hook runtime metadata into .cybervisor/hooks/.
3. Persists an exact settings snapshot in .cybervisor/hooks/.
4. Patches the active tool settings file so the selected agent invokes the packaged cybervisor-agent-hook entry point.
5. Starts the agent in a dedicated process group when supported.
6. Uses the runtime hook to classify autonomy decisions as approve or block, then adapts those into the selected tool's native hook output so the agent continues autonomously.
7. If the active stage declares a contract, uses the same hook runtime to block completion until the required artifact exists and is structurally valid.
8. Streams agent output into stderr and the stage log file.
9. Re-validates contract artifacts after agent exit, then routes by contract status or explicit next_stage when configured.
10. Restores settings and removes runtime files on success, failure, or interrupt.

Generated artifacts:

• .cybervisor/logs/cybervisor.log.jsonl: structured run log
• .cybervisor/logs/stages/<stage_name>.jsonl: captured transcript per stage
• .cybervisor/contracts/artifacts/*.yaml: optional stage-result artifacts for contract-enabled stages
• .cybervisor/contracts/prompts/*.md: authored contract prompt guides for contract-enabled stages

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

Manual demo workflow

The repository includes a demo bootstrap helper:

scripts/e2e-demo-project.sh

That script:

• creates a fresh demo workspace with scripts/init-demo-project.sh
• supports --agent-tool claude|gemini and defaults to claude
• optionally starts a local deterministic hook verifier stub when run with --with-local-api
• copies templates/demo/.env into the demo workspace as .env
• prints the exact cd and cybervisor command to run manually in your shell
• reminds you to install the CLI first if cybervisor is not yet on your PATH

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.