okl — Observed Knowledge Ledger MCP server

<!-- mcp-name: io.github.emeraldleaf/okl -->

okl — Observed Knowledge Ledger

A learning loop that keeps coding agents — and your docs — from drifting. 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.

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

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.

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, 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. 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.)

Shortened. The full README is on GitHub.