Local-first context lineage engine. Indexes a git repo's commits and diffs, then serves "how was X done before?" queries to Claude Code (or any MCP client) via a local stdio server.

Named after Ohara, the island in One Piece whose Tree of Knowledge held 5,000 years of accumulated history — and whose archaeologists devoted their lives to reading it.

Status: v0.13.0. Two MCP tools shipped (find_pattern, explain_change), served by a single shared daemon across all your editor sessions:

• find_pattern — "how was X done before?" (semantic search over git history with a five-lane retrieval pipeline + cross-encoder rerank).
• explain_change — "why does THIS code look the way it does?" Blame-backed exact provenance (hits[]) plus contextual commit neighbours (_meta.explain.related_commits[]).

Recent highlights:

• v0.13.0 — single-writer storage pool (plan-32): all index writes funnel through one connection, fully eliminating the parallel-writer commit drops and the busy-handler contention (storage 458%→39% on a CoreML rebuild).
• v0.12.0 — indexing fixes (plan-31): parallel-writer commit drops reduced (raised busy_timeout + failures now surface and exit non-zero), and the CoreML embedder coalesces per-commit batches to end ~55% GPU padding waste.
• v0.11.0 — fixed-shape CoreML embedder (plan-30): ohara index --embed-provider coreml runs on the Apple GPU+Neural Engine at ~3× CPU embed throughput; no rebuild needed when switching providers.
• v0.10.0 — daemon consolidation (plan-29): N MCP sessions share one engine process; ohara-mcp boots without loading models; the reranker unloads after idle; the plugin auto-tracks the released binary version.
• v0.9.0 — quantized BGE-small becomes the default embedder.
• v0.8.x — ohara plan + .oharaignore, contextual BM25 lane, chunk-embed cache, parallel indexer (plans 25–28).
• v0.7.x — eval harness, perf tracing, memory-efficient indexing, ohara serve daemon + multi-repo support (plans 10–16).

History: v0.1 = Plan 1 foundation + find_pattern; v0.2 = ohara init post-commit hook + --incremental fast path; v0.3 = three-lane retrieval (vector KNN + FTS5 BM25 hunk-text + FTS5 BM25 symbol-name) → RRF → cross-encoder rerank (bge-reranker-base) → recency multiplier

• AST sibling-merge chunking; v0.4 = Java 17/21 and Kotlin 1.9/2.0 language support (sealed types, records, data classes, annotations preserved in source_text for Spring-friendly retrieval); v0.5 = explain_change; v0.5.1 = progress bar, abort-resume hardening, and ohara update. The full per-release breakdown lives in the changelog.

Languages: Rust, TypeScript, JavaScript, Python, Java, Kotlin. Class- and method-level annotations (@RestController, @Service, @Component, @SpringBootApplication, etc.) stay inside source_text, so embeddings and BM25 pick up Spring-style markers without any new query syntax.

Pre-built binaries for macOS and Linux are published on each release:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/vss96/ohara/releases/latest/download/ohara-cli-installer.sh | sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/vss96/ohara/releases/latest/download/ohara-mcp-installer.sh | sh

Or grab a tarball directly from the releases page. The released matrix is:

• macOS: Apple Silicon only (aarch64-apple-darwin).
• Linux: x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu.
• Windows: not supported (use WSL).

Intel Macs and Windows users build from source — see Build from source below.

Linux glibc baseline: released binaries link against the prebuilt onnxruntime shipped with ort 2.0+ and require glibc ≥2.38 (Ubuntu 24.04+, Debian 13+, RHEL/Rocky 10+, Fedora 39+). On older distros (Ubuntu 22.04, Debian 12, RHEL 9), build from source — see Build from source below.

Intel Macs (x86_64-apple-darwin): dropped from the released matrix in v0.9.0 because ort 2.0.0-rc.12 ships its CoreML-featured prebuilt as an Apple-Silicon-only xcframework. Build from source.

Self-update from the CLI:

ohara update              # install the latest release in place
ohara update --check      # just report whether a newer version exists

The cargo-dist installer also drops a standalone ohara-cli-update script alongside the binary; either works.

cargo build --release

Produces two binaries under target/release/:

• ohara — CLI for indexing and debugging
• ohara-mcp — MCP server (stdio) for Claude Code

Apple Silicon (v0.11+): the released macOS binary has CoreML support built in. Opt in per index pass:

ohara index --embed-provider coreml

This runs a fixed-shape fp32 BGE-small on the GPU+Neural Engine — ~3× the CPU embed throughput on an M4 Pro (see docs/perf/v0.11-coreml-fixed-shape.md). First use downloads the fp32 model (~130MB); each run pays a one-time ~30s CoreML compile. Indexes built with either provider share one vector space, so no rebuild is needed when switching.

Linux + NVIDIA: CUDA requires a source build:

cargo build --release --features cuda

then ohara index --embed-provider cuda. See ohara index for the full flag set. Source builds stay CPU-only by default.

fixtures/build_tiny.sh
cargo run -p ohara-cli -- index fixtures/tiny/repo
cargo run -p ohara-cli -- query --query "retry with backoff" fixtures/tiny/repo

The first run downloads the BGE-small embedding model (~80MB, one time). ohara query will auto-spawn a background daemon on first use to keep the embedder warm; pass --no-daemon to skip it, or see ohara daemon --help.

/plugin marketplace add vss96/ohara
/plugin install ohara@vss96
/reload-plugins

Registers the MCP server, ships two skills (ohara:lineage, ohara:indexing), and auto-downloads the binary on first use. Full details in the docs site.

ohara-mcp speaks stdio MCP, so any MCP-aware client picks it up with the same shape:

{
  "mcpServers": {
    "ohara": {
      "command": "/absolute/path/to/ohara-mcp",
      "args": [],
      "env": {}
    }
  }
}

Drop that block into the right config file:

• Claude Code / Claude Desktop (manual fallback): ~/.claude/claude_desktop_config.json, .mcp.json per-repo, or claude mcp add ohara <path>. Prefer the plugin above.
• Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-workspace).
• OpenAI Codex CLI: ~/.codex/config.toml with a [mcp_servers.ohara] block (TOML, not JSON).
• OpenCode: ~/.config/opencode/opencode.json or repo-root opencode.json under an mcp key.

Full config examples for each client live in the docs site.

The server reads the current working directory of the spawning client session as the repo to query. Run ohara index <repo> once to bootstrap, then keep the index fresh with the post-commit hook:

ohara init <repo>                   # installs .git/hooks/post-commit
ohara init <repo> --write-claude-md # also appends an "ohara" stanza to CLAUDE.md

The hook runs ohara index --incremental after every commit. It's safe to re-run ohara init (idempotent) and the hook fails closed if the ohara binary isn't on PATH (won't block your commits).

For large repos (Linux-class, 100k+ commits), run ohara plan first to print a directory commit-share hotmap and suggested .oharaignore patterns. Review the output, then re-run with ohara plan --write to apply the suggestions to .oharaignore at the repo root (this is also the only path that writes the file — the default is print-only). Use .oharaignore to drop mechanical noise (vendored deps, generated code, lockfiles). This is also where hardware acceleration pays off — ohara index --embed-provider coreml (Apple Silicon, ~3× embed throughput) or a --features cuda build (NVIDIA Linux).

Each ohara release records the embedder, chunker, and parser versions it used to build the index. After upgrading, run ohara status — the compatibility: line tells you whether the existing index is still usable as-is, needs a cheap refresh, or needs a full rebuild. The two recovery commands:

• ohara index --force — refreshes derived symbol/chunker rows when only those bumped. Commit + hunk + vector history is untouched.
• ohara index --rebuild --yes — drops the entire index and rebuilds from scratch. Required when the embedder model or vector dimension changed; KNN against a stale-vector index would otherwise return wrong results, and find_pattern (MCP) refuses to run until you rebuild.

Full design + the per-verdict table live in docs-book/src/architecture/indexing.md.

See docs/superpowers/specs/2026-04-30-ohara-context-engine-design.md for the v1 design and docs/superpowers/plans/ for implementation plans.