otter-search

otter-search is the desktop search daemon for Otter Shell. It indexes personal files and answers fuzzy path queries plus content (grep-style) search. Indexing and scoring run in pure Zig (otter_tools_search in otter-tools-core). No Rust or vendored fuzzy engines. A companion CLI, otter-searchctl, queries the indexes, checks status, lists roots, or triggers a reindex. The daemon must be running for otter-searchctl to work. The daemon watches the filesystem and reindexes on changes (debounced and throttled so bursts of writes do not thrash the index).

Binaries

otter-search: indexing daemon
otter-searchctl: control CLI (talks to the daemon)

Starting the daemon

Run once per session (or add to autostart).

otter-search

Add otter-search to your compositor autostart so indexes are ready early. The daemon binds $XDG_RUNTIME_DIR/otter-shell/otter-search.sock.

CLI: otter-searchctl

Command	Description
`otter-searchctl status`	Daemon health, root states, memory (RSS/PSS), and scan progress
`otter-searchctl roots`	List configured and expanded search roots with status
`otter-searchctl reindex`	Drop and rebuild indexes
`otter-searchctl path QUERY...`	Fuzzy path search across indexed roots
`otter-searchctl content QUERY...`	Live content (grep) search within indexed files

path and content accept space-separated multi-word queries. Replies stop after max_results matches (default 10, clamped to 50). Results print as JSON.

otter-searchctl path report pdf
otter-searchctl content "quarterly results"

Example JSON (path)

{"items":[{"kind":"file","path":"/home/you/Documents/invoice-2026.pdf","name":"invoice-2026.pdf","root":0,"size":12345,"modified":1720000000,"score":42}]}

Path results include root index, size, modified, and score. Content results include preview, line, col, ranges, root, and score.

Configuration

~/.config/otter-shell/otter-search.conf

enable_xdg_user_dirs = true
enable_home_config = true
enable_home_shallow = true
content_indexing = true
max_content_file_bytes = 10 * 1024 * 1024   # 10 MiB
cache_budget_max_bytes = 256 * 1024 * 1024  # 256 MiB
max_files_per_root = 75000
max_results = 10

# Extra roots (Dynamic fields use indexed form)
root_0_path = "/home/you/projects"
root_0_enabled = true

See the otter-conf Dynamic docs for accepted forms (root_0_..., bare, and so on).

Options

Key	Default	Description
`enable_xdg_user_dirs`	true	Index XDG dirs (Desktop, Documents, Downloads, Music, Pictures, Public, Templates, Videos)
`enable_home_config`	true	Index `~/.config` recursively
`enable_home_shallow`	true	Index direct children of `$HOME` (path only, shallow)
`content_indexing`	true	Enable live grep / content search
`max_content_file_bytes`	10 MiB	Skip content indexing for larger files
`cache_budget_max_bytes`	256 MiB	Total memory budget across recursive roots
`max_files_per_root`	75,000	Skip roots that look too large at startup
`max_results`	10	Cap on path/content matches per reply (clamped to 50)
`root`	(none)	Additional user roots (repeatable via Dynamic)

status also reports top-level rss_kb / pss_kb plus per-root scan progress when available. Heavy directories (.git, node_modules, .cache, .local, .cargo, and similar) are excluded by default. Content search also skips browser/editor storage and media/binary extensions.

Exclusions and safety

Built-in exclusions keep memory usage reasonable:

VCS dirs, build/cache dirs, dependency trees
Hidden dirs (except ~/.config)
Symlinks are not followed for indexing

If a root exceeds max_files_per_root it is marked too_large and skipped for recursive indexing.

Reindexing

otter-searchctl reindex

Use after large file operations or when you want fresh results immediately. The daemon also watches for changes and applies live reindex with debounce and throttle.

Integration

Scripts and tools can call otter-searchctl and parse JSON.
otter-launcher uses the daemon for file / f (path) and grep / g (content) modes.
Embedders: otter_tools_search and search_client in otter-tools-core, schemas in otter-config-types.

Content search is capped and skips binaries and large files. For very large collections, tune budgets or limit roots.

Get Started

Desktop Shell

Core Apps

Productivity

Utilities

Gaming

Configuration

Binaries

Starting the daemon

CLI: otter-searchctl

Example JSON (path)

Configuration

Options

Exclusions and safety

Reindexing

Integration

​Binaries

​Starting the daemon

​CLI: otter-searchctl

​Example JSON (path)

​Configuration

​Options

​Exclusions and safety

​Reindexing

​Integration

Binaries

Starting the daemon

CLI: otter-searchctl

Example JSON (path)

Configuration

Options

Exclusions and safety

Reindexing

Integration