ControlKeel (CK) is an AI coding agent control plane for everyday governed engineering practice. Through observation, findings, and evaluation, it learns a team's intent rules, review taste, and delivery habits, and turns them into typed memory, policy checks, and proof bundles. CK sits between coding agents and production environments, acting as a portable "company brain": it compares expected delivery with actual delivery and turns raw agent intent into policy-validated tasks.
Purpose
If a team is using AI agents, it usually uses *.md files to tell them how to behave, but rule/spec files are just promises made to the model. ControlKeel's goal is to enforce output. Beyond catching defects, CK also tries to solve the "unknown unknowns" problem: there is no need to re-interpret domain knowledge in every session. Its operating principle is: spend tokens on discovery, not rediscovery. Repeated behavior goes through a human-gated deterministic promotion path; once its regression evidence passes, checks, APIs, CLIs, or workflows can handle known situations, and the agent only handles exceptions and genuinely new uncertainty.
Main capabilities
- Capture intent and policy: scope, risk, budget, domain packs, and human taste become CK state.
- Validate agent output: deterministic checks and optional advisory reviews produce findings before risky work enters the main branch.
- Gate on demand: when intent, risk, or policy requires it, high-impact operations are approved by humans.
- Persist evidence: findings, reviews, proofs, memory, costs, and task results remain after a host switch.
- Improve with evaluation: trajectories and repeated failures become bounded regression evidence for specific suites and topics.
How to use
One-line setup can be done through an agent: copy and paste the installation and run instructions into the agent (OpenCode, Codex, Claude, or another supported host). After installing the CLI, run setup and attach in the repository you want to govern. Project scope writes host files only within that repository; --scope user writes host-level files under user configuration only for hosts that explicitly support user scope, and does not turn project binding or proof state into global state. The full first-run path is in docs/getting-started.md; host realities are in docs/support-matrix.md and docs/agent-integrations.md.
Benchmark Evidence
ControlKeel includes a persistent benchmarking engine. Current user-facing evidence is limited to the following named suites, topics, and scoring definitions; docs/benchmarks.md is the authoritative reference for the full tables, caveats, JSON exports, and agent host protocol. Verified with-vs-without-CK baseline (host_comparison_v1, 12 risk scenarios): under ControlKeel 0.3.45, in the risk suite host_comparison_v1, null_policy_baseline catches 0/12; controlkeel_validate catches 12/12, blocks 9/12, hits expected rules 9/12, median deterministic validation time 52 ms, 0 provider tokens. Paired benign suite benign_baseline_v1: controlkeel_validate produces 0/10 catches, 0/10 blocks, FPR 0.000, median deterministic validation time 42 ms, 0 provider tokens. It must be understood precisely: deterministic scanner evidence is not equivalent to model-driven agent host evidence. Reproduction commands and the OpenCode/Copilot/Claude/Codex comparison protocol are in docs/benchmarks.md.
Current Deliverables
- Local governance: CLI, full local stdio MCP toolset, project binding, host mount/export packages, scanner validation, discovery, review, proof packages, budgets, and typed memory.
- Host and runtime support: native mounting for supported hosts, runtime export for headless/outer-loop systems, a narrower OAuth-hosted MCP set, minimal A2A, and fallback validation/proxy paths.
- Team/project operations: organization members, invitations, workspace GitHub repository binding, service accounts, webhooks, workspace tool policies, and policy set APIs.
- Cloud evidence paths: optional cloud telemetry, workspace keys, cloud run packages, runtime callbacks, and bidirectional sync that is dormant until configured (for discovery, review, summaries, and memory records).
- Observability loop: timeline, memory quality, cost, trends, issue clustering, evaluation candidates, benchmark drafts/history, and improvement suggestions.
Documentation
docs/README.md provides a documentation map by task; docs/getting-started.md goes from installation to the first discovery; docs/support-matrix.md is the authoritative host/protocol list; docs/agent-integrations.md explains integration mechanisms and support tiers; docs/benchmarks.md explains benchmark scoring, metadata, and claim discipline; docs/observability-feedback-loop.md explains the loop from local evidence to regression; docs/control-plane-claim-matrix.md is the README claim-to-test matrix for governance, memory, cloud sync, and human gates; docs/api-reference.md and docs/cli-reference.md are interfaces aligned with the code; docs/packages.md is the package and distribution catalog; docs/self-hosting.md is the self-hosting deployment guide.
Tech Stack
Built on Phoenix + Ecto on SQLite, using Req for HTTP communication. Single-binary builds are released via Burrito and GitHub Releases.
Limitations
The materials do not provide specific pricing, platform coverage, performance guarantees, or complete usage steps; the above benchmark data is limited to the specified suites, topics, and scoring definitions, and deterministic scanner evidence is not equivalent to model-driven agent host evidence.
