keel ⚓

Keel turns coding agents into work owners. It is a project-neutral, multi-agent workflow backbone that drives a unit of work — a GitHub issue — from intake to done: understand readiness, branch, implement, wait on CI, review, test, merge safely, close, and run capture hooks. Projects never fork the backbone: they set per-project values in project.yaml and snap their own Lego pieces into named extension slots.

The keel is a ship's backbone — the fixed spine every project builds on. Linear work is driven by keel:ship, while high-concurrency parallel backlogs are orchestrated by keel:swarm; keel is where ships and fleets are built.

Keel is based on the work pattern of a strong teammate in a real engineering team: take an issue from the queue, decide whether it is ready, own the implementation, get it reviewed, keep the quality gates green, merge inside policy, and leave useful memory behind for the next session. keel focuses on one agent owning work end to end.

The Vision-to-Production Gap in Agentic AI

While over 70% of engineering organizations experiment with autonomous AI agents, only a small fraction (~11-15%) successfully run agentic workflows in production. The bottleneck is rarely code generation—it is work ownership and delivery governance.

Most coding agents stop at "I opened a PR." Without an invariant delivery backbone, agent-written code stalls in review loops, introduces silent regressions, causes merge collisions, or bypasses compliance.

Keel closes the vision-to-production gap. It provides the fixed backbone (s0–s12) that drives every unit of work through scope validation, multi-agent adversarial reviews, commit-bound evidence verification, timezone-aware merge locks, and post-merge proof—guaranteeing work either lands safely in production or fails loudly at a named step.

keel uses a thin-consumer model: the core is installed + pinned, never copied, so the drift/overwrite class of bug is structurally gone. Background: docs/proposals/keel-architecture.md.

Three layers

Layer 3  EXTENSIONS   project-owned Lego pieces, ADD-ONLY into named slots
Layer 2  CONFIG       project.yaml — per-project values (branch, build cmd, globs, agents…)
Layer 1  BACKBONE     keel-core — fixed ordered step machine + invariants (this package)

Changing the backbone is a keel-core change. Projects only ever touch layers 2–3.

What you get

• One backbone, every agent — install once; /keel:<command> runs as native Claude commands and as a single shared skill set every other agent (Codex, Antigravity, Gemini) reads.
• High-concurrency Swarm orchestration — cluster entire backlogs into topological dependency waves, execute disjoint clusters in isolated git worktrees, and land batches through orthogonal fast-forward merges or drift self-healing funnel rebases (guide).
• Project Lego + policy packs — snap gates/steps into named hooks (guard, tester, pre-merge, …) and keep labels, path policy, health sources, local commands, and workflow preferences in policy_pack data instead of packaged command prose.
• Security presets — declarative policy_pack.presets: ["bandit", "gitleaks", "semgrep", "trivy"] automatically slot SAST, secret scanning, and vulnerability auditing into the pipeline.
• Opt-in jury gate — runs the ai-jury multi-agent reviewer on the diff when installed; a fail-soft no-op otherwise. Core resolves the mode from the panel that actually ran: a cross-vendor gate needs ≥2 distinct vendors, so a short panel downgrades to advisory instead of blocking on a jury that never convened.
• …or the panel is the review — set knobs.team.review.by_tier."3": jury and s7 dispatches ai-jury once instead of running host reviewers beside it. keel review --from-jury <report.json> turns each panelist's ballot into a head-pinned keel.review-verdict.v1 with the vendor and model that produced it, posts the jury verdict as the consensus record, and hands the fix loop the panel's verified findings. The evidence gate then requires one verdict per ballot (the panel declares its own size) plus that verdict. Too few participating vendors relaxes neither: on a panel tier the verdict stays required and the thin span is refused as review-vendor-distinctness, because a short panel may not excuse itself from the record that says it was short. The bench is a function of config alone, so every surface of a run agrees on it. Needs ai-jury's ballot report (jury --format json, schema 1.1+); keel still never imports it.
• Headless with just an API key — the hosted-API delegates (--delegate anthropic-api:MODEL / openai-api:MODEL / google-api:MODEL) drive the implement/review steps with only ANTHROPIC_API_KEY/OPENAI_API_KEY/GEMINI_API_KEY in the environment — no agent CLI installed. Connect any OpenAI-compatible provider (OpenRouter, DeepSeek, Groq, local vLLM/Ollama) or custom CLI via knobs.delegate_profiles (design), or keep operator-owned entries out of the repository entirely in the machine-level provider registry (~/.keel/providers.yaml).
• A team, not a delegate — knobs.team states who implements (per issue role, with model and reasoning effort), who gives the gate review from a different vendor, who reviews at each risk tier — or jury, when the cross-vendor panel is the review — and who applies the findings (reference). keel plan/keel ship --json render it as one resolved assignment so every host runs the same team, and keel validate refuses a policy keel cannot execute: an unknown provider, an effort a vendor cannot honour, or a gate reviewer that is the implementer. The reviewer count and the jury mode are enforced by the evidence gate; the gate review is emit-only — core publishes the seat and the adapter dispatches it, with no evidence item behind it, the same boundary operator consent sits behind.
• Test-first when you want it — knobs.implement_mode: tdd (or --tdd for a single run) splits s4 into two phases: a test-only commit carrying the issue's acceptance criteria, then the implementation. s8 gains the pure, blocking tdd-order gate, which checks that commit order against the policy_pack.test_groups paths, so "tests first" is verified rather than asserted. The resolved profile is published as contract.implement_mode ({"mode": "tdd", "gate": "tdd-order", "phases": ["tests", "implementation"], …}) and recorded in the ledger, and --phase-implementer tests=… / implementation=… records a run where the two phases were written by different seats (reference).
• Iterate s4 with the gates as the judge — knobs.loop (or --loop for a single run) wraps the implement pass in a bounded, gate-verified loop: after each iteration the command gates run; green ends the loop, red starts the next iteration with the same brief plus the gate output, up to max_iterations. The completion criterion is the gate run, never the implementer's own "done" — the Ralph loop's iteration without its judge or its amnesia: every iteration is one commit the ledger names, published as contract.implement_mode.loop and rendered in the closure comment. It composes with --tdd (the loop wraps phase B only) and runs on every host keel runs in (reference).
• Every merge can leave a lesson the next run reads — with policy_pack.capture.learning.sink set, an applied create-learning capture writes one Markdown learning: the issue, the gate results on the head it merges, and a link to every file it changed, so a knowledge-graph builder gets the edges (reference). With an in-repo sink, s10 runs keel capture-land --write --onto "$BRANCH", which commits that lesson onto the pull request itself, so the same squash carries it into the base branch: a protected base never sees a direct push, and there is no second pull request to forget (reference). The review still holds for the head that landing produces — the evidence gate accepts a pin across a commit with one parent, the keel.capture-land.v1 marker and exactly one added or modified file inside the sink, and across nothing else. keel plan and keel ship read matching lessons back into the implement and review briefs, at most five (reference).
• Know which providers this machine can actually dispatch to — keel doctor --providers [--json] probes every provider keel supports (agent CLIs, hosted APIs, local Ollama models, delegate profiles and registry entries) and reports available / reason / transport / capabilities / model list for each. Probes are time-boxed and fail-soft, and print key names only, never values (reference).
• Auditable evidence chain & compliance — every PR merged through Keel carries a tamper-evident, commit-SHA-bound record of reviewer verdicts, test results, and model attributions (guide). Approvals are locked to the exact HEAD commit, preventing approval drift across subsequent pushes — a lesson keel capture-land lands is the one commit they survive, under the rule above — with first-class, audited exception tracking.
• Safe merges by construction — the core-owned keel merge path (resource claim, window re-check, live CI rollup, and evidence verification before the merge), timezone-aware night no-merge window, risk-tier → reviewer count, hotfix bypass with an audit line, vendor+model attribution. The PR evidence gate arms from ship provenance by default — only the operator-applied keel:evidence-waived label disarms it, and a gate that never armed now blocks rather than reporting a pass having checked nothing. Requirements are split by phase, so the merge gate asks for the review/jury evidence that exists at s10 and not the closure comments s11 writes after it. Where a host's egress proxy blocks GitHub's GraphQL endpoint, keel merge asks the same questions over REST (--transport auto|graphql|rest) — the claim, window, rollup, evidence and SHA-pinned gates-pass are unchanged — and its read-only drift check, keel verify-merge, takes the same flag (reference).

How Keel compares

Keel sits between three established tool categories:

Keel is not trying to replace those tools. It is the work-ownership backbone that can use coding agents, reviewers, gates, and merge policy in one lifecycle. See docs/keel/comparison.md for the source-backed comparison and the ideas Keel should borrow.

The backbone

Invariants the backbone always preserves: merge lock, night no-merge window, fail-soft, orchestrator-only-writes, vendor+model attribution.

The capture step has a core marker/verifier contract: compound-learning: pr=<N> status=<applied|deferred|skipped:reason>. Projects provide capture content and destinations through capture / post-merge extensions; keel owns the marker, fail-soft semantics, redaction-before-durability, offline capture-verify, and the learning-quality decision recorded in capture.learning. Durable learning is optional: policy can choose create-learning, marker-only, or defer, while duplicate candidates are suppressed by stable fingerprints so routine merges do not flood the learning surface.

Install

Homebrew (macOS & Linux)

brew tap berkayturanci/keel
brew install keel

Or install in a single command:

brew install berkayturanci/keel/keel

Standalone Curl Installer (macOS, Linux, WSL)

curl -fsSL https://raw.githubusercontent.com/berkayturanci/keel/main/scripts/install.sh | sh

PyPI / pipx / uv

pipx install keel-workflow                                    # isolated global CLI tool
pip install keel-workflow                                     # from PyPI (provides the `keel` command)
pip install "git+https://github.com/berkayturanci/keel@v1.23.1"  # or pin an existing git tag

In a cloud agent session, install it from a SessionStart hook (or add keel to the session's repo scope) so the selected core ref is available before a run.

Release maintainers should follow docs/keel/release.md and run python scripts/release_smoke.py before tagging or announcing a package.

Quickstart

keel setup --root .                                  # add keel config + adapters to a project
keel setup --root . --wizard                         # …and pick the team interactively
keel validate projects/example-flutter.yaml          # validate a config against the schema
keel plan      projects/example-flutter.yaml          # show the backbone plan for a project
keel version

keel setup wraps first-run onboarding (init + install-adapter + strict validate + plan) for a consumer project. With --wizard it also runs a team step: it probes which agent CLIs, hosted APIs and local models are usable on this machine (the same probe as keel doctor --providers) and writes knobs.team from what it found — who implements, who gives the mandatory gate review, who reviews at each risk tier. Only providers that are actually reachable are offered. keel ship --wizard picks the same seats for a single run. See docs/keel/onboarding.md. keel plan renders the fixed backbone with each project's gates/extensions slotted in — exactly what a dry-run executes:

keel plan — example-flutter
  base_branch: main   core_version: ^1.0
  backbone:
     s4  implement  [agent]
     ...
     s8  test
           - gate: build
           - gate: lint
           - gate: design-parity
    s10  merge
           - gate: design-parity-gate

Invocation (/keel:<command>)

The agentic workflows ship with the package as project-neutral adapters and install into the two surfaces agents actually read — so the same /keel:<command> works in every project; only that project's .keel/project.yaml + extensions change the behaviour:

keel install-adapter claude   # native Claude commands → /keel:ship, /keel:regression, …
keel install-adapter skills   # one shared keel-<cmd> skill set under .agents/skills/
#                               (read by every non-Claude agent: Codex, Antigravity, Gemini)
keel install-adapter all      # both surfaces

Install into an agent

Everything above needs the CLI on your machine — Install puts it there, and install-adapter writes files into a project with it. Installing keel as a plugin is how an agent gets the commands and skills: from this repository's own marketplace, with no install-adapter step. It is not a replacement for the CLI — the command bodies shell out to keel, so it still has to be on your PATH. Jump to the agent you use:

Each badge jumps to that agent's box; open it for the commands. (A browser scrolls to a collapsed <details>; it does not expand one.)

claude plugin marketplace add https://github.com/berkayturanci/keel
claude plugin install keel@keel

claude plugin marketplace update keel
claude plugin update keel@keel

codex plugin marketplace add https://github.com/berkayturanci/keel
codex plugin add keel@keel

codex plugin marketplace upgrade
codex plugin add keel@keel

agy plugin install https://github.com/berkayturanci/keel
agy plugin enable keel

agy plugin install https://github.com/berkayturanci/keel

cursor-agent plugin marketplace add https://github.com/berkayturanci/keel

git clone --depth 1 https://github.com/berkayturanci/keel ~/.cursor/plugins/local/keel

git -C ~/.cursor/plugins/local/keel pull                   # if you cloned

cursor-agent plugin marketplace update berkayturanci/keel  # if you used the marketplace

Full detail, including what each route actually registers: docs/keel/install.md.

The plugin ships the same project-neutral command bodies as keel install-adapter; the two flows are additive. The plugin's command files under commands/ are generated from src/keel/adapters/commands/ (the single source of truth) by make plugin / keel install-adapter plugin, and a test fails on any drift. The pip install keel-workflow

• keel install-adapter path is unchanged.

17 shipped commands — ship (flagship, with a --compound profile flag), implement, review-cycle, review-all-day, pr-loop, regression, triage, morning, work-block, overnight, swarm, wrap, ci-check, coverage, deps-audit, flake-audit, stale-prs. Each is described in docs/keel/commands.md. The keel CLI does the deterministic work; the adapters are the agentic flows (per-round review, inline comments, delegation).

Dogfooding

keel drives itself from .keel/project.yaml using the latest ^1.0 core contract (Python, make test + make lint gates), and CI runs keel on keel-core on every push. projects/keel.yaml remains a seed copy and is tested to stay in sync with the dogfood config.

keel plan      .keel/project.yaml --root . # render keel's own backbone
keel run-gates .keel/project.yaml --root . # keel runs its own test + lint gates
keel ship      .keel/project.yaml --root . # full dry assessment: tier, window, gates, decision
#   risk tier     : TIER-3  → 3 reviewer(s)
#   decision      : MERGE — clear to merge

If a step's gate fails, keel blocks its own merge — the same backbone every consumer gets.

Docs

• 🌐 Website + live coverage report — the published site is live at https://keel-ship.dev/ (deployed via the pages.yml workflow). Locally, make site builds the coverage HTML into website/coverage/ and serves it at http://localhost:8000.
• docs/keel/configuration.md — project.yaml reference
• docs/keel/evidence.md — evidence chain, commit-SHA binding, and compliance auditability
• docs/keel/models.md — supported AI models, providers, and delegate profiles (Claude, OpenAI, Gemini, OpenRouter, DeepSeek, Groq, Ollama, CLI tools)
• docs/keel/parameter-reference.md — exhaustive per-flag reference for every CLI command and the /keel:ship adapter arguments
• docs/keel/install.md — installing keel into an agent (Claude Code, Codex, Antigravity, Cursor), with the update path for each
• docs/keel/onboarding.md — one-command consumer setup and follow-up checks
• docs/keel/keel-visual.md — the live run board (dash/render/serve, the per-run 2D/3D drawer, --all multi-project, the auto-stamped keel activity channel)
• docs/keel/extensions.md — authoring Lego extensions
• docs/keel/artifacts.md — where runtime state and agent scratch live (the .keel/ dir, its auto-scaffolded .gitignore, and keel scratch-dir)
• docs/keel/consumer-neutrality.md — core vs project policy boundary
• docs/keel/parity-matrix.md — legacy-to-keel command parity status and owning issues
• docs/keel/runtime-capabilities.md — runtime capability detection and requirement declarations
• docs/keel/github-transport.md — GitHub transport selection and normalized operation capabilities
• docs/keel/command-contracts.md — structured JSON plan/result contracts for adapters
• docs/keel/operator-consent.md — live-run operator consent scopes and delegated-agent scope rules
• docs/keel/cli.md — CLI reference
• docs/keel/commands.md — the 17 /keel:<command> workflows (plus the keel status progress command), each with its description
• docs/keel/swarm.md — multi-agent swarm architecture, dependency DAG wave scheduling, isolated worktrees, dual-mode landing, and 2D/3D visualizer
• docs/keel/cutover.md — staged guide to retire a project's copied command bodies (install → verify → retire), losing nothing
• docs/keel/comparison.md — competitive landscape (Mergify, GitHub merge queue, Qodo/PR-Agent, CodeRabbit, Sweep, OpenHands, Danger, …) + ranked borrow-ideas
• docs/keel/github-actions.md — run keel live on GitHub's free runner (the keel-ship workflow)
• docs/keel/release.md — PyPI/TestPyPI release runbook and package smoke test
• docs/keel/homebrew-release-chain.md — how a release reaches brew install, every guard on the way, and what has already gone wrong
• docs/proposals/keel-architecture.md — full design
• docs/proposals/api-token-delegate.md — hosted-API (API-token) implementer/reviewer delegate design (#548)

Development

Stdlib-first, pure-core + thin-I/O, deterministic, fully covered (ai-jury ethos).

make test       # offline unit suite (no network, no credentials)
make lint       # ruff
make coverage   # coverage gate (fail_under in pyproject)
make validate   # validate projects/*.yaml and .keel/project.yaml
make site       # build the coverage report + serve the website at localhost:8000

The pure core (config, model, extensions, findings, gates, orchestrator, cli) is held at 100% line + branch coverage; the coverage gate (fail_under = 100) runs in CI.

Companion: keel-visual

keel-visual is an optional, separately installable animated run visualizer (pipx install keel-visual). It renders a keel run from the ledger/checkpoint keel already writes — it never drives one — for any of the 17 command flows (ship is the s0–s12 backbone; every other command renders its own phases).

Four surfaces:

• play — the run animates in the terminal (flow + wave ribbon, --loop for a demo, live --follow; --theater hands off to ai-jury's deliberation theater at the review step, then resumes).
• dash — a terminal board of every active run; dash --all aggregates every keel project under a parent folder into one board. It shows ship runs and non-ship commands (triage, morning, pr-loop …) live via the keel activity channel — each with its own phases.
• render — a self-contained web page: a 2D flow and a 3D scene with five selectable styles (plexus/comet/aurora/combined/line); render --all writes a multi-project board with a 2D grid / 3D scene toggle, automatic light/dark theme, and an all / active filter that fades finished runs.
• serve / serve --all — a live localhost web dashboard (polls every ~0.5s): a filterable board, and per-run a detail drawer with a 2D / 3D switch (a live per-run scene with curve · helix · ring · line · plexus · aurora · comet styles, drag-orbit + scroll/pinch zoom, theme-aware) and, from the ledger record, the run's command / phase / status, risk tier, merge-window state, per-named-gate status (build / lint / evidence / jury …), agent attribution (implementer, reviewers, host — including the hosted-API delegates), and the jury verdict itself when ai-jury ran, not just the jury mode.

As of keel 1.6.4, the deterministic backbone commands (keel plan at Step 0, keel run-gates at s8, keel merge at s10) auto-stamp the keel activity board when given a --run-id, so a run shows up and advances even if the agent skips the per-phase keel activity calls. Since 1.6.5, keel merge stamps the run merged (a real merge landed) rather than a soft done, so the board distinguishes a green confirmed-merge from a closed-out run; runs whose --run-id ends in their issue/PR (ship-585) are labelled #585 even when no explicit issue is passed.

Depends on this core (keel-workflow >= 1.6.0); the core never depends on it (it only reads records, and probes shutil.which("jury") — never imports ai-jury). See keel-visual/README.md.

Repo layout

src/keel/            the core package (config, model, extensions, findings, gates, orchestrator, cli)
src/keel/schema/     project.schema.json (bundled)
.keel/project.yaml   keel's own dogfood consumer config
projects/*.yaml      example configs and the keel seed copy
src/keel/adapters/   the packaged /keel:<command> bodies (install-adapter: claude commands + shared skills)
keel-visual/         optional companion: animated 2D/3D run visualizer (separate package)
website/             static site + coverage report (make site)
tests/               unit suite
docs/                docs + proposals