Documentation

Start with evidence.
Keep uncertainty visible.

Install Open Kioku, connect your coding agent over local MCP, and use the plan → edit → verify loop on the repository you already have.

Quickstart →All reference docs ↗

First win

Install and connect

The setup command indexes the current repository, writes repository-scoped agent guidance and MCP configuration, and checks that the local server responds.

npm install -g open-kioku
ok setup agent cursor --repo . --apply

Use claude for Claude Code; --apply is wired for those two clients. ok mcp install codex|gemini --repo . prints a read-only server entry for the others. Run without --apply to preview; nothing is written.

CursorRepository-scoped MCP setup→ Claude CodeLocal stdio MCP setup→ CodexConnect Open Kioku tools→ Gemini CLILocal repository evidence→

Core workflow

Plan before editing. Verify after.

Build local evidence

ok index . stores symbols, relationships, tests, history, documentation, and optional semantics under .ok/.

Compile a plan

ok plan "your task" returns bounded context, impact candidates, validation targets, provenance, and explicit caveats.

Verify the change

ok verify --plan plan.json --git (or the verify_change MCP tool) compares the actual changed files with the declared boundary and reports anything outside it.

Install channels

Same binary, every channel you already use.

npm

npm install -g open-kioku

Pulls the native binary for macOS, Linux, or Windows through platform packages.

crates.io

cargo install open-kioku-cli

Or cargo binstall open-kioku-cli for the prebuilt binary.

GitHub releasesok-{linux,macos,windows}-*

Binaries with SHA256SUMS, an SBOM, PROVENANCE.json, and build-provenance attestations. Release trust ↗

Claude Code pluginclaude_plugin.json

Plugin manifest and .claude-plugin/ marketplace entry in the repository.

Cursor / Codex plugins.cursor-plugin/ · .codex-plugin/

Agent, rules, and skill for Cursor; plugin manifest for Codex.

MCP directoriesglama.json · smithery.yaml

Server manifests for the Glama and Smithery MCP directories.

Setup guidesok setup agent claude|cursor --repo . --apply

Claude Code · Cursor · Codex · Gemini CLI

What to expect

Measured on four real repositories, re-run nightly.

Holdout split of the commit-derived corpora on the production ok context path. Baselines frozen 2026-09-25 from a hosted Linux runner matrix run of commit bd5d06ab, confirmed by a second run with identical scores; the nightly job fails when a watched metric drops more than 0.03 below its baseline, or a routed task family of 34 or more cases, with unchanged membership, drops more than max(0.03, 2/n) below its own.

Corpus	Holdout cases	R@5	R@20	MRR
Java, about 10k files	113	0.566	0.708	0.516
Go application, ~800 files	84	0.690	0.821	0.539
TypeScript, ~900 files	167	0.826	0.880	0.683
Python library, ~4k files	199	0.663	0.754	0.543

R@5 — the share of tasks for which at least one file the commit changed is in the first five results.

R@20 — the same within the first twenty results, roughly the whole context pack.

MRR — the average of 1 / rank of the first correct file; 1.0 means it was always first, 0.5 is what you get if the first correct file were always second, or first half the time and never found the rest.

Read it plainly: on a Java repository of about ten thousand files the right file is in the top five about half the time and in the pack about seven times in ten; on a TypeScript repository of about nine hundred files, in the pack nearly nine in ten and in the top five about four in five. Queries are commit subjects, not issue text, so compare a change against the frozen baseline, not the literature. Method, corpora, and scripts ↗

Evidence you can inspect

Proof, methodology, and limitations.

Performance claims are observations tied to a release and host—not universal guarantees.

Large-Java JSON evidence (v3.1.0 lineage)Release, host, workload, measurements, quality checks, limitations↗ Validation methodologyProcedure, evidence boundary, and limitations↗ Public large-repository proofAudit of three public repositories↗ Retrieval benchmarkFrozen fixture, commit-derived corpora, nightly regression policy↗ Proof modelHow Open Kioku reports usefulness and uncertainty↗

Start with evidence.Keep uncertainty visible.