Getting Started

keel is a structural code enforcement tool for LLM coding agents. It builds a fast, incrementally-updated graph of your codebase and validates architectural contracts after every code change -- at generation time, not at review time.

Prerequisites

  • Rust 1.75+ (if building from source)
  • A codebase in TypeScript, Python, Go, or Rust (or any combination)
  • Git (recommended, for pre-commit hook integration)

Installation

Install script

terminal

$ curl -fsSL https://keel.engineer/install.sh | bash

The script detects your OS and architecture, downloads the correct binary, and places it on your PATH.

From source

terminal

$ cargo install --path crates/keel-cli

Homebrew (macOS/Linux)

terminal

$ brew tap FryrAI/keel

$ brew install keel

Verify installation

terminal

$ keel --version

Initialize keel in your project

~/your-project

$ cd your-project

$ keel init

keel initialized. 2 language(s) detected, 147 files indexed.

Next steps:

keel map        Build the structural graph

keel compile    Validate contracts

keel init does the following:

  1. Detects languages -- scans file extensions to find TypeScript, Python, Go, and Rust files
  2. Creates .keel/ -- configuration directory with keel.json, graph.db, and cache/
  3. Creates .keelignore -- default ignore patterns for node_modules/, __pycache__/, target/, dist/, build/, .next/, vendor/, .venv/
  4. Installs a git pre-commit hook -- runs keel compile before each commit
  5. Detects AI tool directories -- finds .cursor/, .windsurf/, .aider/, .continue/

Build the structural graph

terminal

$ keel map

Parses every source file using tree-sitter, builds resolution edges (calls, imports, contains), and stores the complete graph in .keel/graph.db. For a 100k LOC codebase, this takes under 5 seconds.

Use --depth to control output verbosity:

  • --depth 0 -- Summary only: file count, node count, edge count
  • --depth 1 -- Modules + hotspots (default)
  • --depth 2 -- Functions with signatures
  • --depth 3 -- Full graph detail

Validate your code

terminal

$ keel compile src/auth.ts

Clean compile: exit code 0, empty stdout. This is by design -- when everything is fine, the agent sees nothing and moves on.

Violations found: exit code 1 with structured output. Every error includes a fix_hint with actionable remediation, a confidence score, and a resolution_tier.

keel compile --json

$ keel compile src/auth.ts --json

{

"errors": [{

"code": "E001",

"message": "broken caller: login() calls authenticate()..."

"fix_hint": "Update login() to use verifyCredentials()"

}]

}

Output formats

keel supports three output formats via global flags:

  • --json -- Structured JSON for programmatic consumption and CI pipelines
  • --llm -- Token-optimized text for LLM agents (minimal tokens, maximum signal)
  • (default) -- Human-readable for terminal use

Next steps

  • Command Reference -- full documentation for every keel command
  • Agent Integration -- wiring keel into Claude Code, Cursor, Windsurf, and other tools
  • Configuration -- customizing enforcement rules, circuit breaker, and batch mode
  • FAQ -- troubleshooting and common questions