Gemini CLI + Open Kioku MCP

Give Gemini CLI an evidence layer before it edits your codebase

Connect Open Kioku as a local MCP server so Gemini CLI shows its evidence before it edits — files, streams, confidence, caveats — declares an edit boundary in a plan, and has its diff verified against that plan. Open Kioku does not upload source.

Start setup ← Back to openkioku.com

4 stepsinstall, index, connect MCP, paste the prompt

0 cloudno embeddings API, no hosted index for Open Kioku

read-onlysource edits stay in your normal editor

Step-by-Step Guide

Four steps from zero to evidence-backed edits.

Install the CLI, index your repo, wire up MCP, and paste the prompt that unlocks Gemini's plan-before-edit workflow. Indexing time depends on repo size.

1
Install Open Kioku

Install the Open Kioku CLI globally. The npm wrapper pulls the native binary for your OS — macOS, Linux, or Windows.
terminal
```
$ npm install -g open-kioku
```
Other channels: cargo install open-kioku-cli or cargo binstall open-kioku-cli from crates.io; binaries with checksums, an SBOM, and provenance on GitHub releases.
2
Index your repository

Navigate to your project root and run ok index . to build a local SQLite + Tantivy index. This scans files, parses symbols, resolves imports, maps test coverage, and builds a dependency graph — all on your machine.
terminal
```
$ cd /path/to/your/repo
$ ok index .
[ok] scan → parse → occurrences → store → graph → search → complete
[ok] indexed files, symbols, imports, occurrences, and tests
local indexes: .ok/index.sqlite + .ok/search/tantivy
```
3
Connect MCP to Gemini CLI

Run the one-liner below to generate the MCP config for Gemini CLI. Then paste the JSON block into your ~/.gemini/settings.json file.
terminal
```
$ ok mcp install gemini --repo .
```
ok setup agent --apply is wired for Claude Code and Cursor today; for Gemini CLI the manual entry below is the supported path.
~/.gemini/settings.json
```
{
  "mcpServers": {
    "open-kioku": {
      "command": "ok",
      "args": [
        "mcp",
        "serve",
        "--repo",
        "/absolute/path/to/repo",
        "--read-only"
      ],
      "trust": false
    }
  }
}
```
Replace /absolute/path/to/repo with the actual path to the repository you indexed in Step 2.

Paste the golden prompt into Gemini CLI

Start Gemini CLI and paste this prompt. It instructs Gemini to use Open Kioku's evidence tools before making any edits — building a plan from indexed facts, not guesses.

Golden Agent 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.

What You Get

MCP tools available to Gemini CLI after setup.

Once connected, Gemini CLI can call these tools over MCP stdio. Every Open Kioku tool reads from the local index and does not upload source.

What to expect: on a Java repository of about ten thousand files the right file is in the top five about half the time and in the context pack about two thirds of the time; 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 retrieval floor before exact lookups and the plan → verify loop; it is re-measured nightly against frozen baselines. Numbers and method.

plan_change

Build an evidence-backed edit plan with primary context, impact candidates, validation targets, and boundary policies.

verify_change

After editing, verify that changes stayed inside the planned boundary. Catch scope creep before the PR.

search_code

BM25-ranked full-text search across the indexed codebase. Returns file paths, line ranges, and confidence scores.

impact_analysis

Trace callers, dependents, and affected modules using the local dependency graph. Know the blast radius before editing.

get_definition

Jump to the definition of any symbol — functions, types, constants — resolved from the symbol index.

get_references

Find every usage of a symbol across the codebase. Graph-backed, not text-matched.

find_tests_for_change

Identify which tests cover the files and symbols you're about to change. Run the right tests first.

repo_status

Check index health, file counts, symbol counts, and last-indexed time. Confirm the index is ready.

build_context_pack

Assemble a focused context window with exactly the files and symbols the agent needs for a specific task.

Safety

Open Kioku keeps its index local.

Open Kioku is designed for teams and codebases that cannot be uploaded to a hosted index. Every tool reads from a local SQLite + Tantivy index stored in your repo's .ok/ directory.

No hosted index

Metadata stays under .ok/ in your repo. There is no hosted search service to provision or trust.

No embeddings API

BM25 search, symbols, and graph operations work locally without uploading code to a model provider.

Source edits stay local

Source edits stay in your normal editor; command execution and model downloads are policy-gated, and network denial fails closed.

Back to openkioku.com