FAQ

Performance

keel compile is slow

It should not be. keel compile targets <200ms for a single file. Check:

  • Are you running a release build? Debug builds are 10-20x slower. Build with cargo build --release or install with cargo install --path crates/keel-cli.
  • Is the graph database corrupted? Run keel map to rebuild from scratch.
  • Are you compiling too many files? Pass specific file paths for incremental validation: keel compile src/auth.ts.

keel map takes a long time

keel map targets <5s for 100k LOC. Check .keelignore to make sure node_modules/, vendor/, and other large directories are excluded.

Resolution

keel can't find my function

  1. Run keel map to refresh the graph. The function may have been added after the last map.
  2. Check .keelignore -- the file may be excluded.
  3. Verify the file has a supported extension (.ts, .tsx, .js, .jsx, .py, .go, .rs).
  4. Use keel where <hash> to check if the hash resolves.

False positive violation

keel's circuit breaker handles repeated false positives automatically. After max_failures consecutive failures on the same error, it auto-downgrades to a WARNING.

To investigate: run keel explain <error_code> <hash> to see the full resolution chain.

To suppress for one run: keel compile --suppress E002 src/legacy.py.

Low-confidence warning on trait/interface dispatch

Expected behavior. Dynamic dispatch produces low-confidence call edges. keel reports these as warnings, not errors, to avoid false positives. Use keel explain to inspect the resolution tier.

Configuration

How do I ignore a file?

Add the path or pattern to .keelignore. The syntax is identical to .gitignore:

.keelignore

# Ignore a specific file

src/generated/schema.ts

# Ignore a directory

test/fixtures/

After modifying, run keel map to rebuild the graph.

keel init says .keel/ already exists

Run keel deinit first, then keel init again.

How do I change enforcement rules?

Edit .keel/keel.json. Changes take effect on the next keel compile or keel map. No restart needed. See Configuration for details.

General

Does keel work offline?

Yes, 100%. keel is a single binary with zero runtime dependencies and no network calls. Everything runs locally against your filesystem and the .keel/graph.db SQLite database.

Does keel modify my code?

Only with keel fix --apply. All other commands are read-only. keel fix without --apply outputs a plan but does not touch any files.

What's the hash format?

Every symbol gets an 11-character hash: base62(xxhash64(canonical_signature + body_normalized + docstring)). Deterministic -- the same code always produces the same hash. Changes when the function signature, body, or docstring changes.

How do I update keel?

terminal

# Via install script

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

# Via Homebrew

$ brew upgrade keel

# From source

$ cargo install --path crates/keel-cli --force

After updating, run keel map to rebuild the graph.

Can I use keel without AI tools?

Yes. keel works as a standalone structural linter. Pre-commit hooks run automatically after keel init. Add keel compile --strict --json to your CI pipeline to fail builds on violations.

Which languages are supported?

TypeScript, JavaScript (with JSDoc), Python, Go, and Rust. keel uses tree-sitter for universal parsing and per-language enhancers for deeper resolution:

  • TypeScript/JavaScript -- Oxc (oxc_resolver + oxc_semantic)
  • Python -- ty (subprocess)
  • Go -- tree-sitter heuristics
  • Rust -- rust-analyzer (lazy-load)

What does "clean compile" mean?

Zero errors + zero warnings = exit code 0, empty stdout. The structural graph is consistent and all contracts are satisfied. The agent sees nothing and moves on.