git:20260925.78fbf24 to git:20260925.9314a3e

---

name: semlith

description: Use FIRST for any question about code in a folder semlith has indexed — how something works (semlith_brief), where it is defined or used, what calls it, what breaks if it changes, how A reaches B, what a directory holds, or where a planned change would land — before grep, rg, git grep, find, cat, sed, awk or Read — including every-occurrence sweeps (every TODO, every use of a string or regex: semlith_search with exact: true). Also use when handing code research to a subagent. Skip only for git history and the exact read right before an edit.

---

# semlith

The `semlith_*` MCP tools hold a pre-built index of the folders semlith covers:

chunks, embeddings, parsed symbols and call edges. One call replaces a round of

grep + read, returns only the lines that bear on the question, and gives

`path:line` you can cite. Make a semlith call your first lookup for every code

question, and keep using it until the question is answered.

## Pick the tool by the question

| The question | Call |

|---|---|

| How does X work? / explain X | `semlith_brief {question}`, in the user's words |

| Where is X? / which files handle X? | `semlith_search {query}` |

| Every line containing a string or regex (every TODO, every `Hit {`) | `semlith_search {query, exact: true}` |

| What breaks if X changes? / who calls X? / every call site | `semlith_impact {name}` |

| What does X call, one hop either way? | `semlith_neighbors {name}` |

| How does A reach B? / trace the flow | `semlith_trace {from, to}` (`semlith_path` for yes or no) |

| This span / this whole function | `semlith_read {target}`: `path:start-end` or a symbol name |

| Several definitions at once | `semlith_symbol {names: [...]}`, up to 20 |

| What is in this directory? / where would X live? | `semlith_files {tree: true}` |

| Every construct of shape Y | `semlith_pattern {query, lang}`, a tree-sitter query |

Planning a change or tracing a flow: `semlith_brief` for the core, then

`semlith_impact` or `semlith_trace` on the central symbols it names, then read

each central symbol whole (`semlith_read` by name) before you answer.

## What the tools take and return

- `semlith_impact` accepts `Type::method`, `module::function` and `Type.method`.

Rows carry call-site lines. Past 16 000 characters it gives per-file counts

and a `more:` line. `semlith_symbol` and `semlith_neighbors` share that cap; a

caller of a name with several definitions shows `→ Type::method`.

every definition whole (`Type::method` narrows), up to 32 000 characters. A

file edited since indexing is read from disk and marked.

- `semlith_search` rows read `start-end name kind @defline · lists | best line`,

with paths relative to the `root …` header. Identical copies collapse to

`also in N copies`. `format: "excerpt"` adds text.

- `semlith_search {exact: true}` is grep -E over every indexed file: a count

line, then each file once and its matching lines as `line definition | text`,

so the enclosing function comes with the hit. A query that is not a valid

- `semlith_brief` gives text for one span, the best code span for a code

question, plus one-hop edges. `semlith_read` the other spans you need.

- `semlith_files {tree: true, depth, sort: name|size|symbols|recent}` shows

directories with counts and languages, per-file lines, symbols and first

definitions, and what is on disk but not indexed, and why. Capped at 8 000

characters.

`path`, `ext` and `lang` filter search, files and pattern: globs, repeats

union, kinds intersect, a leading `!` excludes. Tests and fixtures rank below

product code unless the query names tests. For a question about product code,

add `path: ["src/**"]` (or the repo's source root) to keep them out entirely.

Filtering happens before ranking, so narrowing improves the answer too.

## Rules

1. **First lookup is semlith.** Do not open with grep, rg, find, cat, sed or

Read on indexed source. Bash `grep`/`rg` is the same habit as the Grep tool,

and `sed -n`/`awk` to see lines or find the enclosing function is the same

habit as Read: `semlith_read` and exact search answer both.

2. **Read spans, not files.** Use the host `Read` (with `offset`/`limit`) only

for the exact text right before an edit, or for a file that is not indexed.

3. **Delegating?** Subagents do not see this skill. Put this line in their

prompt: "Use the semlith MCP tools (semlith_brief, semlith_search,

semlith_impact, semlith_read) for every code lookup, and semlith_search with

exact: true in place of grep." In Claude Code, pick `semlith-explorer` over `Explore`.

4. **Fall back per question, not per session.** If an answer is thin or wrong,

say so in one line, use grep/Read for that question only, and return to

semlith for the next.

5. **Never call `semlith_index`, `semlith_add` or `semlith_forget`** unless the

user asked to change the index. They write; a refusal is not a reason to.

## Limits

- 16 tools: `semlith_search`, `semlith_brief`, `semlith_read`, `semlith_symbol`,

`semlith_neighbors`, `semlith_path`, `semlith_trace`, `semlith_impact`,

`semlith_files`, `semlith_pattern`, `semlith_stats`, `semlith_languages`,

`semlith_report`, `semlith_index`, `semlith_add`, `semlith_forget`.

- Exact search reads what the index holds: a file edited since the last index

pass answers as it was, and a file that is not indexed is not searched.

- Multi-store search merges on rank, so never compare scores across stores.

- Only indexed paths are known. Check `semlith_files` before concluding that

something does not exist.