Guardrails and a learning loop for AI coding agents
Joshua Dellemeraldleaf.dev · open source, MIT

Load your rules.
Hold your agent to them.
Keep learning as you build.

okl works with your agent: it brings your rules and ADRs into context before each task (automatically in Claude Code; other agents call okl_check), proves them with checks you choose, and blocks the push when the code they govern changes.

Your rules

Rules, ADRs, standards and specs · starter lessons for your stack
up front

The store

Rules · decisions · past defects · gates
one local file

In front of the agent

Task arrives → ranked and filtered → briefing in context
before every task *

Gated as code moves

A check must pass → its files change → push or CI fails until it passes again
on every push

Keeps learning

New lessons from mistakes, drift and failing tests · update keeps proof · retire with a reason
as you build
lessons flow back

* Claude Code hooks brief every prompt and ask at session end what was learned; other MCP agents call okl_check. The push gate works with any agent.

01

One shape for every lesson

A paragraph can't be routed into an action; a lesson can.

when you seea request body carries Price
docompute it server-side
whythe client sets its own price
02

Scope decides reach

org reaches repos that load it. repo stays here, so a local quirk never fires elsewhere.

orghereotherother
repohereotherother
03

Selected, not skimmed

Ranked by the task, scoped, capped, and it says how many it trimmed.

+ n lower-ranked, trimmed
04

A stamp is evidence

A check you chose must run and pass, and the stamp keeps the command it ran. A stamp with no run behind it is unproven.

✓your check passedstamped
✕stamp, no rununproven
05

Stale blocks the push

Files changed since the check passed? The pre-push hook or CI fails until it is re-proven.

check
passed
file
changed
push
fails
06

Corrected, not only added

Wrong or outdated lessons get fixed or retired; a retirement keeps its reason.

updatekeeps the proof
retirekeeps the reason
recapnames what to review
Fails closedIf okl can't brief, the prompt is blocked or told so.
ObservableEvery check run kept · okl metric · okl show

Start in four commands

Then every push checks it.
01

Install

pipx install 'observed-knowledge-ledger[mcp]'
02

Wire a repo

okl init --repo my-repo
03

Add a rule

okl record --type Rule --scope repo --files app/orders.py --title "…"
04

Prove it

okl verify <id> --run "pytest -q" --expect passed