Your AI agent tried rm -rf / to "clean build artifacts." Kavex blocked it. You didn't even notice.

Kavex is an open-source safety layer that sits between AI coding agents and your system. It blocks catastrophic commands, protects secrets, and verifies every code change — so you can let AI work autonomously without babysitting.

"You don't trust AI. You instrument it." — Claude is the worker. Bash is the boss.

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

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

# Clone Kavex
git clone https://github.com/ChiFungHillmanChan/kavex.git ~/kavex

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

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

# Install Kavex into this project
bash ~/kavex/install.sh

Optional global CLI:

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

# Activate hooks for this project
kavex activate

# Verify setup
kavex status

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

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

AI coding agents are powerful enough to write production code — and powerful enough to destroy production systems. Most setups have zero guardrails between "AI suggests command" and "command executes."

• Blocks before execution — rm -rf /, DROP TABLE, git push --force, eval/base64 obfuscation — all caught
• Protects secrets — .env, .pem, credentials, API keys — AI can't touch them
• Verifies every change — 7-layer gate: build, test, lint, typecheck, security
• Self-corrects — failures trigger diagnostic + retry; 3 failures spawn a fresh self-healing session
• Circuit breaker — detects stuck loops, kills them, writes actionable reports
• Works across 7 stacks — Node.js, Python, Go, Rust, Ruby, Java, .NET (auto-detected)

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

  ┌─────────────────────────────────────────────┐
  │           kavex-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.

kavex help          # Show all commands
kavex status        # Check hooks, stack, installed commands
kavex activate      # Turn ON hooks
kavex 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 (kavex 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, hooks block operations (fail-closed) for safety