Find the file you only half-remember: hands-on with Kensaku, local search with OCR and MCP

Kensaku (yjid/kensaku, MIT, 480 GitHub stars) is a free, local-first file launcher for Windows, macOS and Linux that searches file names, text inside documents, and text inside screenshots with OCR — nothing leaves your machine. This guide installs the v1.0.11 release and its command-line companion, runs the first scan, searches the way you remember things, and gives an AI agent the same index over MCP, read-only by default.

• Who: Kensaku, by yjid on GitHub. A Rust/Tauri desktop app — a file launcher with full-text, semantic and OCR search, plus a command-line companion and MCP access for AI agents. Licence: MIT.
• What: Searches names, text inside documents and code, text inside images with OCR, and meaning (“the PDF about indexing”), from a launcher summoned with Alt+Space. No account, no telemetry, no cloud search; the index stays in your OS config directory.
• When: Repository created 24 October 2026. Latest release v1.0.11 published 30 October 2026. At research time on 1 November 2026: 480 GitHub stars.
• Speed: Project-measured on Linux (8 vCPU, SSD) against a 100,000-file folder: name search 1.3 ms on average; first index of 101,101 files took 184 s at a 183 MB peak; re-index with nothing changed took 0.56 s; names and metadata for 100,000 files used about 12 MB of memory.
• Needs: Windows, macOS (Apple silicon and Intel) or Linux. Builds are not yet code-signed, so expect a first-run warning. The first run chooses watched folders and exclusions and optionally downloads OCR and model packs; search works while the first scan runs.
• Agent access: MCP over stdio (kensaku-cli mcp), a CLI, and loopback HTTP (kensaku-cli serve). Read-only by default; the only write tool, reindex, is hidden and disabled unless explicitly enabled.

Why this matters now

You rarely remember a filename. You remember what was in the file: the PDF about database indexing saved as notes-final-2.pdf, the log line from the failed deploy, the screenshot with the CUDA error that has no useful name at all. The tools most people reach for stop at filenames. Kensaku’s pitch is that reading inside your files — locally, instantly, and for free — should be the default, not a paid tier.

The project’s own comparison makes the claim concrete. Everything, Listary and PowerToys Run all do millisecond filename search; Kensaku claims the same, and adds full text inside PDF, DOCX, EPUB and more, text inside screenshots and images through OCR, search by meaning, natural-language time phrases such as “screenshots from last week”, and MCP access for AI agents. Spotlight and Raycast are macOS-only, and Alfred’s content search and AI are paid tiers. Kensaku is one app on three platforms, free and MIT-licensed. Treat the comparison as the project’s, not an independent test — and read the benchmark numbers below with the same care.

Those numbers were measured on a release build on Linux with 8 vCPUs and an SSD, against a 100,000-file folder, with the harnesses in the repository’s benchmark notes. The notes are candid about the limits: the comparison with plocate and fd is not a perfect match, because Kensaku’s search is fuzzy and runs inside a running app while the others start a new program per search; Spotlight, Everything and Listary have not been measured yet; and the numbers come from Linux, not macOS or Windows. On Windows, the 1.0.6 release notes give a smaller-scale picture: a 9 MB installer, and with a 24,500-file index loaded the app idling in the tray at about 20 MB of private memory, roughly 150 MB while actively browsing results, trimming back down when hidden. Every command below was checked against the repository’s README, usage guide and agent guide on 1 November 2026.

What you’ll need

• A Windows, macOS (Apple silicon or Intel) or Linux machine. Linux ships as an AppImage, a .deb and an .rpm, and is tested on Ubuntu 22.04 with X11; other Linux desktops are not yet verified.
• No account, no API key, no subscription. Kensaku has no telemetry and no cloud search; the index lives in your OS config directory, and you choose which folders are watched.
• A few minutes for the first scan. Indexing time depends on how much you point it at: the project’s benchmark folder of 101,101 files took 184 seconds on its Linux test machine. Search works while the first scan runs.
• Room for the optional packs: the default OCR model pack is about 6 MB and downloads on first run, and the optional higher-quality Indra OCR engine is about a 27 MB pack downloaded on demand. The semantic model is also acquired during setup.
• Patience with first-run warnings. The builds are not yet code-signed, so Windows SmartScreen and macOS Gatekeeper will both object the first time. That is expected for an independent app, not a sign of a problem — the README says so explicitly.

Step 1: Install the app and the command-line companion from the latest release

Download the bundle for your system from the project’s latest release page. Version 1.0.11, published 30 October 2026, ships these files:

Every release also ships a SHA256SUMS file so you can verify what you downloaded, and kensaku-cli as a separate binary — it is not bundled inside the installer. The CLI binaries in the same release are kensaku-cli-linux-x86_64, kensaku-cli-macos-aarch64, kensaku-cli-macos-universal and kensaku-cli-windows-x86_64.exe. Download the one for your platform and place it somewhere your shell finds it, on your PATH. Steps 5 and 6 use it; the desktop app works without it.

On the first launch, expect the unsigned-build warning. On Windows, on the SmartScreen prompt, click More info and then Run anyway. On macOS, open the app, then go to System Settings, Privacy & Security, and click Open Anyway. To build from source instead, the documented form is git clone followed by bun install and bun run tauri build, needing Rust (stable), Bun 1.1 or later, and your platform’s webview libraries; a Makefile covers make dev, make build, make test and make reset.

Step 2: Run the guided first setup and let the first scan finish

The first run is guided, and it ends with a Done summary before the main window opens. It covers: pick the folders to index (Home, Projects, Documents and Downloads are the suggested starting set), choose an exclusion preset — Developer, Creative or All-round — set preferences such as theme and the global shortcut, optionally download the OCR language data and the semantic model, and start the first scan. Later launches stay search-first: the snapshot loads, then a stat-only reconcile runs in the background.

Choose watched folders deliberately, because that choice is the privacy boundary. Hidden files and common build folders are skipped by default, and credential files such as .pem, .key and .pfx, along with sensitive paths such as .ssh, .gnupg, .aws and .env*, are excluded by default. The index itself contains file names and extracted text, so treat it as sensitive: it lives at ~/.config/kensaku/ on Linux, ~/Library/Application Support/kensaku/ on macOS and %APPDATA%\kensaku\ on Windows. Do not sync that directory to a shared location.

Press Alt+Space to summon the floating search window; the shortcut is configurable in Settings, and on Linux under Wayland, where desktops block global keys for apps, the documented workaround is to bind a key to kensaku --toggle in your desktop settings instead. The window hides on close or when it loses focus, stays out of the taskbar and dock, and keeps the index warm. If anything looks wrong, the /doctor command in the search box, and the Doctor panel in Settings, run on-demand checks covering config writability, database integrity, index size, watched roots, watcher health, model files and OCR. To start over completely, Settings, About, Reset everything deletes the index, database, models and config, then restarts.

Step 3: Search the way you remember it, not the way you filed it

Type anything. Plain words search names and content together, results update as you type, and there is no separate search page. Category chips — All, Files, Folders, Images, Docs, Code, Media and Recent — narrow by type, and Sort offers Best match, Newest, Oldest, Largest and Name. Space previews the selected file, Enter opens it, Shift+Enter shows it in its folder, Cmd/Ctrl+C copies the selected path, Cmd/Ctrl+I shows details, and Esc clears the search, then hides the window. An empty search box shows pinned files, recent files, saved searches and suggested queries; pin a result from the home rows, and save the current query with the bookmark button next to Sort.

When you want precision, the query language is there, and filters never replace the text — they narrow the set:

type:pdf invoice
ext:md in:"~/Notes"       modified:7d
size:>10mb                path:"client/2026"
name:resume               content:"timeout"
re:"fn \w+_test"          -draft
mode:exhaustive

The full set covers type:, ext:, in: to scope to a folder, path: substring matches, modified: windows such as 1h, 7d and 7d..30d, size: ranges, lang:, name: and content: only-matches, re: regular expressions, -term exclusions, exact phrases in quotes, and mode:exhaustive for every match, path-sorted. Type @ to pick a folder from the index and / for the command menu: filters, /dupes, /reindex, /doctor and /settings. Ranking fuses fuzzy filename, BM25 content and static-vector semantic tiers with reciprocal rank fusion, plus name bonuses, recency, frecency from files you open, and a bounded depth penalty; semantic-only hits below a cosine floor are dropped, so a keyword query does not return vaguely related documents.

Plain language works too, compiled locally without a model, and every inference appears as a removable chip above the results:

Time words understood include today, yesterday, last week, last month and last year; “big” means over 100 MB and “tiny” means under 1 MB. Aliases live in Settings, Search, Aliases — the defaults map resume to cv, invoice to receipt, bill and screenshot to capture.

Step 4: Find text inside screenshots with OCR

This is the test that separates Kensaku from a filename launcher. Take a screenshot you know contains an error message, or any image with text in it, make sure its folder is watched, and search for a distinctive word from the text in the image. Kensaku reads the pixels: text inside screenshots and images is extracted with PP-OCRv6 by default, on a bundled ONNX Runtime, with no system install needed and a roughly 6 MB model pack downloaded on first run. The optional Indra engine adds deskew and multi-script recognition at higher quality, as a roughly 27 MB pack downloaded on demand, and classic Tesseract is also selectable. Intel Macs fall back to Tesseract.

Try it with the error you actually lost: search the exact error text, for example content:"CUDA out of memory", and the image should surface with the matching words highlighted. Then try the plain-language form — screenshots from last week — and narrow with type:image if the results are noisy. Indexing reads each file once and feeds both the name and text indexes in a single pass, in bounded batches, so memory stays flat on large folders; unchanged files are not re-read, and renames are tracked by device and inode, so moves do not duplicate entries.

Know the edges before you rely on it. JPEG 2000, fax and JBIG2 scans are not decoded yet; thumbnails cover image files only, while documents and code show type icons; and visual search is a beta model download that is not part of search results yet. Documents covered for full text are PDF, DOCX, PPTX, XLSX, EPUB, ODT, ODS, ODP, RTF, plain text, code and logs, including CJK text, and malformed files are skipped after an 8-second timeout. If a screenshot does not surface, check the OCR status in Settings, Search, confirm the folder is watched, and run /doctor before assuming the text was never extracted.

Step 5: Search from the terminal with kensaku-cli

The same index is available from the shell, which lets scripts and one-off queries use it without opening the window. The documented commands, from the project’s agent guide, are:

kensaku-cli search "docker error"
kensaku-cli search "invoice" --ext pdf --since 30d
kensaku-cli search "resume" --json
kensaku-cli state
kensaku-cli search "type:pdf invoice" --path ~/Documents
kensaku-cli search 're:"fn \w+"' --ext rs --since 30d
kensaku-cli search "config" --exhaustive --json
kensaku-cli state --json

Default output is path, tab, score, tab, snippet; --json prints the full response. Exit codes are 0 for success, 2 for usage errors, and 3 for no index — launch Kensaku once if you get exit code 3, because the CLI never creates an index on its own. The search command accepts the full query language from Step 3, plus --path, --ext, --since, --limit and --exhaustive flags. For repeated queries, prefer the MCP session in Step 6: a one-shot CLI call pays the metadata load each time, while an MCP session loads it once.

Step 6: Give your AI agent the same index, read-only, over MCP

Point an MCP client at the CLI. The documented configuration, from the project’s README and agent guide, is:

{
  "mcpServers": {
    "kensaku": { "command": "kensaku-cli", "args": ["mcp"] }
  }
}

Use the absolute path in command if kensaku-cli is not on your PATH. The protocol is JSON-RPC 2.0, newline-delimited, over stdin and stdout; only protocol messages are written to stdout and logs go to stderr. The easiest path is in the app: Settings, Agents, detects Claude Desktop and Claude Code and Cursor, and merges one config entry atomically, keeping a .bak backup. The CLI form is kensaku-cli connect <client> [--write].

The tools the agent gets are search, read_snippet (a capped window of text centred on the first match, never a whole large file), health_check (which returns ok: false with a reason for an unhealthy index, not a tool error), index_state, regex_search, and find_symbol (tree-sitter definitions for Rust, Python, JavaScript and TypeScript). Responses are budgeted in size, snippets are capped at 100 characters, and file content is returned as data, never as instructions. Search honours the watched folders and exclusions configured in the app, and .gitignore and .cursorignore are honoured by default, so the agent sees the same tree the developer does.

For clients that connect over HTTP instead of stdio, run kensaku-cli serve [--port 8765]. It serves MCP Streamable HTTP on POST /mcp, a read-only GET /health, GET /search?q=, and an SSE keepalive at GET /events. It listens on loopback only and requires a bearer token stored in <config>/http.token with 0600 permissions. The one write action, reindex, is hidden from the tool list and disabled by default; enabling it requires setting "mcp_allow_reindex": true in config and restarting the MCP client, and it is never enabled on the HTTP transport. If you want the agent confined to part of the disk, agent_scoped_roots in config restricts search results and snippet and symbol reads to those roots — out-of-scope requests are rejected, not silently trimmed. An optional local LLM can also power a query compiler and an /ask command with path-and-line citations (kensaku-cli ask "<question>"), off by default and never required.

What you built

A local search layer over the folders you actually work in. The desktop app gives you a launcher that finds files by what is inside them, including screenshots; the CLI gives you the same index from scripts and the shell; and MCP gives your coding agent the same index, read-only, with the same watched folders and exclusions you configured. Nothing in that chain needs an account or sends a query anywhere: the index, the OCR and the semantic vectors all run on your machine, and the HTTP surface binds to loopback with a token.

The habit that makes it pay off is the one from Step 3: stop reconstructing filenames and search for the phrase, the error, or the description you remember. Pin the files you reopen, save the queries you repeat, and let recency and frecency do the ranking work. When the agent needs a file, point it at Kensaku first instead of letting it guess paths — the snippet it gets back carries the path, the score, the match type and a capped snippet, which is usually enough to act on without opening the file at all.

Honest limitations

• Unsigned builds, no auto-updater yet. Expect SmartScreen and Gatekeeper warnings on first install, and check for updates yourself: the auto-updater is not wired up yet, though a check-for-updates button exists in the app.
• Windows gets the most real-world testing. macOS and Linux builds ship from CI and would benefit from more hands on them, in the project’s own words; Linux is tested on Ubuntu 22.04 with X11 and other desktops are not yet verified. Wayland users should use the --toggle shortcut binding instead of relying on the global key.
• Benchmarks are the project’s, on Linux. The headline 1.3 ms figure is a warm, in-memory name search on one test machine and folder; Spotlight, Everything and Listary have not been measured, and the plocate/fd comparison is not like-for-like. Your first index will take as long as your folders take.
• OCR and visual search have edges. JPEG 2000, fax and JBIG2 scans are not decoded yet, thumbnails cover images only, and visual search is a beta download that is not part of search results yet. Intel Macs fall back to Tesseract for OCR.
• The index is sensitive, and young software moves. It contains file names and extracted text, so keep the config directory off shared sync. The project is days old — created 24 October 2026, at v1.0.11 on 30 October — with 240+ Rust tests on every push, but app search and launch, internet quick search and an answers layer over the index are still being shaped in public discussions rather than shipped.
• Agents see what you configured, nothing more. No index means an error, not a fresh one; reindex stays off unless you enable it; and the optional local LLM is off by default. If the agent cannot find a file, check watched folders and exclusions first — the agent surface deliberately cannot change them.