2026-07-04 14:19 UTCIn-site rewrite5 min readUpdated: 2026-07-04 14:40 UTC

Show HN: Open Kioku – local evidence layer for AI coding agents

Open Kioku is an open-source tool that provides AI coding agents with an evidence layer using local indexes and read-only MCP tools. It enables code search, symbol resolution, impact analysis, and validation planning before any edits are made, supporting agents like Claude, Cursor, Codex, and more.

SourceHacker News AIAuthor: shivyadavus

Notifications You must be signed in to change notification settings

Fork 0

Star 4

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

219 Commits

.agents/plugins

.claude-plugin

.codex-plugin

.cursor-plugin

.githooks

.github

Formula

assets

benchmarks

crates

demo

docs

examples

packages

scripts

skills/open-kioku

test-repos/rust-mini

.gitignore

.mcp.json

CHANGELOG.md

CONTRIBUTING.md

Cargo.lock

Cargo.toml

LICENSE

NOTICE

PRIVACY.md

README.md

SECURITY.md

STABILITY.md

audit.toml

claude_plugin.json

demo.tape

deny-output.txt

deny.toml

glama.json

jobs.json

mcp.json

release-metadata.json

run.json

smithery.yaml

Repository files navigation

Give Claude, Cursor, Codex, or any MCP-compatible coding agent an evidence layer before it edits your codebase, using local indexes and read-only MCP tools by default.

First Win: 3 Commands

Run these three commands on your own repo and see what changes:

npm install -g open-kioku ok index . ok mcp install cursor --repo . # or: claude, codex, gemini, windsurf, trae, zed, opencode

Paste the printed MCP config into your agent, then paste this prompt:

Use Open Kioku before editing. Check repo_status, search_code, get_definition, get_references, impact_analysis, and find_tests_for_change. Build a plan with plan_change first, then edit, and verify after the edit with verify_change.

Your agent now has indexed evidence — symbols, references, impact analysis, test candidates, and edit boundaries — before it touches a single file.

See the Proof

Run ok prove on your repo to produce a shareable Markdown or HTML report with indexed counts, task scores, and validation signals. The report intentionally omits source snippets, so it is designed to be reviewed and shared from private repos:

ok prove . --task "the feature you're working on" ok prove . --task "the feature you're working on" --html

A representative public-repo audit indexed 4,600+ files, 46,000+ symbols, and 8,900+ tests locally in 33.1s. The exact Open Kioku version, repository revisions, caveats, and language limitations are recorded in docs/large-repo-proof.md.

What Your Agent Gets

search_code → get_definition → impact_analysis → find_tests_for_change → plan_change → verify_change

An evidence-backed pre-edit plan with: primary files, relevant symbols, likely blast radius, exact validation commands, confidence scores, and the next MCP calls to make.

What The First Plan Tells You

ok plan and MCP plan_change return concrete file ranges, validation candidates, and confidence caveats from the local index. On the bundled demo repo, a token task currently surfaces:

primary context in src/auth.rs, src/lib.rs, and tests/auth_flow.rs

validation candidates such as issue_token, validate_token, and login_returns_valid_token via cargo test

an edit boundary that allows the relevant source and test files while keeping generated, vendored, build, and .ok/ artifacts out of scope

explicit caveats when exact-reference, runtime, history, or coverage evidence is unavailable

Why It Exists

AI coding agents are strongest when they can ask the codebase for facts before editing. Without indexed context, they burn tokens on repeated file crawling, infer references from text matches, and often pick tests only after a change has already gone wrong.

Open Kioku gives agents a pre-edit routine:

Search indexed code and files.

Resolve symbols and references.

Build an evidence-backed pre-edit plan with likely impact and validation targets.

Recall prior repo facts without letting memory outrank indexed code evidence.

Compress context into handles that can retrieve the original snippets later.

Serve those capabilities through MCP over local stdio.

Install

npm (recommended)

npm install -g open-kioku ok --version

The open-kioku npm package is a JavaScript wrapper that installs the native ok binary through platform-specific optional dependencies.

Published platform packages:

@open-kioku/darwin-x64

@open-kioku/darwin-arm64

@open-kioku/linux-x64

@open-kioku/linux-arm64

@open-kioku/win32-x64

cargo-binstall

cargo binstall open-kioku-cli ok --version

crates.io

cargo install open-kioku-cli ok --version

GitHub Releases

Tagged releases publish native binaries and SHA-256 checksums for Linux x86_64/arm64 musl, macOS x86_64/arm64, and Windows x86_64. Download from https://github.com/shivyadavus/open-kioku/releases.

From Source

git clone https://github.com/shivyadavus/open-kioku.git cd open-kioku cargo install --path crates/open-kioku-cli ok --help

Requires a stable Rust toolchain.

Set Up Your Repo

ok init /absolute/path/to/repo ok index /absolute/path/to/repo ok doctor /absolute/path/to/repo ok status /absolute/path/to/repo --markdown --write ok-status.md ok setup audit /absolute/path/to/repo ok --repo /absolute/path/to/repo search "the feature or bug you care about" --limit 5

ok index writes local data under .ok/: SQLite metadata and graph rows in .ok/index.sqlite, plus BM25 search data in .ok/search/tantivy. Large indexes report progress phases such as scan, parse, occurrences, store, graph, search, and complete.

Keep the index fresh while editing:

ok watch /absolute/path/to/repo

Connect Your Agent

ok mcp install cursor --repo /absolute/path/to/repo ok mcp install claude --repo /absolute/path/to/repo ok mcp install codex --repo /absolute/path/to/repo ok mcp install gemini --repo /absolute/path/to/repo ok mcp install windsurf --repo /absolute/path/to/repo ok mcp install trae --repo /absolute/path/to/repo ok mcp install opencode --repo /absolute/path/to/repo ok mcp install zed --repo /absolute/path/to/repo

Paste the printed MCP config snippet into your agent. The default server is read-only and runs locally over stdio. The install matrix is tested for Claude, Cursor, Codex, Gemini CLI, OpenCode, Zed, Windsurf, and Trae.

Agent-specific setup guides: Claude · Cursor · Codex · Gemini CLI. OpenCode, Zed, Windsurf, and Trae use the same verified ok mcp install --repo /absolute/path/to/repo flow shown above.

Plugin Metadata

Open Kioku bundles pre-configured repository-scoped plugin and marketplace manifests:

OpenAI Codex: verified MCP setup is ok mcp install codex --repo /absolute/path/to/repo; .codex-plugin/ metadata is included for Codex installations that support Git-scoped plugin manifests.

Claude: .claude-plugin/ metadata is included alongside the verified ok mcp install claude --repo /absolute/path/to/repo MCP config path.

Cursor: .cursor-plugin/ rules and skills are included alongside the verified ok mcp install cursor --repo /absolute/path/to/repo MCP config path.

Starter examples with golden prompts and one-command smoke tests are available in examples/cursor and examples/claude.

ok status --markdown --write ok-status.md creates a portable handoff with index counts, SCIP quality, readiness checks, and next steps. ok setup audit checks the index, security posture, MCP server health, plugin metadata, and the supported client install matrix.

Multi-Project Workspace

For a fleet or multi-service workspace, index each project first, then create a workspace config:

[workspace] projects = [ { name = "service-a", repo = "../service-a" }, { name = "service-b", repo = "../service-b" }, ]

Run the cross-project linker without reparsing source:

ok index --mode cross-project --workspace /absolute/path/to/workspace ok architecture fleet --workspace /absolute/path/to/workspace

Index Snapshots

Teams and CI can share a known-good local index without sharing personal memory or compressed context state:

ok --repo /absolute/path/to/repo snapshot export --quality best ok --repo /absolute/path/to/repo snapshot doctor ok --repo /absolute/path/to/repo snapshot import ok --repo /absolute/path/to/repo index --from-snapshot auto

Quality Mode

Open Kioku works without external language indexers, but exact references improve search grounding, impact analysis, test selection, and planning. Check what is available:

ok setup audit /absolute/path/to/repo --markdown --write ok-setup.md ok scip doctor /absolute/path/to/repo ok scip setup /absolute/path/to/repo ok index /absolute/path/to/repo --with-scip auto ok doctor /absolute/path/to/repo

Default indexing consumes existing SCIP files such as index.scip and .ok/indexes/*.scip when present. --with-scip auto runs installed indexers for supported repos; it does not install third-party tools. --with-scip required fails the index if no SCIP facts can be imported.

SCIP is the primary precision provider. The default quality model stays local and free: indexed symbols/chunks/imports, language-specific static facts, indexed tests, build-system detection, and SCIP exact references when an index.scip is available. Java/Gradle repositories get scoped validation commands when the test file path is known, for example ./gradlew :x-pack:plugin:ml:test --tests org.example.SomeTests instead of a generic repository-wide test command.

Language-specific static analysis adds durable graph facts such as imports, Java inheritance and implemented interfaces, Spring/Express/FastAPI/Rust route declarations, config reads, and database table mappings. Git-history analysis is local and enabled by default: ok index and ok watch read a bounded local history window, store typed commit metadata and complete per-file touches (including detected renames), and preserve co-change, path-to-test co-run, churn, provenance, ownership, reviewer, and similar-change evidence for planning, ranking, impact, contracts, and test selection. History score components are named history_churn, ownership_risk, similar_change_overlap, and reviewer_affinity; exact references and exact symbol/file evidence remain authoritative. Configure the window with [history] max_commits = 500, or disable it with [history] enabled = false in ok.toml.

Runtime analysis is opt-in evidence ingestion only: place local JSONL trace, span, log, incident, error, or failure artifacts under .ok/runtime/ or .ok/analysis/runtime/ with source file paths plus fields such as service, symbol/function, route, HTTP method, status code, duration, timestamp, SQL statement, and message, then re-run ok index. Open Kioku turns matching entries into runtime signals and aggregates for context, ranking, impact, test selection, and post-edit verification. Runtime evidence is local observation only: it never replaces source, symbol, test, or exact-reference truth.

Validation evidence is also local and opt-in. ok index ingests JUnit XML, lcov, Cobertura XML, JaCoCo XML, and coverage.py XML/JSON reports from .ok/analysis/, .ok/coverage/, coverage/, target/site/, build/reports/, and reports/. Covered lines are mapped to indexed files and symbols where possible, linked to plausible indexed tests, and surfaced as TEST_COVERS / VALIDATES graph facts.

Use ok eval to protect quality on real workflows:

ok eval /absolute/path/to/repo \ --case "fix token expiration=src/auth.rs,tests/auth_flow.rs" \ --min-recall-at-k 0.8 \ --min-mrr 0.5

Use ok workflow-bench for plan → edit → verify benchmark cases:

ok workflow-bench . --cases-file benchmarks/workflow-cases.json --lim

[truncated for AI cost control]