Configuration

keel stores all configuration in the .keel/ directory at your project root. This directory is created by keel init.

.keel/keel.json

The main configuration file. All fields have sensible defaults -- you only need to modify values you want to change.

.keel/keel.json

{

"version": "0.1.0",

"languages": ["typescript", "python"],

"enforce": {

"type_hints": true,

"docstrings": true,

"placement": true

},

"circuit_breaker": { "max_failures": 3 },

"batch": { "timeout_seconds": 60 }

}

Enforcement settings

enforce.type_hints

When true, functions without type annotations produce E002 errors. Applies primarily to Python (which requires explicit annotations) and JavaScript (which requires JSDoc @param/@returns). TypeScript, Go, and Rust are already statically typed.

enforce.docstrings

When true, public functions without docstrings produce E003 errors.

enforce.placement

When true, functions placed in modules where they don't structurally belong produce W001 warnings. keel measures edge affinity -- how many call edges connect the function to its current module vs. other modules.

Circuit breaker

The circuit_breaker.max_failures setting controls how many consecutive failures on the same error-code + hash pair are allowed before auto-downgrade:

  • Attempt 1: Reports the error with a fix_hint
  • Attempt 2: Reports with wider discover context
  • Attempt N (max_failures): Auto-downgrades to WARNING

Resets on success or a different error on the same symbol. Default: 3.

Batch mode

The batch.timeout_seconds setting controls how long batch mode stays active before auto-expiring. During batch mode, E002 (type hints), E003 (docstrings), and W001 (placement) checks are deferred. Structural errors (E001, E004, E005) still fire immediately.

.keelignore

A gitignore-syntax file specifying which files and directories keel should skip. Created by keel init with defaults for node_modules/, __pycache__/, target/, dist/, build/, .next/, vendor/, .venv/.

.keelignore

# Generated protobuf code

src/generated/

# Test fixtures with intentional violations

tests/fixtures/bad-code/

# Specific files

config/legacy-router.ts

After modifying .keelignore, run keel map to rebuild the graph without excluded files.

.keel/ directory structure

  • keel.json -- Main configuration (commit to version control)
  • graph.db -- SQLite structural graph (add to .gitignore)
  • cache/ -- Incremental parsing cache
  • telemetry.db -- Compilation history for keel stats
  • session.json -- Temporary session state (batch mode, circuit breaker)

Example configurations

Strict (new project)

keel.json — strict

{ "enforce": { "type_hints": true, "docstrings": true, "placement": true },

"circuit_breaker": { "max_failures": 1 } }

Relaxed (legacy codebase)

keel.json — relaxed

{ "enforce": { "type_hints": false, "docstrings": false, "placement": true },

"circuit_breaker": { "max_failures": 5 },

"ignore_patterns": ["src/legacy/**"] }

Minimal (structural errors only)

keel.json — minimal

{ "enforce": { "type_hints": false, "docstrings": false, "placement": false } }

This only fires on structural errors (E001 broken callers, E004 function removed, E005 arity mismatch) -- violations that cannot be ignored.