<!-- mcp-name: io.github.emeraldleaf/okl --> <div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/emeraldleaf/okl/main/docs/brand/okl-logo-dark.png"> <img src="https://raw.githubusercontent.com/emeraldleaf/okl/main/docs/brand/okl-logo-light.png" alt="okl logo: a tree's growth rings around a healed scar, in an engraved frame with okl in the gap" width="240"> </picture>

okl — Observed Knowledge Ledger

Guardrails and a learning loop for AI coding agents.<br> Engineering rules, architecture decisions, documentation and diagrams: recorded once, briefed to your agent before every task (by a hook in Claude Code; any MCP agent can ask for the same briefing), proven by checks you choose, and flagged before you push (or in CI) when what they govern changes. Each session's lessons are fed back in. Use it in one repo, or share one store across every repo your team runs.

🚀 Quickstart · 📘 Getting started guide · 🔬 How it works · 📊 Results · 🧪 Eval report · 🧩 Plugin

</div> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/emeraldleaf/okl/main/docs/overview/okl-overview-dark.png"> <img src="https://raw.githubusercontent.com/emeraldleaf/okl/main/docs/overview/okl-overview-light.png" alt="Load your rules. Hold your agent to them. Keep learning as you build. Five stages: your rules, ADRs, standards and specs plus starter lessons for your stack, loaded up front; the store, one local file; a briefing in front of the agent before every task; gated as code moves, on every push; and it keeps learning as you build, with new lessons from mistakes, drift and failing tests, updates that keep their proof and retirements that keep their reason. The briefing before every task and the session-end question are Claude Code hooks; other MCP agents can call okl_check, and the push gate works with any agent. Six cards: one shape for every lesson (when you see, do, why); scope decides reach; selected, not skimmed; a stamp is evidence, and a stamp with no run behind it is unproven; stale blocks the push; corrected, not only added. It fails closed, keeps every check run, and starts in four commands: install, okl init, okl record with the files a rule governs, and okl verify with the check that proves it." width="100%"> </picture>

A small store of what a codebase knows — its conventions, architecture decisions and why they were made, the checks that catch mistakes already made once, and the claims its docs and diagrams make — plus a hook that hands the relevant ones to a coding agent (or a person) before they start a task. Each session can record what it learned, so the store grows with the work; it survives past a session and can be shared across a team. And it stays true: an entry is verified by running a check, and flagged when the files it governs change, whether those are code, docs or diagrams.

Quickstart

New here? docs/GETTING-STARTED.md walks through setup, the habit of adding to the canon as you build a feature, and keeping your docs from drifting. Already have a CLAUDE.md, ADRs, standards or specs? Load your rules shows how to load them, prove the ones that matter, and keep them current.

1. Install the CLI (the PyPI name differs — PyPI refuses okl as confusable with oki — but everything you type afterwards is okl):

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

Needs Python 3.10+ (and git for drift detection). Tested on macOS and Linux. Windows is untested: the core should work, but the Claude Code hooks likely need fixes there (#85).

2. Wire your repo. From the repository root:

okl init --repo my-repo --dry-run   # lists every file it would write; writes nothing
okl init --repo my-repo             # config, Claude Code hooks, MCP server, pre-push drift gate, starter lessons

init detects your stack (*.csproj, package.json, pyproject.toml …), sets the repo's interests from it, and fills the store with 20 starter lessons that hold on almost any codebase plus the bundled packs for your stack, so the first prompt is already briefed (--interests chooses your own subjects; --no-seed leaves the store empty).

init wires Claude Code when the repo has a .claude/ directory or claude is on your PATH; --claude forces it and --no-claude skips it. Drift is gated locally by default: in a git repository init installs a pre-push hook that runs the drift gate and blocks a push only when lessons have drifted (--no-git-hook skips it). The GitHub Actions workflow is opt-in, because it spends a private repo's minutes and does nothing on another CI: --ci installs it instead of the hook, unless an earlier init already installed the hook, which stays (--ci --git-hook gives both), for a team that wants a gate git push --no-verify cannot skip; a repo an earlier okl gave the workflow keeps it. Later runs remember both choices. Prefer the plugin? Install it before running init — /plugin marketplace add emeraldleaf/okl, then /plugin install okl@okl in Claude Code — and init leaves the hooks to the plugin, so nothing is wired twice. (Installed after? okl doctor reports the double wiring; run okl init --uninstall, then okl init again, which leaves the Claude Code hooks to the plugin and reinstalls okl's pre-push gate; where another tool owns the pre-push hook, init prints the one line to add to it instead.)

3. Add a rule of your own. The starter lessons are generic; what pays is what only your codebase knows. Tell your agent — "record an okl rule for this repo: order lookups are scoped to the signed-in customer; governs app/orders.py" — and it records the lesson with okl's okl_record MCP tool (in Claude Code, /record drafts it and asks you first). Underneath, that is one CLI call you can also run yourself:

okl record --type Rule --scope repo --id order-owner-scope \
  --title "Order lookups are scoped to the signed-in customer" \
  --symptom "an endpoint fetches an order by id with no owner filter" \
  --fix "filter by the caller's customer id in the query; return 404 on no match"

More: okl seed lists every bundled pack; /seed-from-docs has your agent propose cited records from the rules, ADRs, standards and specs you already wrote, and /seed-from-codebase from your own code. Both come with the Claude Code plugin or okl scaffold . (Seed it).

4. Check it works:

okl check --task "add an endpoint that returns an order for the logged-in user"
okl doctor                  # flags other memory tools, double wiring, and where drift is gated

What a normal day looks like

• You prompt as usual. The pre-task hook runs okl check on what you typed and puts the relevant lessons in the agent's context before it starts, and shows you one line — okl · briefed 9 lesson(s): … — so you can see it working (OKL_QUIET=1 hides it).
• When you learn something worth keeping — a decision, a convention the agent broke, a bug you fixed — say so and the agent records it (okl_record, or okl record), with the files it governs. In Claude Code the Stop hook also asks once, at the end of a session that changed files, what was learned, and names the lessons the session was briefed on and those whose files it changed, so the agent can propose correcting or retiring one (you approve).
• Using another agent? The briefing and recording are MCP tools (okl mcp); register them and add one line to your AGENTS.md: before each task call okl_check. The hooks that do this automatically are Claude Code's; see Getting started.
• When a lesson needs correcting, take its [id] from the briefing and change only what is wrong: okl update <id> --fix "..." (or the okl_update tool) keeps the rest, including its proof, unless you change its governed --files: then it needs verifying again, and okl reverify re-runs its stored check. okl show <id> prints the whole lesson, with how often its check has passed and failed: every run of okl verify and okl reverify is kept, so a check that caught a change leaves a record. Recording an existing id again is refused, because it used to replace the lesson and wipe its proof.
• When a lesson is wrong or replaced, retire it with a reason; nothing is deleted. okl retire <id> --reason "..." keeps a wrong one briefed as AVOID, so nobody restates it; --by <new-id> takes a replaced one out of briefings, which point to the new one; --obsolete is for a lesson whose subject is gone. A fixed defect is not retired: it keeps briefing against its return.
• Proving a lesson is true is a check you run, not a flag you set: okl verify <id> --run "pytest -q tests/test_orders.py" --expect "passed".
• When code a lesson governs changes, okl drift goes red until its check passes again, or the code is put back as it was when the check passed (a lesson recorded with --files is also red until its first okl verify). The briefing says so too: such a lesson is marked STALE (or UNVERIFIED, or UNPROVEN) with the file that changed, so the agent confirms it against the code instead of trusting it blindly. okl reverify re-runs each drifted lesson's stored check after you confirm. With the GitHub workflow (okl init --ci), CI reads a committed snapshot, okl-drift.json, which okl verify creates the first time a lesson with --files is verified and keeps current after that: commit it after the code change it verifies. Until then CI warns "Drift not checked", which is expected. Without the workflow, okl verify writes no snapshot unless one is already committed.
• Headless runs (claude -p, scripts, CI agents) set OKL_DISABLED_HOOKS=encode, or the end-of-session question replaces the printed answer.

The problem it solves

A team (or an AI agent) fixes a subtle bug, learns why it happened, and writes a rule to prevent it. Weeks later, in a different file — or a different repository — the same class of bug comes back, because the person or agent doing the new work never saw that rule. The knowledge existed; it just wasn't in front of whoever needed it, at the moment they needed it.

okl fixes that with one move: the relevant lessons are read automatically at the start of a task, not looked up if someone remembers to. You record a lesson once; every future task that resembles it gets the lesson injected before the first line of code is written.

It works for a single repo on day one, and across many repos when you point them at a shared instance — so a lesson learned in one project protects the next one.

This is a v0 starter, not production-hardened. It ships an end-to-end test suite (run pytest -q to see t