Skip to main content
Glama
ltspace

dowse

by ltspace
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

English | 简体中文 | 日本語 | 한국어 | Español | Italiano

The name comes from a dowsing rod.

Dowse searching the fictional Northstar workspace, with ranked project files on the left and a live brief preview on the right

Motivation

No Windows tool satisfies all three of the following at once:

  • Keep a persistent index of file contents, not just file names (Everything can scan contents on demand, but its instant index is centered on names and paths)

  • Recognize and index text inside images on ordinary Windows PCs without requiring a Copilot+ device

  • One hotkey to summon, full keyboard operation, no perceptible latency

The closest open-source implementation is sist2, but it targets Linux (on Windows it only runs via Docker), treats Chinese text as trigrams, and the project is no longer maintained. dowse is a Windows-native implementation built around these three points.

Related MCP server: cowork-semantic-search

Features

🔍 File name search

Instant, as you type

📄 Document content search

Plain text, Markdown, code, and document formats (PDF, Word, Excel, PowerPoint)

🖼️ Screenshot / image OCR

Text inside PNG/JPG/WebP/BMP images, fully offline (Windows.Media.Ocr)

🈶 Chinese word segmentation

jieba + BM25 ranking, not trigrams — plus automatic GBK encoding detection

⚡ Incremental indexing

File-watch during runtime, mtime/size reconciliation at startup

🤖 MCP server

Exposes local search to AI agents over stdio

🚀 NTFS fast path

MFT enumeration + USN Journal, admin-only, falls back transparently otherwise

dowse vs. the alternatives

dowse

Everything

Windows Search

sist2

File name search

✓

✓

✓

✓

Document content search

✓ (persistent index)

on-demand scan

depends on indexed locations and filters

✓

Screenshot / image OCR

✓

✗

device/version dependent

limited (optional Tesseract)

Proper Chinese segmentation

✓ (jieba)

—

limited

✗ (trigrams)

Fully local, no network

✓

✓

✓

✓

Global hotkey overlay

✓

✓

✓ (Win key)

✗ (web UI)

Windows-native

✓

✓

✓

✗ (Linux-first, Docker on Windows)

Chinese text handling

  • Word segmentation via jieba, ranking via BM25 (tantivy engine). No trigrams.

  • Automatic file encoding detection (chardetng). GBK-encoded files are decoded correctly before indexing — this matters because a large share of Chinese-language documents on Windows, especially older ones, are still saved in GBK rather than UTF-8, and a search tool that assumes UTF-8 will silently mis-index or garble them.

  • Multi-term queries default to AND semantics. Quoted phrase queries match on exact position. Inline operators narrow things down further: path:reports, mtime:>2026-01-01, size:>10mb, uppercase OR between groups, -term to exclude.

  • OCR runs on the Windows-native engine (Windows.Media.Ocr), fully offline. The zh-Hans language pack also covers mixed Chinese/English text, no extra configuration required.

Performance

Design targets; exceeding them is treated as a defect. "Measured" is a from-scratch benchmark of dowse 0.7.0 (i7-13700K / 24 logical cores / 64GB RAM, single machine, single session, 2026-07-12), reusing the byte-identical corpus from the v0.6.1 round-3 benchmark for direct comparability. Full raw output (index/search logs, JSON result files) is kept with the benchmark working directory, outside this repo.

Metric

Design target

Measured (v0.7.0, 2026-07-12)

Hotkey to window visible

< 50ms

not measured — CLI-only benchmark, no overlay-app instrumentation

Keystroke to results rendered

< 80ms

not measured — same

OCR, single image

~112ms / 1080p screenshot

~170ms isolated (480×200 synthetic image), unchanged from v0.6.1 — the OCR pipeline was not modified this release. Sub-30ms readings on immediate repeat runs of the same image reflect OS-level recognition caching, not real recognition, and are excluded here. Not real 1080p screenshots

Resident memory

< 150MB idle

not measured (idle); peak working set during full-corpus indexing was ~327MB — a different metric, not a regression against the idle target

Installer size

< 50MB (revised 2026-07 — the original 15MB target predates the bundled CLI sidecar)

14.98MB (dowse-app_0.9.0_x64-setup.exe, published release)

Full-text index build, 10,000 files / 437MB

seconds (planned filename-only fast path)

10.0–10.6s — current full-content dowse index, not the planned filename-only MFT path

Full-text index build + OCR, 15,100 files (incl. 5,100 images)

—

~46.6s first pass, all 5,100/5,100 images OCR'd in that same pass — no pending, no second pass needed

Search latency, P50 (5 required categories)

—

30.7–161.1ms across single word / Chinese phrase / English phrase / multi-word AND / zero-result, on a 15,100-document index

Search latency, P95

—

39.1–172.3ms, same 5 categories

ext: filter query latency

—

P50 155.6ms, same band as the non-zero-result query categories

Index size ÷ corpus size

—

0.36 (text-only), down from 0.54 in the v0.6.1 round

Full-corpus rows measured on the same 10,000-file / 437.66MB text corpus plus 5,100 synthetic 480×200 OCR images (89.8MB) used for the v0.6.1 round-3 numbers above — byte-identical, reused directly rather than regenerated. Indexing is roughly 2x faster and the on-disk text index roughly a third smaller than v0.6.1; both track the new tokenizer (lowercase normalization, alphanumeric-boundary splitting of Latin words) producing a leaner term dictionary. The zero-result query dropped from 135ms (v0.6.1) to a startup-noise-level 31ms, consistent with less index to scan before concluding a term is absent. OCR recognition speed is unchanged this release, since the pipeline was not touched: single-image recognition stays around 170ms, and the sub-30ms readings on repeated identical images are OS-level caching artifacts, not real recognition. The full-corpus text-plus-OCR pass got faster (83s to 46.6s) from the quicker tokenizer and write path, not from faster recognition.

Quick start

Download — grab the installer from the latest release (dowse-app_*_x64-setup.exe), run it, then `Alt+`` to summon.

The installer is unsigned, so Windows SmartScreen will flag it on first run. To proceed, click More info and then Run anyway. A code-signing certificate is a recurring cost that is hard to justify for an independent project; it may be reconsidered for a future release.

Install the CLI — the library and command-line tool ship as one dowse package:

cargo install dowse                 # once published to crates.io
cargo install --path crates/dowse   # from a local checkout

Build from source:

git clone https://github.com/ltspace/dowse && cd dowse

# CLI
cargo run -p dowse -- index D:\docs      # build the index
cargo run -p dowse -- search 限流         # search
cargo run -p dowse -- search "精确短语"   # phrase query
cargo run -p dowse -- add E:\projects     # add another root incrementally (no full rebuild)
cargo run -p dowse -- rules show          # view index rules (excluded dirs, extra extensions, size cap)

# Overlay app (Tauri 2 + Svelte 5)
cd crates/dowse-app
npm install
cargo tauri build      # produces the installer under target/release/bundle

Overlay app: Alt+\`` to summon, ↑↓to select,Enterto open,Ctrl+Enterto reveal in Explorer,Ctrl+Cto copy path,Escto hide. Results are paginated in groups of 50; the compact‹ 1 / N ›control shows only when needed, and pressing↓past the last result or↑ before the first moves between pages. Two nearly invisible dropdowns sit at the right of the search bar — file type filter (Ctrl+P) and sort order (Ctrl+S, relevance / newest / oldest / largest); both stay faint until you select a non-default value. Right-click a result row for a native Explorer-style context menu (open / reveal in folder / copy path / copy name). A pin toggle at the top-right keeps the window open when it loses focus (session-only, resets on restart). With an empty input, the overlay lists your recent searches (last 10, stored locally) — ↑↓/Enterto reuse one,Deleteto remove it.Ctrl+,` opens the settings panel — general (hotkey rebinding, transparency, autostart, interface language) and index rules (excluded directories, extra text extensions, per-file size cap).

Dowse settings panel in English, with controls for the global shortcut, transparency, startup behavior, and interface language

Preview pane for an image result: the source image rendered inline next to its OCR-extracted text with the matched terms highlighted

MCP server

dowse mcp starts a read-only MCP server over stdio, exposing the local index to AI agents:

claude mcp add --scope user dowse -- dowse mcp

Three tools: search (query, limit, sort by relevance / mtime / size, comma-separated ext filter, offset pagination with a total_hits count), preview (full snippet + metadata for one hit), index_status (document count, index health, active index rules). The server never touches the index writer — it only reloads the reader before each call, so it can run alongside the overlay app or a live dowse watch session without write contention.

Architecture

                 ┌─────────────────────────────────────────┐
                 │                   dowse                   │
                 │  library core: tantivy index · jieba      │
                 │  segmentation · encoding detection ·      │
                 │  text extraction (txt/md/pdf/code/        │
                 │  docx/xlsx/pptx) · OCR pipeline           │
                 │  ─────────────────────────────────────    │
                 │  CLI + MCP server (default `cli` feature) │
                 └────────────────────┬────────────────────┘
                                      │ library API
                                      │ (default-features = false)
                              ┌───────┴────────┐
                              │    dowse-app    │
                              └────────────────┘

Two crates. dowse is both the search library and the command-line tool: the library core exposes the search API, and the CLI plus the read-only MCP server ride behind the default cli feature in a single binary — the CLI for scripting and debugging, the MCP server for AI agents. dowse-app, a Tauri 2 + Svelte 5 resident overlay, is a separate crate that depends on dowse as a library only (default-features = false, so it pulls in neither the CLI nor its dependencies).

Index updates run on a two-tier scheme: while running, file system events drive incremental updates (500ms debounce window, batched commits); at startup, an mtime/size comparison reconciles changes made while the app was not running. On NTFS volumes with admin rights, the same two tiers are served by MFT enumeration and the USN Journal instead of directory walks and file-system-event watching; both paths produce identical results and the upper layers cannot tell which one is active.

Roadmap

#

Scope

Status

1

CLI indexing and search: Chinese segmentation, GBK detection, highlighting

✅ Done

2

Overlay: global hotkey, Acrylic material, keyboard navigation

✅ Done

3

Incremental indexing: file watching, startup reconciliation

✅ Done

4

OCR pipeline: screenshot text into the index

✅ Done

5

MCP server

✅ Done

6

NTFS MFT / USN Journal fast path

✅ Done (the admin-only fast path itself is not yet verified on real hardware — see the design doc's implementation notes)

7

Semantic search (embeddings, hybrid ranking)

🔍 Exploring

Stack

Rust · tantivy · jieba · Tauri 2 · Svelte 5 · Windows.Media.Ocr · notify · Win32 (MFT/USN Journal)

Design docs

Privacy Policy

The index is stored locally (%LOCALAPPDATA%\dowse). No network access, no telemetry. You can verify this yourself: watch the process in Resource Monitor or a firewall tool and confirm it opens no outbound connections. Releases also include a SHA-256 checksum for the installer so you can verify the download.

Full policy — data collection, storage, retention, and contact: PRIVACY.md.

License

Dual-licensed under MIT or Apache-2.0, at your option.

A note

As a kid I had a single Coolpad phone. In the long stretches without internet, I would open the file manager and study the files one by one, trying to figure out what they were and how they fit together, forever lost among files scattered everywhere with no idea what any of them held.

In college I bought a QNAP NAS and discovered Qsirch, a genuinely good thing, except it lived only on the NAS and had no Windows version.

screenpipe got there first, a kind of primitive version of the memory grain from Black Mirror S1E3, The Entire History of You. Very future, very post-modern, close to the ultimate form of local search, but far too heavy for the world as it is now.

So I made dowse.

The film Her reads like a prophecy: before long, AI will run our personal computers. dowse takes its cue from that and exposes an MCP interface for AI to call, except what it searches is your own files, on your own machine.

If you are a little obsessive, if you like keeping things in order, if you want real control over your own file system, this is for you. Performance and beauty are things I cared about just as much.

Available Tools

3 tools
index_statusA
Read-only

查看本地索引的概况：文档总数、已注册的索引根目录、索引落盘体积、最近一次更新时间，以及当前生效的索引规则（排除目录/追加文本扩展名/单文件体积上限）。不需要参数。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations include readOnlyHint=true, which matches the description's 'view' operation. The description adds specific behavioral context by listing the exact fields returned, going beyond the annotation. It discloses no side effects, which is appropriate for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the purpose ('查看本地索引的概况') and then lists the specific items in a clear enumeration. It is concise without sacrificing necessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description fully conveys what the tool does and what it returns. It covers all the relevant data points, making it complete for an agent to understand and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the description explicitly states '不需要参数' (no parameters needed). Per the baseline rule for 0 parameters, a score of 4 is appropriate; the description correctly confirms the lack of inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: viewing an overview of the local index, and enumerates the specific data points it returns (document count, root directories, disk size, last update, rules). This distinguishes it from the sibling tools 'search' and 'preview' without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating it requires no parameters and provides status information. It does not explicitly contrast with alternatives, but the context makes it obvious this is for checking index health/overview rather than searching or previewing. A minor gap is the lack of explicit 'when to use' phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

previewA
Read-only

取某个文件在索引里命中查询词的完整上下文（约 1500 字，比 search 返回的摘要长得多），附带文件大小/修改时间/类型。path 用 search 结果里的 path 字段。

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes目标文件的完整路径，取自 search 结果里的 path 字段
queryYes定位高亮用的查询词，通常和 search 时用的一致

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so no destructive behavior. Description adds specifics: returns ~1500-word context, file size/mod time/type, which is valuable beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the main purpose and key details. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description adequately explains return value (context and metadata). Sufficient for a preview tool with clear inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers both parameters with descriptions, and description reinforces that path comes from search results and query should match search. Adds clarity without contradicting schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it retrieves full context of query hits (about 1500 chars), longer than search summary, plus file metadata. It explicitly distinguishes from sibling tool 'search' by noting the longer context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use (need full context around hits) and how to use: path from search results, query consistent with search. Provides alternatives by contrasting with search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.1.0
    • Changedsearch5 fields changed
      • changedInput schema / properties / ext / description
        Previous value: -"只保留该扩展名的结果（不含点，如 \"md\"、\"pdf\"），可选"New value: +"只保留这些扩展名的结果（不含点）。逗号分隔可给多个，如 \"md\" 或 \"md,pdf,txt\"；\n不需要按扩展名过滤就整个字段别传（传空串或纯逗号会报参数错误）"
      • changedInput schema / properties / limit / description
        Previous value: -"最多返回几条，默认 10"New value: +"最多返回几条，默认 10；和 offset 搭配翻页"
      • addedInput schema / properties / offset
        Added value: +{
+  "description": "跳过前多少条命中再取，默认 0；和 limit 搭配翻页（取第 2 页就传 offset=limit）。\n返回里的 total_hits 是匹配总数，offset + 本页条数 < total_hits 就说明后面还有",
+  "format": "uint",
+  "minimum": 0,
+  "type": [
+    "integer",
+    "null"
+  ]
+}
      • changedInput schema / properties / query / description
        Previous value: -"查询词，支持空格分隔多个词（AND 语义）和 \"短语查询\""New value: +"查询词，支持空格分隔多个词（AND 语义）和 \"短语查询\"。也支持内联操作符：\n`path:关键词`（按路径匹配）、`mtime:>2026-01-01`/`mtime:<=2026-07`（按修改\n日期，支持 > >= < <=，日期写 YYYY-MM-DD 或 YYYY-MM）、`size:>10mb`/`size:<500kb`\n（按体积，单位 kb/mb/gb）、`A OR B`（大写 OR 分组，组内空格是 AND）、\n`-词` 或 `NOT 词`（排除）。带空格的操作数加引号，如 `path:\"我的 文档\"`"
      • addedInput schema / properties / sort
        Added value: +{
+  "description": "排序方式：relevance（默认，按相关度）/ mtime（按修改时间，新的在前）/\nsize（按体积，大的在前）。非 relevance 排序下 BM25 分数没有意义，结果里\n不返回 score 字段。传其它值会报参数错误",
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. 3 tool updatesv0.8.2
    • First observedindex_status
    • First observedpreview
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a clearly distinct role: index_status reports overall index health, search returns matching hits, and preview provides extended context for a specific file. The description explicitly pairs search with preview as a two-step workflow, removing any ambiguity.

Naming Consistency3/5

The names are simple and readable, but they do not follow a single consistent convention: 'search' and 'preview' are bare verbs while 'index_status' is a noun phrase with an underscore. There is no drastic mixing of styles, but the pattern is not uniform.

Tool Count5/5

Three tools is well-scoped for a local full-text search server: inspect index status, search, and preview matches. Each tool has a clear purpose and none feel redundant or missing for the core search workflow.

Completeness5/5

The server covers the full search journey: locating candidates with search, examining details with preview, and checking the index state with index_status. There are no obvious dead ends for the stated purpose of searching a local index.

Maintenance

ActivityActive
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers

  • Local RAG

    shinpr
    A
    license
    A
    quality
    A
    maintenance
    Privacy-first local document search using semantic search. Runs entirely on your machine with no cloud services, supporting PDF, DOCX, TXT, and Markdown files.
    22
    9
    4,655 npm
    398
    MIT

  • cowork-semantic-search

    ZhuBit
    A
    license
    Not graded
    quality
    C
    maintenance
    Local offline semantic search over documents (txt, md, pdf, docx, pptx, csv). Indexes folders into a LanceDB vector database with multilingual embeddings and supports hybrid vector + keyword search via Reciprocal Rank Fusion. No API keys, no cloud, no Docker required.
    28
    AGPL 3.0

  • LocalSynapse

    LocalSynapse
    A
    license
    Not graded
    quality
    A
    maintenance
    Offline AI-powered local file search MCP server for Windows. Searches inside document contents (Word, Excel, PDF, PowerPoint, HWP) using BM25 + dense vector hybrid search. 100% local, no cloud, no login, no telemetry.
    7
    Apache 2.0

  • Everything Search MCP Server

    fastmcp-me
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides fast file searching across Windows, macOS, and Linux using platform-native tools like Everything SDK, mdfind, and locate.
    MIT