ControlKeel

io.github.aryaminusPublished by GitHub account aryaminusv0.2.29Updated Oct 24, 2026

Governed MCP workflows with policy validation, findings tracking, and review gates.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

A local stdio MCP server that sits between coding agents and production, validating agent output against team policy and recording findings, reviews and proof.

What you can do
Capture intent and policy: scope, risk, budget, domain pack and human taste become stored state for the project, with typed memory that persists across host switches and sessions. Validate agent output: deterministic checks and optional advisory review produce findings before risky work reaches main. Gate high-impact actions: humans approve when intent, risk or policy requires it. Persist evidence: findings, reviews, proofs, costs and task outcomes survive host changes. Improve with evals: traces and recurring failures become bounded regression evidence, and recurring behavior can be promoted through a human-gated path.
When to use it
Worth adding when a team already uses coding agents and wants their rules, review taste and delivery habits enforced rather than merely written in a rules file, especially where risky changes need validation, findings and human approval gates before reaching main.
Requirements
Runs as a local process on the user's machine via npx from the npm package, or through the CLI installed by Homebrew, npm or the release installers. Setup and attach are run from the repository to be governed; project scope writes host files only inside that repository. No authentication, environment variables or headers are declared in the manifest.
Before you install
It writes host files and attaches to agent hosts, and some changes need a host restart or workspace trust. It can gate and block actions, so misconfigured policy may block legitimate work. Optional cloud telemetry, workspace keys and sync are opt-in and send findings, reviews, digests and memory records to a third party once configured. The README's one-line setup asks an agent to fetch remote docs and install software, so review it before running.

Installation

In SourceWeft

  1. Open ControlKeel in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ControlKeel

[CI] [Release Smoke] [Latest Release] [npm bootstrap] [Socket Badge] [controlkeel MCP server]

Turn the way your team works into enforceable memory for AI agents. - @arya_minus

ControlKeel is an agent control plane for day-to-day governed engineering. Through observation, findings and evaluation, it learns your intent rules, review taste and delivery habits, turning them into typed memory, policy checks and proof bundles. CK sits between your coding agents and production as a portable "company brain": comparing intended delivery against actual delivery and turning raw agent intent into policy-validated tasks.

If you're using an AI agent today, you probably have an *.md telling it how to behave. But a rules/specs file is just a promise made to the model. ControlKeel enforces the output. Beyond just catching bugs, CK solves the "Unknown Unknowns" problem: having to re-explain your domain knowledge in every single session.

Product loop

  1. Capture intent and policy — scope, risk, budget, domain pack, and human taste become CK state.
  2. Validate agent output — deterministic checks and optional advisory review produce findings before risky work reaches main.
  3. Gate only when needed — humans approve high-impact actions when intent, risk, or policy requires it.
  4. Persist evidence — findings, reviews, proofs, memory, cost, and task outcomes survive host switches.
  5. Improve with evals — traces and recurring failures become bounded regression evidence for specific suites and subjects.

The operating rule is simple: spend tokens on discovery, not rediscovery. Recurring behavior moves through a human-gated deterministic promotion path; once its regression evidence passes, checks, APIs, CLIs, or workflows handle the known case and agents handle only exceptions and genuinely new uncertainty.

ControlKeel transforms your domain knowledge from "raw" intent and "shelfware" documentation into a living system that remembers, enforces, and evolves.

Quick start

One-line setup via your agent

Copy/paste this into your agent (OpenCode, Codex, Claude, or another supported host):

text
Set up ControlKeel for this repository. Read and follow https://raw.githubusercontent.com/aryaminus/controlkeel/main/README.md, https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/getting-started.md, https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/support-matrix.md, and https://raw.githubusercontent.com/aryaminus/controlkeel/main/docs/agent-integrations.md. Install ControlKeel if missing, run `controlkeel setup`, detect this agent host, attach the strongest supported path with `controlkeel attach <host>`, then run `controlkeel attach doctor`, `controlkeel provider doctor`, `controlkeel status`, `controlkeel findings`, and the host-native MCP check. If CK is available only as MCP, call `ck_attach` for this host. Apply only safe local fixes and redact secrets from logs. Pause and ask before continuing if the host needs workspace trust, manual provider configuration, a restart after attach/plugin changes, or a plan-review approval that cannot auto-wait. Ensure the project is trusted and restart the host after attach/plugin changes.

CLI install

Install the CLI:

bash
brew tap aryaminus/controlkeel && brew install controlkeel# ornpm i -g @aryaminus/controlkeel# orcurl -fsSL https://github.com/aryaminus/controlkeel/releases/latest/download/install.sh | sh

Windows PowerShell:

powershell
irm https://github.com/aryaminus/controlkeel/releases/latest/download/install.ps1 | iex

First governed run:

bash
controlkeelcontrolkeel setupcontrolkeel attach opencode   # project scope by default; use another supported host as neededcontrolkeel attach doctorcontrolkeel provider doctorcontrolkeel statuscontrolkeel findings

Run setup and attach from the repository you want to govern. Project scope writes host files only inside that repository. --scope user writes host-level files under your user configuration only for targets that explicitly support user scope; it does not turn project binding or proof state into global state.

For the complete first-run path, use docs/getting-started.md. For host truth, use docs/support-matrix.md and docs/agent-integrations.md.

Benchmark-backed evidence

ControlKeel includes a persisted benchmark engine. Current user-facing evidence is bounded to the named suite, subject, and scoring definition below; docs/benchmarks.md is the canonical reference for full tables, caveats, JSON exports, and agent-host protocols.

Verified with-vs-without-CK baseline (host_comparison_v1, 12 risky scenarios)

Verified with ControlKeel 0.3.45:

  • Risky suite host_comparison_v1: null_policy_baseline caught 0/12; controlkeel_validate caught 12/12, blocked 9/12, and hit expected rules 9/12 with median deterministic validation time 52 ms, 0 provider tokens.
  • Paired benign suite benign_baseline_v1: controlkeel_validate produced 0/10 catches, 0/10 blocks, FPR 0.000, median deterministic validation time 42 ms, 0 provider tokens.

Read the numbers precisely: deterministic scanner evidence is not the same as model-backed agent-host evidence. Reproduction commands and the OpenCode/Copilot/Claude/Codex comparison protocol live in docs/benchmarks.md.

What ships today

  • Local governance: CLI, the full local stdio MCP tool set, project binding, host attach/export bundles, scanner validation, findings, reviews, proof bundles, budgets, and typed memory.
  • Host and runtime support: native attach for supported hosts, runtime exports for headless/outer-loop systems, a narrower OAuth-scoped hosted MCP set, minimal A2A, and fallback validation/proxy paths.
  • Team/project operations: org membership, invitations, workspace GitHub repo bindings, service accounts, webhooks, workspace tool policy, and policy-set APIs.
  • Cloud evidence paths: opt-in cloud telemetry, workspace keys, cloud run packages, runtime callbacks, and dormant-until-configured bidirectional sync for findings, reviews, digests, and memory records.
  • Observability loop: timelines, memory quality, costs, trends, problem clusters, eval candidates, benchmark drafts/history, and promotion advisories.

Docs map

Development

bash
mix setupmix phx.servermix testmix precommit

Phoenix + Ecto on SQLite. Uses Req for HTTP. Single-binary builds ship through Burrito and GitHub Releases.

Source: README.md at commit b0e0cf6

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.29LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.