Autonomous engineering protocol for Claude Code: safe by default, verified before stop, and built to ship.

Kova drops into any project and turns Claude Code from "assistant that asks" into "engineering system that executes, verifies, and self-corrects."

claude /install kova          # Lightweight: commands + skills
claude /install kova-full     # Full suite: + hooks + enforcement

That's it — no cloning, no scripts. Commands and skills are available immediately.

# Clone Kova
git clone https://github.com/ChiFungHillmanChan/kova.git ~/kova

# Go to your project
cd /path/to/your/project

# Preview what will be installed
bash ~/kova/install.sh --dry-run

# Install Kova into this project
bash ~/kova/install.sh

Optional global CLI:

# Install global CLI
bash ~/kova/install.sh --global

# Activate hooks for this project
kova activate

# Verify setup
kova status

Choose kova if you want the workflow without enforcement. Choose kova-full if you want the full autonomous engineering system.

Requirements: Claude Code, jq (required), gh (optional), @openai/codex (optional)

• Safe by default — blocks dangerous commands (rm -rf /, DROP TABLE, force push) and protects secrets
• Verified before stop — fast stop gate (lint + typecheck) catches errors on every stop; full 7-layer verification runs in the Team Loop
• Autonomous but bounded — retry, rate limiting, and circuit breaker prevent runaway loops
• Multi-model review — Claude agents + optional OpenAI Codex cross-model review
• Works across stacks — Node.js, Python, Go, Rust, Ruby, Java, .NET (auto-detected)

The Team Loop (/kova:loop) is bash-orchestrated — Claude is the worker, bash is the boss:

  ┌─────────────────────────────────────────────┐
  │           kova-loop.sh (bash)               │
  │  Controls flow, runs verification, reviews  │
  └──────────────────┬──────────────────────────┘
                     │
    For each PRD item:
                     │
       ┌─────────────▼─────────────┐
       │   claude -p (implement)   │  ← Separate session per iteration
       └─────────────┬─────────────┘
                     │
       ┌─────────────▼─────────────┐
       │  verify-gate.sh (bash)    │  ← Build, test, lint, typecheck
       │  Claude CANNOT skip this  │
       └─────────────┬─────────────┘
                     │
              pass?──┤
              │      │ fail → diagnostic prompt → retry
              ▼
       ┌─────────────────────────────┐
       │  run-code-review.sh (bash)  │  ← Separate claude -p session
       └─────────────┬───────────────┘
                     │
              pass?──┤
              │      │ HIGH issues → fix prompt → retry
              ▼
       ┌─────────────────────────────┐
       │  git commit (bash)          │
       └─────────────────────────────┘

Why bash orchestration? Prompt-based self-orchestration can be skipped. When bash runs verification after Claude exits, skipping is impossible.

kova help          # Show all commands
kova status        # Check hooks, stack, installed commands
kova activate      # Turn ON hooks
kova deactivate    # Turn OFF hooks

See the full guide for detailed explanations of each feature.

Automated tests across three suites:

npm install     # Install test dependencies
npm test        # Run all tests
npm run lint    # ShellCheck all scripts

CI runs on both Linux and macOS for every PR. See CONTRIBUTING.md for details.

"You don't trust; you instrument."

The goal isn't to hope Claude does the right thing. It's to build a system where hooks make the wrong thing hard. As AI models get stronger, your system gets stronger automatically.

What hooks guarantee (when active):

• Every stop triggers lint + typecheck (fast stop gate)
• Every file write is checked against the protected files list
• Every bash command is checked against the dangerous commands list
• The Team Loop runs full 7-layer verification via bash instead of relying on prompt compliance

What hooks do NOT guarantee:

• Hooks can be disabled by the user (kova deactivate or editing settings.json)
• The stop gate runs lint + typecheck only — build, tests, and security run in the Team Loop
• File protection uses pattern matching, not OS-level permissions
• Hooks require jq to be installed; without it, they exit silently