Semlith

Semlith

Local search over your code and documents for AI agents.

Website · Install · Quick start · Agents · Portal · Benchmarks · Docs

Why Semlith

An agent working in a large codebase either reads too much, which is slow and expensive, or guesses which file to open, which is often wrong. What it needs is the few spans that answer the question. Semlith finds them.

• Hybrid search. Every query runs against a vector index (meaning) and a keyword index (exact names), and the two rankings are fused. *How does retry backoff work* and EMBED_BATCH both land on the right chunk.
• A code graph built on the same pass. Definitions become nodes, and calls, imports and re-exports become edges, each labelled with how well it is supported. Ask what calls a function, what breaks if it changes, or how two symbols connect.
• Always current. A watcher re-embeds a file when you save it. There is no build step and nothing to go stale against your working tree.
• Local by design. No API keys, and no network at query time unless you sign in to Semlith Cloud, a separate hosted service, with semlith cloud login. The portal binds to 127.0.0.1 only. Model weights and acceleration packs are the only downloads, each pinned by digest, and --airgap refuses every outbound request before a connection opens.
• Made for agents. An MCP server with eight tools listed by default and sixteen in all, registered in your agent clients by semlith setup, and a ledger of every retrieval with the tokens it saved.
• More than code. PDFs, Office documents, notebooks and Markdown are read as text, and images are searchable by what they show.

Install

One command, no Rust toolchain needed.

macOS and Linux

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/semlith/semlith/main/install.sh | sh

Windows

irm https://raw.githubusercontent.com/semlith/semlith/main/install.ps1 | iex

The installer picks the release for your machine, verifies the ed25519 signature on the release's SHA256SUMS, checks the archive against it, unpacks it into ~/.semlith/bin and runs semlith setup. Setup puts Semlith on your PATH, downloads the embedding model, registers Semlith with each agent client that has a registration CLI, and installs the daemon as a login service. Run semlith setup again at any time to repair an install, and --yes takes every default.

You can also run cargo install semlith, or take an archive from the releases page. semlith upgrade replaces the binary with the newest release, and Semlith never checks for updates on its own.

Requirements. A 64-bit machine running macOS on Apple silicon, Linux on x86_64 or aarch64, or Windows on x86_64 (Windows PowerShell 5.1 is enough). The Linux archives ship libonnxruntime.so beside the binary and need only glibc 2.34 or later and libstdc++ (GLIBCXX_3.4.22). Debian 12, Ubuntu 22.04, RHEL 9 and Amazon Linux 2023 all qualify. Intel macOS is not supported, because ONNX Runtime no longer ships for it.

Verifying the installer

The installer writes the binary to ~/.semlith/bin (mode 700 on macOS and Linux) and, on Linux, libonnxruntime.so beside it. Nothing is written until the archive passes three checks. SHA256SUMS must carry the project's ed25519 signature, checked with ssh-keygen -Y verify (OpenSSH 8.1 or later, which macOS, current Linux distributions and Windows 10 and later have). The archive's SHA-256 must match it. When gh is on your PATH, its GitHub artifact attestation, signed by this repository's release workflow, is checked too. A missing or wrong signature stops the install, and semlith upgrade holds a release to the same key, built into the binary, which semlith --version names. curl is held to https and TLS 1.2 or later, and the script runs only once it has fully downloaded. Releases before v0.40.0 are not signed, so these installers do not install them.

To read the installer before running it:

curl --proto '=https' --tlsv1.2 -fsSLO https://github.com/semlith/semlith/releases/latest/download/install.sh

less install.sh gh attestation verify install.sh --repo semlith/semlith sh install.sh

On Windows, run irm https://github.com/semlith/semlith/releases/latest/download/install.ps1 -OutFile install.ps1, read it, then run powershell -ExecutionPolicy Bypass -File install.ps1.

To verify an archive by hand:

echo 'semlith-release ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICMTHiHMzeSHzzc+8UDZHUzJcvb6XGUBb+TJdFes91xm' > allowed_signers

ssh-keygen -Y verify -f allowed_signers -I semlith-release -n file -s SHA256SUMS.sig < SHA256SUMS grep " semlith- - .tar.gz$" SHA256SUMS | shasum -a 256 -c gh attestation verify semlith- - .tar.gz --repo semlith/semlith

Quick start

cd ~/src/ripgrep

semlith index . # one store, and the model (~52 MB) downloads once semlith search "where is a file detected as binary" semlith neighbors search_parallel # callers and callees semlith start # the daemon and the portal

$ semlith search "where is a file detected as binary" -k 1

1. 0.083 vf GUIDE.md:735-746 binary files:

1. The default mode is to attempt to remove binary files from a search completely. ...

$ semlith neighbors search_parallel callers (2) main via defines (extracted) crates/core/main.rs:44 · call at line 166 run via calls (resolved) crates/core/main.rs:78 · call at line 90 callees (25) matcher via calls (resolved) crates/core/flags/hiargs.rs:379 · called at crates/core/main.rs:177 search_worker via calls (resolved) crates/core/flags/hiargs.rs:705 · called at crates/core/main.rs:176 ...

Every hit is a path:start-end locator you can hand to an editor or an agent, and vf says the vector and keyword lists both found it. Documents answer the same way.

Use it from an agent

semlith setup     # registers each agent client that has a registration CLI

semlith doctor # checks each client can actually reach it, and says how to fix it if not

semlith setup registers the MCP server at user scope in each installed client that has a registration CLI, which is six of the 12 documented clients. The other six are a config file, which semlith setup --register-all writes for you, and semlith doctor reports on every one. Each stanza is run against the binary in tests/clients.rs, and docs/clients.md has them all with the HTTP transport. Setup also installs the Semlith Agent Skill, a steering hook that suggests a Semlith call when an agent is about to grep, and a read-only research agent.

semlith mcp serves MCP over stdio, and the daemon serves the same tools over HTTP at /mcp, behind an agent key (semlith key show). Eight tools are listed by default, because every definition costs tokens on every request, and SEMLITH_MCP_TOOLS=all lists all sixteen.

A bare semlith mcp opens every registered store, so one question can span repositories. It speaks MCP 2026-07-28, 2025-11-25, 2025-06-18 and 2024-11-05, each proven by a session in tests/mcp.rs. In the official MCP registry it is listed as mcp-name: io.github.semlith/semlith

The portal

semlith start runs one daemon that owns every store. It holds each store's write lock, watches its folders, re-embeds what you save, and serves a portal at http://127.0.0.1:7365. The URL with its session token is printed once, on stdout. docs/portal.md documents every page.

Search . Hybrid results, each saying which list found it.

Graph . Callers, callees, blast radius and paths.

Index runs . Live rate per device, pause and stop.

Ledger . Every retrieval, and the tokens it saved.

It is not on the network. The daemon binds 127.0.0.1 only, with no flag to change it. Every page and /api/ route needs the per-run session token, sent in a Semlith-Token request header, and without it the answer is 401. The agent key opens /mcp and nothing else. Responses carry a Content-Security-Policy of `'self'