Workspace search

A ranked, chunk-aware full-text search over your workspace’s file content — the complement to exact-match grep. Use it to find where a topic, concept, or phrase is discussed when you don’t know the exact substring; the built-in grep is the stable bounded route for one exact regex or a 1–2 character pattern.

Default and opt-out

The search_workspace tool is on by default. To remove it from new sessions:

# ~/.kin/settings.toml  (or a project .kin/settings.toml — it's project-safe)
search_enabled = false

or for a one-off launch:

KIN_SEARCH_ENABLED=0 uv run kin

The toggle may be set in project settings because the index is local and has no network access.

With the default enabled, the first search may take a moment while the lazy index builds. Scheduled kin -p runs use the same local workspace index.

How it works

The first search builds a local SQLite FTS5 index under ~/.kin/index/. Later searches update changed files and remove deleted ones. Builds have a time limit and report when the index is partial.

Results rank lexical matches with BM25 and point to line windows or Markdown heading sections. The index uses workspace text only, with no network or embedding service.

Arguments

Argument	Meaning
query	The search text. Must be ≥ 3 characters (the trigram floor — shorter strings have no trigram to match; use grep for those).
path	Optional path-prefix filter, relative to the workspace root (e.g. src/).
kind	Optional chunk-kind filter: markdown (heading sections) or text (code + plain text). Omit to search everything.
limit	Max results (default 10, max 50).

What’s indexed (and what isn’t)

The crawl reuses grep’s discipline and adds a few exclusions, so the index excludes these recognized file classes:

• Excluded: secret files (.env, ~/.ssh, .mcp.json, and the rest of the read-deny list), .gitignored paths, binary files (NUL-byte heuristic), oversized files, and heavy dirs (.git, node_modules, .venv, …). Excluded files appear in neither the index nor the results.
• Trust. Because results are in-workspace content the model already reads freely, they carry the same trust as grep output — they are not wrapped in the untrusted-content framing that web fetches and out-of-workspace @-mentions get.

Relationship to grep

	grep	search_workspace
Match	Exact regex / substring	Ranked full-text (BM25, trigram)
Order	File order	Relevance, best-first
Granularity	Single line	Chunk (line range / heading section)
Min length	1 char	3 chars
Ignored files	Included (except secrets)	Excluded by .gitignore
Default availability	Always	On (search_enabled=false opts out)

Reach for search_workspace when you’re searching by meaning/topic and don’t know the exact text. For known text, the built-in grep remains the bounded, workspace-confined single-search route. A root session may use shell search instead when batching or command composition is useful; read-only profiles stay on the structured tool. See the Filesystem tools section for grep and the rest of the built-in read/write toolset.