Agent Integration

keel is designed to be called by LLM coding agents after every code modification. The integration pattern is the same across all tools:

  1. Session start -- run keel map --llm to give the agent structural context
  2. After every file edit -- run keel compile <file> --llm to validate the change

Claude Code

Claude Code supports lifecycle hooks via .claude/settings.json:

.claude/settings.json

{

"hooks": {

"SessionStart": [

{ "command": "keel map --llm --depth 1" }

],

"PostToolUse": [

{

"tools": ["Edit", "Write", "MultiEdit"],

"command": "bash scripts/post-edit.sh $FILE"

}

]

}

}

Cursor

Cursor uses .cursor/hooks.json for lifecycle hooks and .cursor/rules/ for instruction files.

.cursor/hooks.json

{

"hooks": {

"session_start": [{ "command": "keel map --llm" }],

"post_tool_use": [{

"tools": ["edit_file", "create_file"],

"command": "bash scripts/post-edit.sh $FILE"

}]

}

}

Gemini CLI

Gemini CLI uses .gemini/settings.json for hooks and GEMINI.md for instructions. Same hook pattern as above.

Windsurf

Windsurf uses .windsurf/hooks.json for hooks and .windsurfrules for instructions. Same hook pattern.

Aider

Aider uses .aider.conf.yml for configuration:

.aider.conf.yml

lint-cmd: keel compile --llm

auto-lint: true

This runs keel compile after every edit and feeds violations back to the model.

GitHub Copilot

Copilot reads .github/copilot-instructions.md. Add keel commands and the compile-after-edit pattern to that file.

MCP server mode

For tools that support MCP (Model Context Protocol), keel can run as a persistent tool server:

terminal

$ keel serve --mcp

This exposes keel's commands as MCP tools that the agent can call directly, without shell exec. Supports compile, discover, where, explain, map, and fix.

Universal fallback: AGENTS.md

For any tool that reads a project-level instruction file, create AGENTS.md at the project root with the compile-after-edit workflow. This covers tools not listed above and future tools that follow the convention.

Hook workflow

SessionStart

Runs keel map --llm --depth 1 once at session start. Gives the agent a structural overview: modules, hotspots, graph shape. Costs roughly 200-500 tokens depending on project size.

PostToolUse (post-edit)

Runs after every file edit. If exit 0 (clean compile): outputs nothing. If exit 1 (violations): outputs violations in LLM format. This keeps the agent in a tight validate-fix loop without wasting tokens on clean compiles.

Batch mode

During rapid scaffolding, use batch mode to defer non-critical checks:

terminal

$ keel compile --batch-start

# ... agent creates multiple files ...

$ keel compile --batch-end

Batch mode defers type hint (E002), docstring (E003), and placement (W001) checks. Structural errors (E001, E004, E005) still fire immediately. Auto-expires after 60 seconds of inactivity.