Open Kioku

Home › Docs › Claude Code

Claude Code + Open Kioku

Give Claude Code something to read before it edits.

Open Kioku runs as a local MCP server. Claude Code asks it what a task touches, plans inside a declared boundary, and has the finished diff checked against that plan. Nothing leaves your machine.

Setup

Install, connect, ask for a plan.

Indexing time depends on the size of the repository; a few thousand files take seconds. Everything is stored under the repository's own .ok/ directory.

  • cargo install open-kioku-cli, or cargo binstall for the prebuilt binary.
  • Binaries with checksums, an SBOM and provenance on GitHub releases ↗.
  • The server is read-only by default: source edits remain in Claude Code's own workflow.
  1. Install Open Kioku

    The npm package pulls the native binary for macOS, Linux or Windows.

    npm install -g open-kioku
  2. Connect Claude Code

    One command indexes the repository, writes a repository-scoped .mcp.json and managed guidance, and checks that the local server answers. Run it without --apply to preview; nothing is written.

    ok setup agent claude --repo . --apply

    Or print the server entry and paste it into your Claude Code MCP settings:

    ok mcp install claude --repo .
    .mcp.json
    {
      "mcpServers": {
        "open-kioku": {
          "command": "ok",
          "args": ["mcp", "serve", "--repo", "/absolute/path/to/repo", "--read-only"]
        }
      }
    }
  3. Tell the agent to use it

    Add this to CLAUDE.md. The setup command writes managed guidance of its own; this is the short form.

    CLAUDE.md
    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.
  4. Turn on the hooks

    With the hooks, a boundary is planned from each prompt, a secret-like path is refused, and after an edit the agent is told which calls elsewhere no longer fit what it changed. The Claude Code plugin installs them for you.

    ok gate install claude --apply
What Claude Code can ask

Sixteen tools, each answering one question.

These are the ones an edit usually needs. Every tool runs against the local index and says what it could not find.

ToolWhat it answers
plan_changeAn edit plan with primary context, impact candidates, validation targets and the edit boundary.
verify_changeThe finished change checked against the plan's boundary.
build_context_packThe files, symbols and tests for one task, with confidence and caveats.
search_codeRanked code search with paths, line ranges and confidence.
get_definitionWhere a symbol is defined, from the local symbol index.
get_referencesWhere a symbol is used, from indexed relationship edges.
impact_analysisWhat a change to a file or symbol reaches, proven edges apart from possible ones.
find_tests_for_changeThe tests that cover what is about to change.
repo_statusIndex health, coverage by language, and what was skipped and why.

Measured every night on four real repositories: on a TypeScript repository of about nine hundred files, the right file is in the top five about four times in five. The numbers ↗ · All sixteen tools ↗

Other agents

The same server, a different client.