Metadata-Version: 2.4
Name: cybervisor
Version: 0.1.3
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: 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 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"
```

Version and help:

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

Minimal config:

```yaml
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:

```yaml
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:

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

## Manual demo workflow

The repository includes a demo bootstrap helper:

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

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