Skip to main content
Glama

Open Kioku

Your coding agent shows its evidence before it edits, and its diff is verified against the plan it declared.

A local index of your repository feeds a bounded plan; after the edit, ok verify checks the actual changed files against that plan. Nothing leaves your machine.

CI npm npm downloads crates.io crates.io downloads License

Website · First win · What to expect · Install · MCP tools · Architecture


First Win: 2 Commands

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

Use claude instead of cursor for Claude Code. One command indexes the repository, writes repository-scoped MCP configuration and agent guidance, and checks that the local server answers (run without --apply to preview; nothing is written). Then ask for evidence on a real task:

ok context "reap the doctor's MCP probe child process" --format markdown

This is the actual output on this repository, trimmed: … marks cut lines, and each primary unit is collapsed to its line range and first line. The commit that made this change touched exactly one file, and it is the first result:

# Task: reap the doctor's MCP probe child process

## Confidence
- Overall: `Medium` (`0.74`)
- Caveats:
  - exact symbol/reference evidence is absent
  - runtime corroboration is absent
- Components:
  …
  - `exact_references` score `0.25`, weight `0.20`, contribution `0.05`
  …
  - `task_relevance` score `1.00`, weight `0.20`, contribution `0.20`
  …
## Retrieval
…
- Attempted: `lexical, document, exact_semantic, graph, validation, git_history, runtime`
- Succeeded: `lexical, document, exact_semantic, graph, validation, git_history`
…
- Exact-authority selections: `0`; ambiguity/unresolved signals: `0`
- Retrieval confidence: `Medium` (qualitative ContextPack confidence, not a calibrated probability)
- Caveats:
  - no runtime traces, logs, or incidents are ingested for this repository
  …
## Primary Context
### crates/open-kioku-cli/src/reports/status_setup_doctor.rs
Lines 1-107  `fn file_path_for_symbol(store: &dyn MetadataStore, symbol: &Symbol) -> anyhow::Result<PathBuf> {`
### crates/open-kioku-core/src/process.rs
Lines 66-180  `fn proc_status_peak_rss_bytes() -> Option<u64> {`
…

The label is Medium, not higher, for one reason the pack states: the task names no identifier the index resolves exactly and this repository has no SCIP index, so exact_reference_count is 0 (exact_references scores 0.25; Exact-authority selections is 0), which caps the score at 0.74 and the label at Medium. Runtime artifacts are absent too; that is the second caveat, and it lowers the score, not the band. Exact is reserved for packs with at least one exact-authority selection; a lexical match, however good, does not earn it. The task is phrased as the fixing commit's subject, so git history corroborates the first file alongside the lexical match. Every pack says which evidence streams ran, which succeeded, and what is missing. Missing evidence lowers the stated confidence; it is never papered over.

Related MCP server: Atlas

What You Get

ok plan "change token expiration" --format json > plan.json   # context, impact, tests, edit boundary, caveats
# ...edit with your normal agent or editor...
ok verify --plan plan.json --git                               # the real diff against the declared boundary

ok plan (or the plan_change MCP tool) returns primary context with provenance, impact candidates split into structurally proven and heuristic, validation targets tiered by evidence, an edit boundary (allowed, caution, forbidden paths), and explicit caveats. ok verify reads the actual changed files and reports, for example, [out_of_boundary] go/shipping/carrier.go: path is outside the saved plan boundary. A green exit code from a test runner is not proof the right files changed; this is.

The Gate

Every verification step a coding agent is given today is an instruction to the model. This one runs.

ok gate install claude --apply     # once per repository; the Claude Code plugin ships the same hooks

That is the whole setup. The first prompt of a conversation plans an edit boundary in the background; later prompts widen it; every Edit, Write and shell write is judged against it; every stop that follows a change verifies the real change (files created with no hook included) and writes a Change Dossier: what was declared, what the harness reported, what was denied, what actually changed, what verification found, and what is still uncertain.

A session started from a prompt is advisory: it records which edits fall outside the boundary without interrupting the agent about them, denies secret-like and generated paths, and its boundary holds nothing, because a plan built from a prompt cannot tell a task from a remark (measured: "fix it" plans with the same confidence as a real commit subject). The boundary is binding where someone declared it: ok gate start "<task>", mode = "enforce" in ok.toml, or --mode enforce in CI. There a FAIL holds the agent, or fails the check, with the violations and the one remedy, ok gate expand <path> --reason "<why>".

ok gate ci --base origin/main --task "$PR_TITLE" --write dossier.md   # a dossier for any pull request, no hooks; fails on forbidden paths
ok gate install git --apply        # any agent, any person: a pre-commit hook that refuses a staged secret

Measured on commit-derived sessions and three live Claude Code sessions; method, numbers and caveats in benchmarks/gate/. docs/gate.md

Ripple: what the diff does not show

$ ok ripple
Ripple: 2 site(s) no longer fit 1 changed declaration(s).

src/click/utils.py:62  function `_make_default_short_help`: signature changed
  - def _make_default_short_help(help: str, max_length: int = 45)
  + def _make_default_short_help(help: str, max_length: int, strict: bool)
  broken: 2 site(s)
    src/click/core.py:1275 (in Command.get_short_help_str)  text = _make_default_short_help(self.help, limit)
        does not pass `strict`, which is required now [by name]
    tests/test_utils/test_make_default_short_help.py:62 (in test_make_default_short_help)  out = click.utils._make_default_short_help(value, max_length)
        does not pass `strict`, which is required now [by name]

A change that alters a function's parameters, or removes or renames a declaration, breaks code the diff never shows. ok ripple finds the calls that no longer fit and the code that still names what is gone, in Rust, Python, TypeScript, JavaScript, Go, Java and C#, with no index and nothing to set up. The same hooks tell a coding agent right after the edit that caused it, and tell you at the stop what it left; ok gate ci puts the list in the pull request's dossier. It reads syntax, not types: a call is claimed only when it fit the old signature and does not fit the new one, and only when an import or a qualifier leads from it to the declaration, or the function around it says its receiver is of the declaring type.

Measured four ways, and changed by each. On the last 300 commits of 46 open-source repositories in seven languages (7,711 commits that change code), given only the file that declares each change, it names 1,411 broken sites; the real commit went on to change 1,398 of them and 12 more were code the commit really left broken. On the complete merged commits it names 15 sites in 4 commits, all four real: commits on the main branch of a widely used library that still named something they had removed. On 14 repositories it had never been run on, 275 of 275, and a fifth real leftover. Against type checkers (Go's, pyright, tsc) on 835 signature changes, it counts 53% of the sites the checker reports and counts or lists 93% (Go 78%, TypeScript 34%, Python 37%, where little is typed); the first version counted 18%. What it does not show: on five small tasks, with and without being asked to update the callers, current models left nothing broken or said what they left, with or without the hooks. So the hooks tell and do not hold unless you ask them to ([gate] ripple = "hold").

See it on a real commit. scripts/demo-replay.sh stops a commit to psf/black halfway, with one function given a required parameter and its callers not yet updated. Ripple names six calls in 0.2 seconds, and the finished commit changed all six. CI runs the script on every pull request against the output recorded in demo/proof/replay-black/; the walk-through, with a recorded Claude Code session on the same change, is at openkioku.com/see-it-work.

docs/ripple.md · benchmarks/ripple/

Underneath: exact definitions, references, and dependency paths from source (and optional SCIP) are authoritative. Lexical, semantic, history, test, and runtime signals can reorder retrieval; they cannot overwrite repository truth.

What Changed in 5.0.0

Released 2026-11-12. Run ok index after upgrading: every analysis-semantics version moved, and a 4.0 index withholds relationship evidence and says so until it is rebuilt. Then ok semantic index if you use semantic search. Source builds need Rust 1.89. The upgrade notes at the top of the changelog list the JSON shapes and exit codes a script should check.

  • The gate (experimental). ok gate holds a coding agent's edits to the boundary its plan declared, through Claude Code hooks, and writes a verified Change Dossier when it stops; ok gate ci writes one for any pull request, and ok gate install git puts the forbidden-path check in a pre-commit hook for every other agent and for people. A boundary nobody declared is reported, not enforced: replayed over this repository's last 20 merged commits, a binding boundary failed all 20, so by default only a forbidden path (a secret, key material, a dependency directory, generated output) fails. On a repository that is not this one, with a real agent, the gate did not change what the agent produced on four real commits, took about six seconds longer per task, and refused the one edit to a secret file. On ten real Django fixes with the tests as judge, two models solved every task with and without the plugin at the same cost, and never called its tools; the gate's notices about edits outside a boundary planned from the prompt were wrong 142 times in 148 and cost the smaller model turns, so an advisory session no longer says them to the agent (docs/gate.md, benchmarks/gate/, benchmarks/agent-ab/outside-repository.md, benchmarks/agent-ab/large-repository.md).

  • Answers an agent can afford to read. plan_change with detail: "brief" and ok preflight --format brief give the start decision in a kilobyte or two: on this repository one plan is 155 KB as Markdown and the brief of the same task is 1.9 KB. ok --json status went from 1,771,248 bytes to 24,392 on this repository by summarising its notes.

  • Rust relationships proven across crates, re-exports and module layouts. Calls and imports resolve across workspace crates, through pub use, struct fields, and cfg- and #[path]-selected modules: 1,765 authoritative edges added on this repository and thirteen published crates by one change alone, each where the previous build had no edge (#476). A glob-heavy crate of about 110 Rust files that ran for more than 15 minutes indexes in about 12 seconds (#659).

  • Impact analysis reads by importance and counts what it left out. ok impact takes --symbol and --since, reports deleted files and downstream crates, and lists proven dependents first; the "list was cut" caveat fires on 5 of 55 files of this repository instead of 48, and workflow-benchmark impact recall went from 0.925 to 0.975 (#584).

  • Fewer name-match edges, and authority on every graph answer. The symbol registry no longer links across languages, from comments or strings, or from locals: estimated precision of its unique-name edges rose from about 50% to 70% on a Go service, 51% to 77% on a Java module, 27% to 87% on a Python library and 13% to 97% on this repository, at a stated cost in correct edges (#582). ok path, dependency_path and graph queries label each hop's authority.

  • Secrets stay out of the index files. Secret-like values in config, data and prose are stored as [REDACTED], as is a private key pasted into source; content of a path later excluded is removed from the database, its write-ahead log, the vector store and context handles (#379, #676). cargo audit is clean, including the SQLite fix for RUSTSEC-2026-0459.

  • Coverage says what is missing. Build and dependency directories are pruned on evidence and named, not on their name alone, and a coverage gap names its language, cause and directories. On this repository ok doctor went from coverage 241 of 1,690 programming-language files indexed (14.3%) to 241 of 241 (100.0%) (#477, #661).

  • One ranking, repeatable. ok search and MCP search_code share one ranked search (#448), and two indexes of one tree score identically: byte-identical ok --json search output for all 30 retrieval-benchmark queries, against 237 differing values on the previous build (#491).

  • C# symbols. .cs files are parsed into namespaces, types and members (#680). Relationships, using directives and test discovery are not there yet (#681–#683).

What to Expect

Retrieval is measured on the production path (ok context, the same builder behind ok plan and the MCP build_context_pack tool) on four real repositories, each indexed at a fixed base commit. Every case is a later commit: the query is its subject line, the answer is the source files it changed. Cases are split chronologically; both splits are gated nightly, and the table shows holdout.

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. That is the floor the agent starts from before it has looked at anything, and it is the number to watch. Exact lookups (definitions, references, dependency paths) and the plan → edit → verify loop sit on top of it.

These baselines were frozen on 2026-09-25 from one hosted Linux runner matrix run of commit bd5d06ab, and a second run of the same commit produced identical scores (timings aside). .github/workflows/commit-derived-bench.yml re-derives them nightly; the job fails when a watched metric falls more than 0.03 below its frozen baseline, or when a routed task family of 34 or more cases whose case membership is unchanged falls more than max(0.03, 2/n) below its own. Queries are commit subjects, not issue text, so the numbers are not comparable with published benchmarks that use issue text. Corpus descriptions, both splits, the scripts, and the regression policy: docs/retrieval-benchmark.md; frozen baselines: benchmarks/commit-derived/.

Two more measured facts:

  • When the task has no answer. On the 30-case frozen fixture, none of the five no-gold tasks is presented as an answer: the no-gold false-positive rate is 0.0 (the CI ceiling is 0.25), and the advisory routed context-pack strategy in the same run (cc4:routed_contextpack) returns none of them above Low. A low-confidence pack still lists candidates; it tells the caller not to trust them rather than returning nothing. benchmarks/retrieval-baseline.json

  • Optional local neural embeddings. The default local neural profile (a 149M-parameter int8 model, pinned by digest) improved every metric on the Go and TypeScript corpora against a same-day control, by about +0.025 MRR, on 4-vCPU / 16 GB hosted runners. Real but modest; the lexical ranking fixes landed the same day were worth about four times as much. docs/embedding-providers.md

Measured at Scale

Performance claims are observations tied to an identifiable build, published with method and caveats. The most recent end-to-end scale record validates the 3.1.0 release lineage at source commit 3959fdfb6ca27d0c279b635fca7fc1b7935d4889 on a large Java repository, on the same host and protocol as the previous public record. 4.0.0 changed the index storage format and has not been re-run on this corpus; the table describes 3.1.0. 4.0.0's own measured changes are listed with their commits and methods in CHANGELOG.md.

Measurement (v3.1.0 lineage, end to end)

Result

Tracked source files / Java files

16,537 / 12,580

Indexed files / symbols / chunks

13,607 / 247,499 / 248,107

Graph nodes / edges

402,844 / 1,522,135

Cold structural index

19m 28s

Exact class lookup, fresh process

0.02–0.05s

Exact references / lexical search, fresh process

0.74s / 0.24s

Exact-flat semantic build

495,606 vectors in 58.8s; 0 failures

Persistent HNSW build

495,606 vectors in 10m 19s; 0 failures

Against main at c96f61a on the identical corpus and host (methodology): per-command startup ~14s → sub-second, exact class lookup 13.9s (returning an incorrect symbol not found) → 0.02s with the correct class, cold structural index 40m 40s → 19m 28s. The repeat index reproduced identical totals and four parallel graph readers completed with zero lock failures. The repository identity is withheld, so this is a scale record rather than a replayable corpus: machine-readable evidence · methodology · previous record: v3.0.4 evidence.

More artifacts: local semantic scale, 51,349 vectors, persistent HNSW auto-selected, 21.70s fresh build, 0 stale / 0 failed vectors (demo/proof/ann-50k-dogfood.json); plan → edit → validate → verify through the policy-gated runner, 2 passed, 0 boundary violations, final verdict warn because stronger evidence was absent (demo/proof/verification-dogfood.json); a public repository audit, 4,600+ files, 46,000+ symbols, 8,900+ tests indexed in 33.1s (docs/large-repo-proof.md).

These are local workstation timings, not universal guarantees.

Install

Channel

How

npm (recommended)

npm install -g open-kioku — the wrapper pulls @open-kioku/{darwin-arm64,linux-x64,linux-arm64,win32-x64} (sources under packages/)

crates.io

cargo install open-kioku-cli or cargo binstall open-kioku-cli

GitHub releases

Binaries with SHA256SUMS, SBOM.cargo-metadata.json, PROVENANCE.json, and GitHub build-provenance attestations (docs/release-trust.md)

Claude Code plugin

claude_plugin.json and .claude-plugin/

Cursor / Codex plugins

.cursor-plugin/ · .codex-plugin/

MCP directories

Glama (glama.json) · Smithery (smithery.yaml)

From source

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

Connect an Agent

ok setup agent claude --repo . --apply    # Claude Code: index + .mcp.json + managed skill, then a live MCP check
ok setup agent cursor --repo . --apply    # Cursor: index + .cursor/mcp.json + managed rule
ok mcp install codex  --repo .            # Codex: prints the TOML server entry
ok mcp install gemini --repo .            # Gemini CLI: prints the JSON server entry

ok setup agent --apply is wired for claude and cursor; every other client listed by ok mcp install --help gets a read-only configuration snippet from ok mcp install <client>. The MCP server is local, read-only, and speaks stdio. It advertises 16 tools — one per question nothing else answers — each carrying usage guidance, input/output schemas, safety annotations, and routing categories, and a metadata regression test rejects new tools that omit any of it. Memory and runtime-error tools appear only once those features are configured; the architecture, history and ownership capabilities ship on the CLI (ok architecture …, ok history …, ok contract show).

Step-by-step guides: Claude Code · Cursor · Codex · Gemini CLI · CI: open-kioku-action (docs/github-action.md)

Every ok mcp install client, with its generated config shape and how to confirm the connection: docs/guides/cross-harness-setup.md

Why Local

  • No hosted index and no source upload: everything lives under the repository's .ok/ directory, and ok prove shares counts and scores without source snippets.

  • MCP is read-only by default; source edits stay in your normal editor or agent harness.

  • Command execution and model downloads are policy-gated, secret-like paths are blocked, and network denial fails closed rather than degrading silently.

docs/security-model.md · SECURITY.md · docs/release-trust.md

How It Is Measured

Threshold changes are product changes and are reviewed as such; a threshold is never lowered to make CI green.

More Than One Repository

Semantic retrieval is optional and local (ok --repo . semantic index, then ok search "authorization expiry" --hybrid); model acquisition needs explicit consent and is refused under network denial (docs/semantic-search.md, docs/vector-index.md). Index projects individually and link them into a workspace (ok index --mode cross-project --workspace <dir>, ok architecture fleet). Export and import known-good indexes for team and CI reuse (ok --repo . snapshot export --quality best, ok --repo . index --from-snapshot auto); personal memory is excluded from shared snapshots by default. Detect architecture, check policies, and create bounded change contracts (ok --repo . architecture detect, ok --repo . contract create "update API boundary"). Git history is on by default with a bounded window; runtime traces and coverage reports are opt-in local inputs that never outrank exact source truth.

Language Support

Tree-sitter parsing and symbol extraction cover Rust, Python, TypeScript/TSX, JavaScript/JSX, Go, Java, and C#. C# calls, type uses and base lists are resolved through namespaces and using directives; calls to static members through a type's name, extension methods, global using and the project model are not resolved yet, and no C# callable counts as a test. YAML and JSON are parsed structurally; file/chunk indexing also covers TOML, SQL, Markdown, Terraform, and other repository text. Language-aware resolution adds scope, import, receiver/type, containment, and inheritance semantics where supported.

Exact Java definitions and references from a scip-java index: docs/guides/java-scip.md

Useful Commands

ok --repo . search "token expiration handler"
ok --repo . symbol definition PolicyGate
ok --repo . symbol refs PolicyGate
ok --repo . impact --file src/auth.rs
ok --repo . ripple --base origin/main
ok --repo . tests --changed src/auth.rs
ok --repo . context "change token expiration" --format markdown
ok --repo . plan "change token expiration" --format markdown
ok --repo . verify --plan /tmp/plan.json --git
ok --repo . history similar --task "change token expiration" --path src/auth.rs
ok prove . --task "change token expiration"

Current top-level commands (40): init, index, snapshot, watch, status, doctor, setup, demo, search, semantic, symbol, explain, impact, ripple, path, tests, context, retrieve-context, plan, preflight, verify-boundary, verify, gate, contract, bench, workflow-bench, retrieval-bench, relationship-bench, contract-bench, eval, prove, adr, ui, architecture, history, patch, memory, mcp, scip, and graph.

Full MCP tool reference: docs/mcp-tools.md

Repository Layout

This is a 44-crate Cargo workspace with a strict downward dependency direction: CLI / MCP → agent intelligence (context, impact, tests, plan, patch, gate, actions) → code-intelligence kernel (ingest, parse, tree-sitter, resolution, graph, architecture) → storage and search (storage-sqlite, search-tantivy). open-kioku-core holds the evidence, graph, and report contracts; optional integrations (scip, lsp, semantic, vector, qdrant, sentry) return explicit disabled/unsupported diagnostics rather than degrading silently.

Architecture: docs/architecture.md · Crate map: docs/crate-map.md · Storage: docs/storage-model.md

Development

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
scripts/validate-docs.sh
ok retrieval-bench . --cases-file benchmarks/retrieval-cases.json --min-cases 30
ok workflow-bench . --cases-file benchmarks/workflow-cases.json --limit 10

Maintainer-led and source-available under Elastic-2.0; see CONTRIBUTING.md before opening a pull request.


If Open Kioku improves your agent workflow, consider starring the repository.

Available Tools

42 tools
architecture_boundariesOpen Kioku Architecture BoundariesA
Read-onlyIdempotent

Retrieve the configured or inferred component boundaries and their import constraints. Returns boundary definitions including component names, directory mappings, and allowed or forbidden dependency directions. Use to inspect the configured or inferred component boundaries and their import constraints before explaining or checking violations. Do NOT use for detecting actual violations (use architecture_violations), for policy-backed enforcement against indexed edges (use architecture_policy_check), or for explaining why a file belongs to a component (use architecture_policy_explain). This is read-only.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

architecture_policy_checkOpen Kioku Architecture Policy CheckA
Read-onlyIdempotent

Evaluate repository-owned architecture policy dependency rules against indexed import, reference, and call graph edges. Returns allowed, forbidden, and unknown edge counts with bounded unknown samples. Use to enforce architecture policy against indexed import/reference/call edges. Use architecture_policy_validate first for policy syntax errors and architecture_policy_explain for why a specific file or symbol matched. This is read-only.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

architecture_policy_explainOpen Kioku Architecture Policy ExplainA
Read-onlyIdempotent

Explain architecture policy component, public API boundary, and exemption evidence for one indexed file, symbol, or the whole repository. Use after a policy check to explain component membership, public API boundaries, or exemptions for one file, one symbol, or the whole repo. This is read-only and does not change policy.

Inputs: file, scope, symbol. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

architecture_policy_validateOpen Kioku Architecture Policy ValidateA
Read-onlyIdempotent

Validate the resolved repository architecture policy, or an explicit policy TOML path, without evaluating indexed graph edges. Use before architecture_policy_check when editing or debugging policy TOML syntax and component resolution. It validates policy shape only and does not evaluate graph edges.

Inputs: path. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

architecture_violationsOpen Kioku Architecture ViolationsA
Read-onlyIdempotent

Detect and report import-graph boundary violations that deviate from the inferred architecture layers. Returns violation details including source file, target file, violated boundary, and edge type. Use for a quick boundary-violation scan based on inferred architecture layers and import patterns without consulting ok.toml policy rules. Do NOT use when policy TOML rules must be authoritative (use architecture_policy_check instead) or when explaining why a specific file violates a boundary (use architecture_policy_explain). This is read-only and reads only from the local index.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

build_compressed_contextOpen Kioku Build Compressed ContextA

Build a compressed context pack with short handles instead of full source snippets, reducing token count for prompt-constrained scenarios. Use retrieve_context with the returned handles to expand original snippets on demand. Use when a context pack is needed but prompt token budget is constrained. Returns compressed references with short handles instead of full source snippets, significantly reducing token count. Call retrieve_context later with a handle to expand the original snippet. Do NOT use when full inline context is acceptable (use build_context_pack) or when only test targets are needed (use find_tests_for_change). This tool writes reusable context handles under the .ok data directory and is not idempotent.

Inputs: task (required), limit, format. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

build_context_packOpen Kioku Build Context PackA
Read-onlyIdempotent

Assemble a ranked, token-efficient context pack of relevant files, symbol definitions, test targets, git history evidence, and architecture policy context for a natural-language task. Returns results in JSON, Markdown, or TOON format. Use before planning or editing to assemble a ranked bundle of relevant files, symbol definitions, test targets, git history evidence, and architecture policy context for a natural-language task description. Returns results in the specified format (JSON, Markdown, or TOON). Do NOT use when prompt token budget is tight (use build_compressed_context with retrievable handles instead) or when only test recommendations are needed (use find_tests_for_change). This is read-only and queries the local index and git history only.

Inputs: task (required), limit, format. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

create_change_contractOpen Kioku Create Change ContractA

Create and optionally store a versioned change contract from a task or saved plan while preserving plan_change for backwards compatibility. Use when a plan needs a durable verification contract for later review or CI evidence. By default it writes a contract under .ok/contracts; set store=false for a transient contract.

Inputs: plan, task, limit, since, +3 more. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

dependency_pathOpen Kioku Dependency PathA
Read-onlyIdempotent

Trace the shortest dependency or reference path between two files or symbols, illustrating how they are connected. Use to explain how two files or symbols are connected through indexed dependencies. Prefer module_dependencies for local neighbors and impact_analysis for downstream blast radius. This is read-only.

Inputs: to (required), from (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

detect_architectureOpen Kioku Detect ArchitectureA
Read-onlyIdempotent

Infer high-level architectural components and layers from the repository directory structure and file layout. Returns detected component names, directory paths, and inferred layer assignments using heuristic analysis. Use to infer high-level architectural components and layers from the repository directory structure using heuristic analysis. Do NOT use when enforced policy rules are needed (use architecture_policy_check), when specific boundary constraints are needed (use architecture_boundaries), or when file-level policy membership must be explained (use architecture_policy_explain). This is read-only and performs heuristic detection only.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

explain_fileOpen Kioku Explain FileA
Read-onlyIdempotent

Retrieve comprehensive indexed metadata for one repository-relative file, including language detection, syntax parsing status, all code chunks with line ranges, and associated symbol definitions. Use to retrieve comprehensive indexed metadata for one known repository-relative file, including language detection, syntax parsing status, all code chunks with line ranges, and associated symbols. Do NOT use to discover files by keyword (use search_files), for symbol-level context (use explain_symbol or get_symbol_context), or for architecture-level file analysis (use architecture_policy_explain). This is read-only and returns only previously indexed data.

Inputs: path (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

explain_symbolOpen Kioku Explain SymbolA
Read-onlyIdempotent

Retrieve a concise explanation of one indexed symbol, including its definition range, qualified name, kind (function, class, struct, trait), and direct structural relationships within the codebase. Use for a concise explanation of one known symbol, returning its definition range, qualified name, kind, and direct structural relationships. Do NOT use for a comprehensive context bundle with docs and surrounding code (use get_symbol_context), for fuzzy symbol search (use search_symbols), or for cross-reference tracing (use get_references). This is read-only and reads from the local index.

Inputs: query (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

explain_test_coverageOpen Kioku Explain Test CoverageA
Read-onlyIdempotent

Retrieve stored test-coverage evidence and associated test suites for one repository-relative file or the whole repository. Returns coverage percentages, test file associations, and suite metadata from indexed data. Use to inspect stored test-coverage evidence for one file path or the whole repository. Returns associated test suites, coverage percentage when available, and test file associations from indexed metadata. Do NOT use to decide what tests to run next (use recommend_validation_plan) or to find tests for a specific change (use find_tests_for_change). This is read-only, does not execute any tests, and reports only previously indexed or stored coverage data.

Inputs: path, limit. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

explain_verificationOpen Kioku Explain VerificationA
Read-onlyIdempotent

Explain a contract verification report, including the decision, boundary failures, warnings, dependency deltas, validation attestations, and recommended tests. Use after verify_change_contract to translate a verification report into a decision, failures, warnings, and next tests. This is read-only.

Inputs: format, verification, verification_json. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

find_tests_for_changeOpen Kioku Find Tests For ChangeA
Read-onlyIdempotent

Identify test files that should be run to validate changes to one repository-relative file. Returns ranked test file paths with relevance scores based on naming conventions, import relationships, and co-change history. Use after identifying a changed file to select relevant test files that should be run to validate the change. Returns ranked test file paths with relevance scores based on naming conventions, import relationships, and co-change history. Do NOT use when a broader validation plan including static checks and coverage actions is needed (use recommend_validation_plan) or when checking existing coverage data (use explain_test_coverage). This is read-only.

Inputs: path (required), limit. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

get_change_contractOpen Kioku Get Change ContractA
Read-onlyIdempotent

Retrieve a stored change contract by id and optionally export it as JSON, Markdown, or TOON. Use to retrieve a previously stored contract by id before verification or explanation. Prefer create_change_contract for new contracts. This is read-only.

Inputs: contract_id (required), format. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

get_definitionOpen Kioku Get DefinitionA
Read-onlyIdempotent

Retrieve the definition location, file range, and body of a symbol (function, class, struct, trait, module) by its name. Use after resolving a symbol name to retrieve its defining range and body. Prefer search_symbols for candidate discovery and get_symbol_context when surrounding references and documentation are needed. This is read-only.

Inputs: query (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

get_evidence_schemaOpen Kioku Get Evidence SchemaA
Read-onlyIdempotent

Retrieve the versioned schema defining the supported graph node types, edge types, and query properties available in the repository's structural evidence graph. Use before query_evidence_graph to learn available graph node types, edge types, and properties. This is read-only and does not query graph data.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

get_referencesOpen Kioku Get ReferencesA
Read-onlyIdempotent

Retrieve all references, usages, and call-sites of a given symbol throughout the indexed codebase. Use to find usages of a resolved symbol across the index. Prefer get_callers for caller-only relationships and impact_analysis for broader file-level blast radius. This is read-only.

Inputs: query (required), limit. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

get_symbol_contextOpen Kioku Get Symbol ContextA
Read-onlyIdempotent

Retrieve a comprehensive context bundle for one symbol, including its full definition body, file location and range, enclosing scope, documentation comments, and surrounding code context from the local index. Use to retrieve a comprehensive context bundle for one symbol, including its definition body, file location, enclosing scope, documentation comments, and surrounding code context when indexed. Returns more detail than get_definition. Do NOT use for simple definition lookup only (use get_definition), for fuzzy symbol search (use search_symbols), or for cross-reference tracing (use get_references). This is read-only and reads from the local index.

Inputs: query (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

impact_analysisOpen Kioku Impact AnalysisA
Read-onlyIdempotent

Analyze the blast radius of a change to one repository-relative file using the indexed dependency graph. Returns ranked downstream dependent files, caller functions, related test files, and architecture policy impact with impact scores and relationship types. Use before editing a file to estimate the blast radius: downstream dependent files, caller functions, related test files, and architecture policy impact from the indexed dependency graph. Do NOT use when only test targets are needed (use find_tests_for_change) or for a comprehensive validation plan including static checks (use recommend_validation_plan). This is read-only and analyzes the local index only.

Inputs: path (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

list_filesOpen Kioku List FilesA
Read-onlyIdempotent

List all indexed files within the repository. Returns metadata such as relative path, size in bytes, and language. Useful for codebase structure discovery. Use for broad repository inventory and pagination over indexed paths; use search_files when you already have a keyword or path fragment. This is read-only and returns indexed data only.

Inputs: limit, offset. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

list_languagesOpen Kioku List LanguagesA
Read-onlyIdempotent

List all programming languages detected and indexed in the repository, alongside support status. Use for a quick language/support overview before choosing language-specific investigation paths. This is read-only and does not rescan the repository.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

list_symbolsOpen Kioku List SymbolsA
Read-onlyIdempotent

List or substring-filter all indexed code symbols (functions, classes, structs, traits, interfaces) with pagination. Returns symbol name, kind, file path, and line range for each entry. Use to browse the indexed symbol table or filter by exact substring match. Supports pagination via limit and offset. Do NOT use for fuzzy or ranked symbol search (use search_symbols), for retrieving a symbol's full definition body (use get_definition), or for comprehensive symbol context (use get_symbol_context). This is read-only and reads from the local index only.

Inputs: limit, query, offset. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

module_dependenciesOpen Kioku Module DependenciesA
Read-onlyIdempotent

List the direct dependency graph neighbors (imports and dependents) of a given file or symbol node. Use to inspect direct dependency neighbors for one file or symbol. Prefer dependency_path for a route between two nodes and architecture_policy_check for rule violations. This is read-only.

Inputs: node (required), limit. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

plan_changeOpen Kioku Plan ChangeA
Read-onlyIdempotent

Generate an evidence-backed pre-edit plan for a task, including primary files to edit, expected impact, changed-line ranges, and recommended test targets. Use before editing to create an evidence-backed plan with expected files, ranges, impact, and tests. Prefer create_change_contract when the plan must be persisted and verified later. This is read-only.

Inputs: task (required), limit, since, format. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

propose_patchOpen Kioku Propose PatchA
Read-onlyIdempotent

Propose a patch plan (file edits, context bounds) for a task. Read-only; does not write any files. Use to draft a patch plan without modifying files. Prefer plan_change for evidence-backed planning and apply_patch only after explicit approval in write-enabled mode. This is read-only.

Inputs: task (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

query_evidence_graphOpen Kioku Query Evidence GraphA
Read-onlyIdempotent

Execute a read-only graph query using a constrained subset of Cypher. Call get_evidence_schema first to see available node/edge types. (Note: The DSL is NOT full Cypher). Output rows are JSON arrays aligned with the user-selected variables in columns. Use for advanced read-only evidence queries after inspecting get_evidence_schema. The query language is a constrained Cypher-like DSL, not full Cypher; prefer purpose-built tools when available.

Inputs: query (required), limit, offset. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

recommend_validation_planOpen Kioku Recommend Validation PlanA
Read-onlyIdempotent

Recommend a comprehensive validation plan (test targets, coverage checks, static checks) for a file change. Use before finalizing a change to choose tests, static checks, and coverage actions for one path. Prefer find_tests_for_change for test-only recommendations. This is read-only.

Inputs: path (required), limit. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

remember_factOpen Kioku Remember FactA

Persist a durable, repository-scoped memory fact into the local .ok SQLite store with optional source attribution and confidence level. The fact is append-only and survives re-indexing. Use only for durable, repository-scoped facts (architectural decisions, ownership conventions, known anti-patterns) that an agent should recall across sessions. Appends an immutable record to the local .ok SQLite store; duplicates are not deduplicated. Do NOT use for transient session notes, per-task scratch data, or facts derivable from the live index. Call search_memory first to avoid recording redundant entries. This tool writes to local storage and is not idempotent.

Inputs: text (required), source, confidence. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

repo_statusOpen Kioku Repo StatusA
Read-onlyIdempotent

Retrieve the current repository index metadata, including file count, symbol count, chunk count, and the exact timestamp when the repository was last indexed. Use first to check whether the local index exists and is fresh enough before calling search, symbol, or graph tools. This is read-only and only inspects repository metadata.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

retrieve_contextOpen Kioku Retrieve ContextA
Read-onlyIdempotent

Retrieve the original uncompressed source code snippet associated with a compressed context handle. Use only with handles returned by build_compressed_context to recover original snippets. Prefer build_context_pack for a fresh task-level context bundle. This is read-only.

Inputs: handle (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

review_patchOpen Kioku Review PatchA
Read-onlyIdempotent

Review a proposed patch plan for safety, target constraints, completeness, and potential regressions. Returns a structured safety assessment with warnings, risk indicators, and recommendations. Use to review a proposed patch plan for safety, target constraints, completeness, and potential regressions before applying it. Returns a structured safety assessment with warnings and recommendations. Do NOT use for architecture boundary and reference validation only (use validate_patch) or for post-edit verification against a plan (use verify_change). This is read-only and does not modify any files.

Inputs: task (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

search_codeOpen Kioku Search CodeA
Read-onlyIdempotent

Perform a lexical BM25 search across indexed code chunks. Set mode=graph to search indexed graph-node identifiers, qualified names, routes, config keys, and properties. Use for lexical BM25 code search when exact identifiers, terms, routes, or config keys are known. Prefer semantic_search for conceptual queries, hybrid_search when both lexical and semantic evidence are needed, and regex_search for exact patterns. This is read-only.

Inputs: query (required), mode, limit, offset. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

search_filesOpen Kioku Search FilesA
Read-onlyIdempotent

Search indexed file names and contents for specific keywords or file path patterns, returning ranked file matches with path, size, and language metadata. Set mode=graph to search graph-node documents through the same index. Use when the target is a file path, filename, or file-content keyword rather than a code symbol. Set mode=graph to search indexed graph-node documents. Do NOT use for browsing all files without a query (use list_files), for code snippet search (use search_code), or for exact regex line matching (use regex_search). This is read-only and searches the local Tantivy index only.

Inputs: query (required), mode, limit, offset. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

search_memoryOpen Kioku Search MemoryA
Read-onlyIdempotent

Search the append-only repository memory store for previously recorded facts by keyword and entity match. Returns fact text, source, confidence level, and timestamp for each matching entry. Use to retrieve stored repository-scoped memory facts by keyword, entity, or text match from the local .ok SQLite store. Returns fact text, source, confidence, timestamp, and associated entities for each match. Do NOT use for current source code search (use search_code or hybrid_search) or for live index data (use the search and symbol tools). Use remember_fact to write new entries. This is read-only.

Inputs: query (required), limit. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

search_symbolsOpen Kioku Search SymbolsA
Read-onlyIdempotent

Search indexed code symbols (functions, classes, structs, traits, interfaces) by name using fuzzy matching. Returns ranked candidates with symbol name, kind, file path, and line range. Use when an agent has an approximate or partial symbol name and needs fuzzy-ranked candidates from the indexed symbol table. Do NOT use for exact substring inventory (use list_symbols), retrieving a symbol's full body (use get_definition), or comprehensive symbol context with docs (use get_symbol_context). This is read-only and searches the local index only.

Inputs: limit, query, offset. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

summarize_architectureOpen Kioku Summarize ArchitectureA
Read-onlyIdempotent

Return a structured summary of the codebase architecture, including layer constraints and violation checks. Use for a structured architecture overview with layer constraints and violation checks. Prefer explain_flow for a narrative and architecture_policy_explain for file-level evidence. This is read-only.

Inputs: no named parameters. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

validate_patchOpen Kioku Validate PatchA
Read-onlyIdempotent

Validate a proposed patch plan against architecture boundaries, symbol references, and import constraints. Returns boundary violations, broken reference warnings, and policy conflicts without modifying any files. Use to check a proposed patch plan against architecture boundaries, symbol references, and import constraints before applying it. Returns boundary violations, broken reference warnings, and policy conflicts. Do NOT use after real edits have been made (use verify_change or verify_change_contract instead) or for full safety review (use review_patch). This is read-only and checks against the local index and policy rules only.

Inputs: task (required). Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

verify_changeOpen Kioku Verify ChangeA

Verify an actual unified diff or set of changed files against a saved PlanReport, checking boundary constraints, expected file coverage, API surface stability, and dependency policy. Optionally executes configured validation commands and persists timestamped attestation records. Use after code edits to compare an actual unified diff or changed file list against a PlanReport produced by plan_change. When run_commands=true, executes shell commands listed in the plan's validation section (test runners, linters) on the local machine. When write_attestation=true, persists timestamped pass/fail records under .ok/contracts/validation/. Do NOT use for pre-edit planning (use plan_change), contract-based verification (use verify_change_contract), or boundary-only checks (use validate_patch). Side effects are conditional on boolean flags; with all flags false the tool is read-only.

Inputs: diff, plan, plan_json, since_plan, +7 more. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

verify_change_contractOpen Kioku Verify Change ContractA

Verify changed files or a diff against a stored or inline change contract. Stored contract ids append verification records to .ok/contracts. Use after edits to verify a diff against a stored or inline change contract. Stored contract ids append verification records under .ok/contracts, and command execution is opt-in via run_commands.

Inputs: diff, format, contract, since_plan, +10 more. Returns: The MCP structuredContent object returned by this Open Kioku tool. Most tools e…

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 42 tools

    Disambiguation4/5

    Most tools have distinct purposes with detailed descriptions including 'use this not that' guidance. However, with 42 tools, there is inherent overlap in categories like search and context building, which could still cause misselection despite clear documentation.

    Naming Consistency4/5

    Tool names consistently use underscores and mostly follow a verb_noun pattern (e.g., list_files, search_code, explain_symbol). Some noun-verb combinations (e.g., architecture_boundaries) still convey clear meaning, but the pattern is not perfectly uniform.

    Tool Count3/5

    42 tools is well above the typical 15-tool threshold for 'heavy' sets. While the server covers a broad domain (architecture, search, analysis, change management), many tools are granular and could be consolidated, making the count feel excessive.

    Completeness4/5

    The tool surface covers indexing, search, symbols, dependencies, architecture policy, context building, change planning, verification, and memory. Notable gaps include the absence of an apply_patch tool and limited execution capabilities, but core workflows are well-covered.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent codebase knowledge layer for AI agents. Pre-digests codebases into structured knowledge (symbols, dependency graphs, co-change patterns, architectural decisions) and serves via MCP. 28 languages, 14 tools, ~85% token reduction.
      22 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local-first codebase intelligence layer for AI coding agents, providing a persistent, queryable model of a repository via an MCP server and CLI to enable structure queries instead of reading many files.
      1
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Local-first code intelligence for AI coding assistants: MCP tools, symbol graph search, impact analysis, and auto-index watch for Cursor, Claude Code, and Codex.
      62
      2
      Business Source 1.1