reference

a macOS and windows app that indexes your files locally and lets you search them semantically. no cloud, no api calls, nothing leaves your machine.

the problem

existing ai-powered launchers (raycast's quick ai, spotlight, etc.) don't actually know anything about your files. ask raycast "how did i implement rate limiting here" and it has no index of your activity, it just tells you how to check manually (open file > open recent, run git status, etc.). that's a cloud llm wrapper with no real memory of your machine, not a tool that retrieves anything.

this app is the real version: an actual local index of your files, kept current automatically, queryable with real semantic search, answered with citations back to the source file.

core idea

• you pick which folders to index (opt in, never automatic): type a path into the folder field, press tab to autocomplete/step into a folder, press enter to start watching it
• a background daemon watches those folders in real time and embeds new/changed files as they happen
• search combines fast fuzzy filename matching with gpu-accelerated semantic search
• question-shaped queries get a synthesized answer with clickable source citations
• everything runs locally, embeddings, storage, and search never touch the network

why not just use raycast / spotlight / cloud rag tools

• raycast is mac only and its "ai" features are thin wrappers around cloud apis, not a real local index
• cloud rag tools require your files to leave the machine, a non starter for code and private notes
• this app runs on macOS (metal-accelerated) and windows (cuda-accelerated), not a mac-only tool

tech stack

core features

• folder-level opt in indexing
• real-time file watching (background daemon, not manual re-scan)
• local gpu-accelerated embeddings (cuda / metal)
• hybrid search: fast fuzzy filename match + semantic match
• code-aware chunking: search and cite exact functions/classes, not just whole files
• answer synthesis with source citations, linking back to the actual file, code citations are syntax-highlighted with a high-contrast palette tuned for the app's dark theme
• a "send to agent" button on every result and citation: copies a formatted query and code/line-range context to the clipboard, so a human who found the right chunk can hand it straight to whatever coding agent they're using
• pick which app opens a result: right-click a result/citation for an "open with" popup, or use the toolbar button to set the default a plain click uses. lists whatever's actually installed (finder, cursor, zed, vs code, windsurf, xcode, sublime text, terminal, any jetbrains ide) with real icons extracted from each app's own bundle, no hardcoded logos, no dependency on any one editor being installed
• an mcp server exposing four read-only tools over the same index, for agents to query directly mid-task: search for natural-language lookup (with an exclude_folder param for cross-repo recall), explain for citation synthesis regardless of query phrasing, find_similar for finding near-duplicate chunks given one already found, check_doc_drift for flagging a doc chunk that no longer scores close to the code it describes

explicitly out of scope

• cloud sync/backup of the index (undermines the whole privacy pitch)
• general-purpose chatbot mode (scope creep away from "search my stuff")
• auto-indexing everything by default (erodes trust, opt in only)
• a persistent "nothing leaves this machine" status indicator in the main ui (redundant clutter, anyone who installed a local-only tool already knows the deal)

later / stretch ideas

• multi-machine indexing (search across a mac and a pc you own)
• structured fact extraction (claims with provenance, not just chunk retrieval)
• plugin/extension model for new source types (notion, browser history, calendar)
• natural-language file actions (rename, move)
• directly launching a coding agent with context, not just clipboard hand-off

current status

watch, embed, store, and hybrid search all work end to end through the tauri app, backed by one local index (~/.reference/). code is chunked at function/class granularity for rust, python, typescript, javascript, go, java, c, c++, ruby, and swift (prose and other languages still index as one whole-file chunk). answer synthesis cites exact chunks, syntax-highlighted in the app, with a send-to-agent clipboard button on every result.

everything lives under ~/.reference/: watched_folders.json is the plain-text list of folders you've added via the app, index/ is the actual lancedb table (paths, chunks, and embeddings). removing a folder from the app doesn't just stop watching it, it purges every already-indexed row for that folder from index/ too, so nothing stale is left searchable after you remove it.

there's a menu bar tray icon (the pixelated & mark) alongside the dock icon, click it to show/focus the main window. closing the window hides it instead of quitting the app, specifically so the tray icon has a window to bring back; quit fully via the dock icon or cmd+q.

adding a folder to watch

open the folder picker (⌘7), type or paste a path, then:

• tab — autocomplete the path / step into the highlighted folder
• enter — start watching the current path

building from source

git clone <this repo>
cd reference/app
pnpm install
pnpm tauri dev

requires rust and pnpm installed. no python dependency anywhere in the pipeline. on macOS this builds with metal (gpu) support automatically, no extra flags needed.

building on windows (cuda)

windows builds with cuda support automatically too (app/src-tauri/tauri.windows.conf.json turns on the cuda feature), but getting a working nvcc/msvc toolchain in place takes a few one-time steps on a fresh machine:

• rust via rustup
• visual studio build tools 2022 with the desktop development with c++ workload (the plain vs installer default doesn't include it — use the installer's "modify" flow and check that workload explicitly)
• protoc (needed by lance-encoding's build script, unrelated to cuda)
• node.js lts + pnpm, then run pnpm approve-builds --all once after the first pnpm install (pnpm's build-script approval gate otherwise blocks esbuild's postinstall)
• the nvidia cuda toolkit — verified working with cuda 13.3 and a driver reporting the same cuda version via nvidia-smi; matching (or older than) whatever your driver supports should work
• before building, import msvc's environment into your shell (vcvars64.bat, under VC\Auxiliary\Build in your VS install) so cl.exe/link.exe are on PATH, then set two things nvcc/the linker need on top of that:
  • NVCC_APPEND_FLAGS=-Xcompiler /Zc:preprocessor — without this, candle-kernels' build script fails compiling reduce.cu with an msvc preprocessor error on newer cuda toolkits
  • append the cuda toolkit's lib\x64 directory to %LIB% — without this, the final link fails with cannot open input file 'cuda.lib'

with those in place, pnpm tauri dev (or pnpm tauri build) from app/ builds and runs like any other rust/tauri project. a missing or non-nvidia gpu at runtime falls back to cpu automatically, it doesn't crash the app.

using the mcp server with an agent

build it once:

cargo build -p reference-mcp

then register it with claude code:

claude mcp add --scope local reference-mcp -- ${CLAUDE_PROJECT_DIR:-.}/target/debug/reference-mcp

or, if you're using the installed app instead of a source build, the reference-mcp binary ships inside the app bundle at Contents/MacOS/reference-mcp on macOS:

claude mcp add --scope user reference-mcp -- /Applications/reference.app/Contents/MacOS/reference-mcp

on windows, build it the same way (cargo build -p reference-mcp, no extra flags needed — it picks up cuda automatically) and point at target\debug\reference-mcp.exe, or the copy that ships alongside the installed app's own .exe.

it only searches folders you've already added to the app. exposes four tools: search, explain, find_similar, and check_doc_drift.

license

elastic license 2.0 (LICENSE). free to use, copy, modify, and distribute. can't offer it to third parties as a hosted or managed service, and can't circumvent license key functionality.