Codex + Open Kioku Setup Guide

Give Codex an evidence layer before it edits your codebase

Open Kioku is a local MCP server Codex reads before it edits: it shows its evidence — 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 View on GitHub
Step 1

Install Open Kioku

Install the CLI globally. The npm wrapper automatically downloads the correct native binary (Rust) for macOS, Linux, or Windows.

terminal
$ npm install -g open-kioku

Requires Node.js v18 or later. The native binary handles indexing and search.

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.

Step 2

Index your repository

Navigate to your repo root and run the index command. Open Kioku scans files, extracts symbols, builds a dependency graph, and creates local search indexes.

terminal — your repo root
$ ok index .

Indexes are stored locally under .ok/ in your repo. Open Kioku does not upload source.

Step 3

Connect Codex to Open Kioku

Use the verified manual MCP config path. Plugin metadata is included in the repository for Codex installations that support Git-scoped plugin manifests.

  1. 3a

    Manual MCP server (Verified)

    Configure the MCP stdio transport directly with a repo path pinned to the index you built in Step 2.

    Verified
    manual MCP
    $ ok mcp install codex --repo .

    This prints the Codex TOML config for the current repository. ok setup agent --apply is wired for Claude Code and Cursor today; for Codex the manual entry below is the supported path.

then
  1. 3b

    Paste the generated TOML

    The command above prints this shape. Replace the repo path with the absolute path to the repository you indexed.

    codex MCP config
    [mcp_servers.open-kioku]
command = "ok"
args = ["mcp", "serve", "--repo", "/absolute/path/to/repo", "--read-only"]
enabled = true
Step 4

Paste the golden prompt

Add this system prompt to your Codex configuration or paste it at the start of a session. It tells Codex to always gather evidence before making edits.

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

Tools Codex can call after setup

Once connected, these MCP tools are available to Codex in every session. All tools are read-only by default and operate on local indexes.

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 affected files, impact candidates, and validation targets before any code is touched.

verify_change

After editing, verify that changes stayed within the planned boundary and flag unexpected side effects.

search_code

BM25-ranked code search with file ranges, confidence scores, and snippet context. No embeddings API needed.

impact_analysis

Trace which files and symbols are affected by a proposed change using the local dependency graph.

get_definition

Jump to the exact definition of a symbol — function, class, type, or variable — across the indexed repo.

get_references

Find every usage and call site of a symbol using persisted graph edges, not text matching.

find_tests_for_change

Identify which test files and functions are relevant to a set of changed files before running the suite.

repo_status

Check index health, file counts, symbol coverage, and whether the repo is ready for MCP queries.

build_context_pack

Assemble a focused context bundle of code, symbols, and tests for a specific task or file set.

Security

Your code stays local

Open Kioku is designed for codebases people cannot upload to a hosted index. No hosted search service or embeddings API is required.

  • ✓Local SQLite + Tantivy indexes
  • ✓MCP stdio transport only
  • ✓No source upload by Open Kioku
  • ✓Read-only by default
  • ✓Source edits stay in your normal editor
  • ✓No embeddings API required

Back to openkioku.com