keel-companion-plugin

KEEL

Local-first anti-drift companion for AI coding agents.

KEEL keeps AI agents (Claude Code, Codex) honest while they work on your codebase. It tracks what the agent said it would do, detects when work drifts from the plan, and blocks "done" until reality matches intent.

No cloud. No MCP runtime dependency. Just YAML artifacts in .keel/ and a CLI.

Early alpha / proof of concept. The core ideas work and the companion loop is real, but expect rough edges, breaking changes, and missing features. Feedback and contributions welcome.

The Companion — Why KEEL Exists

The companion is what makes KEEL fundamentally different from a linter or a one-shot audit tool. It's a persistent, real-time awareness loop that runs alongside your AI agent and catches drift as it happens, not after.

AI agents don't self-correct. They commit to a plan, then silently wander. By the time a human reviews the PR, the damage is done — wrong files touched, scope ballooned, the "done" claim doesn't match the goal. The companion closes that feedback loop in real-time. The agent gets a drift warning while it's still in the session, early enough to course-correct.

What it does:

• Polls the repo every 2 seconds in the background
• On every file change: re-runs validation, drift detection, traceability, and cluster analysis
• Updates the current brief, alert feed, and heartbeat in real-time
• Pushes drift notifications into the agent's status line and hooks — the agent sees drift during the tool call that caused it, not 10 minutes later
• Writes a heartbeat so the status line, hooks, and other tools can verify the companion is alive and fresh

Resilience:

• Per-cycle error handling with exponential backoff — a single bad awareness pass doesn't kill the companion
• Logs exit reason on any shutdown (crash, signal, error cascade)
• Detects dead processes and writes truthful state — no stale "running: true" lies
• Heartbeat staleness detection tells you if the companion is alive but stuck vs. actually dead

keel companion status   # check if alive, fresh, and token-matched
keel companion start    # start if not running
keel companion stop     # stop gracefully

Guardrails — What's Working Now, What's WIP

KEEL is being built to create hard stops that prevent AI agents from causing further damage once drift is detected. Some guardrails are already in place. Others are work in progress.

Working now:

• Real-time drift detection — the companion catches scope creep, plan drift, and goal drift as files change
• Done-gate blocking — keel done refuses to pass until reality matches the declared goal and plan
• Confidence labeling — every signal says whether it's proven or a guess, so agents can't treat heuristics as facts
• Alert feed into agent context — Claude Code sees drift warnings in its status line and hooks during the session, not after
• Cluster detection — repeated weak signals roll up into a probable drift warning before they become a real problem
• Checkpoint/recover flow — keel recover automatically creates a checkpoint the moment it detects drift, freezing the current state as a recovery anchor before producing a concrete route back — the agent can't lose the "last known good" point
• Development guide — keel guide gives contextual coaching for the current step: what to do, what to avoid, when you're done — adapts to your phase, goal mode, and active warnings
• Teaching drift — every drift rule includes a plain-language explanation of why it matters, so agents learn spec-driven development instead of just getting flagged
• Repo-aware planning — keel plan generates steps specific to your actual codebase: real file paths, real unknowns, real entrypoints — not a generic template
• Step advancement — keel advance marks the current step done, auto-checkpoints, and advances to the next step in the plan
• Auto-replan detection — the companion watches for accumulating drift warnings and suggests keel replan when the plan no longer matches reality
• Pre-edit hard stop — a PreToolUse hook intercepts Write/Edit before they execute. If the target file is outside the active plan step and no delta covers it, the edit is blocked. The agent must keel delta, keel replan, or keel advance to proceed. Managed paths (.keel/, .claude/, .codex/) are always allowed.

WIP — building toward more hard stops:

• Automatic session pause — when drift severity hits a threshold, force the agent to stop and get human confirmation before continuing
• Budget/token guardrails — detect when an agent is churning (lots of edits, no progress) and interrupt the loop
• Cross-agent consistency — if Claude Code and Codex both touch the same repo, detect conflicting intent