ControlKeel
Turns engineering habits into enforceable policy gates, persistent evidence, and reusable memory for coding agents.
- Source repo
- aryaminus/controlkeel
- Stars
- ★ 11
- Last updated
- today
- License
- NOASSERTION
- Primary language
- Elixir
- FA score
- 59/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformCodexClaude Code (Partial support)
- You'll need
- Typical use
- A development team using Codex, Claude, OpenCode, or another supported host wants consistent checks before agent-generated changes reach the main branch.
- Main limitation
- Integration depth varies: the material distinguishes native attachment, a narrower OAuth-scoped hosted MCP set, minimal A2A, and fallback validation or proxy paths, so teams must verify the tier for each host.
- Source review
- 59/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
ControlKeel is a governance control plane for AI-assisted engineering that compares intended delivery with actual changes before risky work reaches the main branch. It ships a CLI, a full local stdio MCP tool set, project binding, host attachment, runtime exports, and records for findings, reviews, proof bundles, budgets, typed memory, and task outcomes. Its workflow captures scope, risk, budget, domain rules, and human review preferences, then applies deterministic validation and optional advisory review with human approval where policy requires it. Evidence can remain local, while opt-in cloud telemetry, workspace keys, cloud run packages, callbacks, and configurable synchronization provide additional team paths. Development uses Phoenix and Ecto on SQLite, with single-binary builds distributed through Burrito and GitHub Releases.
ControlKeel initializes governance state with controlkeel setup and connects a supported coding-agent host through controlkeel attach <host>; when only MCP is available, the documented path is ck_attach. controlkeel attach doctor diagnoses the host connection, controlkeel provider doctor checks provider configuration, controlkeel status reports state, and controlkeel findings displays recorded findings. During governed work it evaluates agent output against captured scope, risk, budget, domain packs, and human preferences, runs deterministic scans and optional advisory review, blocks or requests approval when policy calls for it, and persists findings, reviews, proof bundles, memory, cost, and task outcomes. Its observability loop also organizes timelines, trends, problem clusters, eval candidates, benchmark drafts and history, and promotion advisories so recurring failures can become bounded deterministic checks backed by regression evidence.
- A development team using Codex, Claude, OpenCode, or another supported host wants consistent checks before agent-generated changes reach the main branch.
- A DevSecOps group needs security or compliance rules that can block high-impact actions while retaining findings and proof bundles.
- An engineering organization that changes agent hosts wants project binding, MCP, host attachment, and runtime exports to preserve governance evidence and typed memory.
- A team with extensive domain conventions wants recurring review preferences and delivery habits enforced instead of repeatedly explaining them to a model.
- An agent-evaluation team wants to turn traces and repeated failures into regression evidence tied to specific suites and subjects.
How do you install or deploy this agent?
Choose one of the documented installation routes. The supplied material does not state minimum versions for Node.js, Homebrew, or supported operating systems, and it does not identify credentials required for the initial local run.
Homebrew:
brew tap aryaminus/controlkeel && brew install controlkeelnpm:
npm i -g @aryaminus/controlkeelRelease installer:
curl -fsSL https://github.com/aryaminus/controlkeel/releases/latest/download/install.sh | shWindows PowerShell:
irm https://github.com/aryaminus/controlkeel/releases/latest/download/install.ps1 | iexSource development requires the Elixir Mix toolchain; the documented development sequence is:
mix setup
mix phx.server
mix test
mix precommitHow do you use this agent?
Run the first setup from the repository you want to govern. This documented example attaches OpenCode; substitute another supported host name where applicable.
controlkeel
controlkeel setup
controlkeel attach opencode
controlkeel attach doctor
controlkeel provider doctor
controlkeel status
controlkeel findingsProject scope is the default and writes host files only inside that repository. Use --scope user only for targets that explicitly support user scope; it writes host-level user configuration but does not make project binding or proof state global. Restart the host after attachment or plugin changes. Workspace trust, manual provider configuration, a required restart, or a plan-review approval that cannot auto-wait may require human action. If ControlKeel is exposed only through MCP, call ck_attach for the current host.
What are this agent's strengths and limitations?
- It provides CLI, local stdio MCP, native host attachment, and runtime-export paths rather than requiring a single agent-host interface.
- It can perform deterministic policy validation, gate high-impact work, and persist findings, reviews, and proof bundles instead of only suggesting behavior.
- Typed memory, costs, task outcomes, eval evidence, and promotion advisories form a concrete path from recurring failures to regression-backed checks.
- Its bounded public baseline reports that version 0.3.45 caught 12 of 12 risky
host_comparison_v1scenarios, blocked 9, and used zero provider tokens for deterministic validation.
- Integration depth varies: the material distinguishes native attachment, a narrower OAuth-scoped hosted MCP set, minimal A2A, and fallback validation or proxy paths, so teams must verify the tier for each host.
- Initial integration may require workspace trust, manual provider configuration, and a host restart, preventing a uniformly unattended setup.
- The published evidence is limited to named suites, subjects, and scoring definitions; deterministic scanner results are not proof of model-backed performance across arbitrary repositories.
- The repository license is reported as
NOASSERTION, and no verifiable license terms are included in the supplied material. - Bidirectional cloud synchronization is dormant until configured, while cloud paths add decisions around workspace keys, telemetry, run packages, and callbacks.
How does this agent compare with similar options?
Compared with relying only on an *.md file that tells a model how to behave, ControlKeel is designed to inspect actual output and express recurring expectations as typed memory, policy checks, findings, and proof bundles. In the named host_comparison_v1 suite, null_policy_baseline caught 0 of 12 risky scenarios while controlkeel_validate caught 12 of 12; that result is bounded to the documented suite and should not be generalized to every host or repository.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| ControlKeel This agent | 59 · Major gaps | ★ 11 | today | Elixir | Codex |
| Jev Review | 81 · Good | ★ 177 | 7d ago | TypeScript | Codex · Claude Code |
| Alas Agent Workspace | 78 · Good | ★ 18 | today | Swift | Codex · Claude Code |
| Bug Hunter | 79 · Good | ★ 514 | 1mo ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows project-scoped attachment defaults to writes inside the repository, user scope is limited to explicitly supported targets, and workflows declare focused contents/read, packages/write, or contents/write permissions. The README calls for human approval of high-impact actions and pauses for workspace trust, provider configuration, restarts, or plan approval; it also outlines local versus opt-in cloud paths and major persisted data classes. Deductions apply because most controls are descriptive rather than supported by implementation here, sensitive-data guidance is limited to log redaction and use of the built-in GITHUB_TOKEN, third-party Actions use mutable major-version tags rather than commit digests, installation pipes remote scripts directly into interpreters, and no uninstall, rollback, or recovery procedure is documented. Repository, account, and copyright attribution are visible, but the unverified publisher identity is not inferred beyond that evidence.
The product loop, feature inventory, setup sequence, and shown build/release workflows are broadly consistent, and the version workflow rechecks the main-branch commit before pushing. Deductions apply because the referenced support matrix, dependency manifests, implementation, and tests are absent, preventing static confirmation of dependency availability or claimed runtime behavior. Doctor, status, and findings commands suggest diagnostic entry points, but actual failure messages, degradation behavior, and recovery examples are not shown.
The material identifies teams using several coding-agent hosts and covers local governance, hosted MCP, headless runtimes, team operations, and self-hosting. It distinguishes project and user scope, native attachment, runtime exports, and MCP fallback, while identifying risk, intent, and policy as gating triggers and naming conditions that require a pause. Deductions apply because exact host boundaries are delegated to unavailable documents, and the evidence does not show rule-matching configuration, false-trigger handling, or complete prerequisites across environments.
The README has strong organization covering quick start, product loop, current capabilities, benchmark framing, a documentation map, and development commands. It provides three principal installation channels plus Windows instructions, and the full Apache-2.0 license is present. Naming is reasonably consistent across the CLI, MCP surface, and runner image, with release badges and an automated patch-version/CHANGELOG workflow. Deductions apply because no FAQ, CHANGELOG contents, package catalog, or migration policy is supplied; limitations appear mainly as scope notes and benchmark caveats; and maintenance responsibility is limited to a repository account and copyright name without a clear support route, response commitment, or verified organizational identity.
The proposed outputs—findings, reviews, proof bundles, budgets, typed memory, timelines, and evaluation evidence—are usable governance artifacts. The README reports risky and benign comparisons against a null-policy baseline, including latency and zero provider-token figures, providing bounded support for marginal value and some cost-benefit value. Deductions apply because the benchmark definitions, JSON results, implementation, and tests are not included here, so the figures cannot be checked, and setup, maintenance, false-positive investigation, cloud, and human-approval costs are not quantified.
The README maps important claims to benchmark, claim-matrix, support-matrix, and API/CLI documents and explicitly separates deterministic scanner evidence from model-backed agent-host evidence, showing useful fact/inference discipline. The workflows independently support the narrower image-publication and version-update claims. Deductions apply because the cited validation documents, tests, exports, and implementation are not part of the supplied material, leaving most product and benchmark claims traceable only to one source and weakly corroborated.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- The quick-install commands pipe remote shell or PowerShell scripts directly into an interpreter; pin a release and inspect those scripts before enterprise use.
- No rollback, uninstall, or state-recovery procedure is supplied; establish backup and recovery steps before allowing writes to host configuration, policy state, or cloud records.
- The benchmark figures and claims of determinism or enforcement lack the referenced tests, implementation, and exported results in this evidence set and should not be treated as independently reproduced.
- Third-party GitHub Actions are referenced by v3/v4/v6 tags rather than immutable commit digests; stricter supply-chain environments should pin and review them.
- The concrete fields, retention, destinations, and deletion controls for cloud sync, telemetry, workspace keys, and webhooks are not shown; verify them before enabling cloud features.
FAQ
Does local validation necessarily incur model-provider cost?
Will setup write outside my repository?
--scope user writes user configuration only for targets that explicitly support it, and it does not globalize project binding or proof state.Is the cloud service mandatory?
What should I check when attachment fails?
controlkeel attach doctor, controlkeel provider doctor, and controlkeel status; also verify workspace trust and restart the host after attachment or plugin changes.