okl

<!-- mcp-name: io.github.emeraldleaf/okl -->
<div align="center">

# okl — Observed Knowledge Ledger

**A learning loop that keeps coding agents — and your docs — from drifting.**<br>
Engineering rules, architecture decisions, documentation and diagrams: recorded once, briefed to
Claude Code or any MCP agent before every task, proven by checks, and flagged in CI when what they
govern changes. Use it in one repo, or share one store across every repo your team runs.

[![PyPI](https://img.shields.io/pypi/v/observed-knowledge-ledger?color=blue&label=PyPI)](https://pypi.org/project/observed-knowledge-ledger/)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
[![ci](https://github.com/emeraldleaf/okl/actions/workflows/ci.yml/badge.svg)](https://github.com/emeraldleaf/okl/actions/workflows/ci.yml)
[![okl-verify](https://github.com/emeraldleaf/okl/actions/workflows/okl-verify.yml/badge.svg)](https://github.com/emeraldleaf/okl/actions/workflows/okl-verify.yml)
[![Claude Code plugin](https://img.shields.io/badge/Claude_Code-plugin-D97757)](#install-as-a-claude-code-plugin)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

🚀 [Quickstart](#quickstart) · 📘 [Getting started guide](docs/GETTING-STARTED.md) · 🔬 [How it works](#how-it-works) · 📊 [Results](#measured-effect-and-its-limits) · 🧪 [Eval report](evals/REPORT.md) · 🧩 [Plugin](#install-as-a-claude-code-plugin)

</div>

> 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](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.

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

```bash
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](https://github.com/emeraldleaf/okl/issues/85)).

**2. Wire your repo.** From the repository root:

```bash
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, CI workflow, 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. `--no-ci` skips the GitHub Actions
workflow, for a private repo that would pay for its minutes or one that runs another CI,
and later runs remember that; `--ci` puts it back. **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, and
`okl init --uninstall` removes the project copy.)

**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:

```bash
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; `okl scaffold .` stamps the method kit, which
includes a `/seed-from-codebase` command that has your agent propose cited records from
your own code ([Seed it](#seed-it-so-the-very-first-check-returns-something)).

**4. Check it works:**

```bash
okl check --task "add an endpoint that returns an order for the logged-in user"
okl doctor                  # flags other agent-memory tools and double wiring
```

### 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.
- **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](docs/GETTING-STARTED.md#using-another-agent).
- **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 someone re-runs its
  check (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*) 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. 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.
- **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 the suite and its current result in your environment). The core is
stdlib-only with zero required dependencies.

---

## What okl is

**A store of your engineering rules, and the machinery that keeps them true.**

Two things ship in the package. They are not coequal:

- **The knowledge layer** is the product. Typed records (rules, architecture decisions,
  known defects, gates, tombstones, retractions) that live outside any one repo, get
  retrieved into an agent's context before a task, and go stale loudly when the code
  they describe moves on. Everything measured in [evals/REPORT.md](evals/REPORT.md)
  measures this.

  It is worth being precise about what that store fills up with, because "lessons a
  codebase has learned" invites the picture of a bug database. In the 161-record corpus
  in [seed/](seed/) it is mostly not that: **90 Rules, 20 Decisions and 7 Gates against
  34 Defects** — conventions the code follows and trade-offs already settled, not a
  ledger of things that broke. Count it yourself:

  ```bash
  python3 -c "import json,glob,collections; c=collections.Counter(
    n['type'] for f in glob.glob('seed/*.json') for n in json.load(open(f))['nodes']); print(c)"
  ```
- **`okl scaffold`** is a starter kit for the in-repo discipline the store assumes: a
  lean canon file, mechanical gates, registries, a review agent, and an eval harness.
  It is useful on its own and it has never been measured. Use it to get a new repo to
  the state where a shared store has something to attach to.

| Piece | What it is | Where it lives |
|---|---|---|
| **client** (`okl` CLI + agent tools) | `check` / `record` / `verify` / `drift` / `search` / `seed` | installed per-repo (this package) |
| **shared layer** (`okl serve`) | one small service owning the database, so many repos share one store | one place you run it |
| **scaffold** (`okl scaffold`) | the in-repo starter files: canon, gates, registries, evals | stamped into each repo, optional |

## What okl is not for

okl holds lessons: what an