code-search-local (csl)

Local code search over your git checkouts. A CLI and an MCP stdio server for Claude Code, backed by zoekt.

csl walks the directories you configure, indexes every git repo it finds, and searches them with zoekt's trigram index. You get grep-like queries across dozens of checkouts in milliseconds, without shipping your code to a cloud service.

There is no server to manage. A short-lived search daemon is spawned on demand from the same binary, keeps zoekt shards mmap'd across queries, and exits after ten minutes of idleness.

Use it in two ways:

• At the terminal: csl search, csl count, csl repo, csl read.
• Inside Claude Code (or any MCP client). csl mcp exposes eight csl_* tools so the agent can search, resolve repo paths, and read files without shelling out.

Install

Requires Go 1.25+.

go install github.com/mad01/code-search-local/cmd/csl@latest

From a checkout:

make install   # builds with version embedded, copies to ~/code/bin/csl

Configure

Create ~/.config/csl/config.yaml listing the directories that contain your git checkouts:

dirs:
  - ~/code/src/github.com
  - ~/workspace

csl walks each directory concurrently and records every directory whose immediate child is .git. Nested repos are not descended into once a .git is found.

Use the CLI

csl repo --list                     # list every indexed repo
csl search "func Walk"              # search all indexed repos
csl search "TODO" --repo myrepo     # filter to one repo
csl search "fmt\.Errorf" --lang go --output-mode content -C 3
csl count "TODO" --group-by repo    # cross-repo tally
csl doctor                          # check index + daemon health

First search in a fresh checkout triggers an initial index build. Subsequent searches are served by the daemon and return in hundreds of milliseconds.

Register the MCP server

claude mcp add --scope user csl -- csl mcp
claude mcp list   # expect: csl: csl mcp - ✓ Connected

The MCP server exposes eight tools: search, count, query validation, repo lookup/info/pull/reindex, and file read. See docs/mcp.md for the per-tool reference.

To skip the per-call permission prompt, add "mcp__csl__*" to permissions.allow in ~/.claude/settings.json.

Add this to your CLAUDE.md

Registering the MCP server makes the tools available, but Claude will still reach for find, ls, Glob, or raw grep by default. Paste the snippet below into ~/.claude/CLAUDE.md (user-level) or a project CLAUDE.md so Claude prefers csl_* tools for local repo work:

## Local Code Search (csl)

Always use the `csl_*` MCP tools for repo discovery, code search, and file reads across local checkouts. Do not use the `csl` CLI directly — the MCP tools and CLI share the same foundation, so if one is down the other will be too.

Available tools:
- **Repo:** `csl_repo_lookup`, `csl_repo_info`, `csl_repo_pull`, `csl_repo_reindex`
- **Search:** `csl_search`, `csl_count`, `csl_read`, `csl_query_validate`

### Repo discovery
- Use `csl_repo_lookup` or `csl_repo_info` to find repos. Do not use `find`, `ls`, `Glob`, or shell to manually search for repo directories.
- `csl_repo_info` returns git health (branch, dirty files, index staleness, suggested action). Call it before starting work on a repo to decide whether to commit, stash, pull, or reindex.
- `csl_repo_lookup` returns `remote` and `host` fields — use them to branch behavior per git host when needed.
- If lookup returns empty, the repo is not checked out locally — say so, don't guess paths.
- Use `csl_repo_pull` before creating branches on repos that may be behind (it has safety checks for dirty state).
- Use `csl_repo_reindex` after significant changes so `csl_search` results stay current.

### Query syntax
For zoekt query syntax help, call `csl_query_validate` — it returns the parsed tree or a parse error with a hint.

### Multi-repo awareness
When switching working directory to a different git repo, read that repo's `CLAUDE.md` (and `.claude/CLAUDE.md` if present) before making changes. Per-repo instructions take precedence over this global file for repo-specific concerns (build commands, conventions, test frameworks).

Docs

• Getting started — install, configure, first search.
• Configuration — config file, paths, environment.
• CLI reference — every subcommand and flag.
• MCP server reference — csl mcp tool reference for Claude Code.
• Architecture — how the daemon, index, and MCP adapter fit together.

License

MIT. See LICENSE.