\r \r

SLG — Semantic Git Search\r

\r slg is a local-first CLI that builds a semantic index of your git history (embeddings + BM25) so you can ask natural-language questions about who changed what, why, and when. No API keys required — everything runs offline via ONNX Runtime.\r \r

Installation\r

\r

npm install -g slg-cli\r
# or run without installing\r
npx slg-cli \x3Ccommand>\r
```\r
\r
## When to Use This Skill\r
\r
Use `slg` when the user:\r
\r
- Asks **why** a piece of code exists or was written a certain way\r
- Wants to know **who** is responsible for a file or function\r
- Is tracking down **what introduced a bug** across many commits\r
- Needs to understand **what changed** between two refs or in a range\r
- Wants to assess **how risky** reverting a commit would be\r
- Asks about **recent activity** on a file or directory\r
\r
## Setup\r
\r
Index must be built once before searching. Run this in the repo root:\r
\r
```bash\r
slg init\r
```\r
\r
Re-index after significant new commits:\r
\r
```bash\r
slg reindex\r
```\r
\r
Check index health:\r
\r
```bash\r
slg doctor\r
```\r
\r
## Core Commands\r
\r
### Why does this code exist?\r
\r
```bash\r
slg why "why does the retry logic use exponential backoff"\r
slg why "what is the purpose of the connection pool size limit"\r
```\r
\r
Returns ranked commit results explaining the reasoning behind code decisions.\r
\r
### Who owns a file?\r
\r
```bash\r
slg blame src/auth/middleware.ts\r
slg blame --top 3 src/payments/\r
```\r
\r
Returns contributors ranked by semantic commit weight for the given path.\r
\r
### Find what introduced a regression\r
\r
```bash\r
slg bisect "authentication stopped working after the refactor"\r
```\r
\r
Narrows down the range of commits most likely to have introduced an issue using semantic search over the message + diff corpus.\r
\r
### Search commit history semantically\r
\r
```bash\r
slg log "database schema migrations"\r
slg log --since 2024-01-01 "API rate limiting changes"\r
slg log --limit 20 "performance optimizations"\r
```\r
\r
Returns commits ranked by semantic + BM25 relevance. Supports `--since`, `--until`, `--limit`, and `--path` filters.\r
\r
### Summarize a diff\r
\r
```bash\r
slg diff HEAD~5..HEAD\r
slg diff v1.2.0..v1.3.0\r
slg diff --path src/api/ main~10..main\r
```\r
\r
Generates a semantic summary of what changed across a commit range.\r
\r
### Assess revert risk\r
\r
```bash\r
slg revert-risk abc1234\r
slg revert-risk HEAD~3\r
```\r
\r
Scores how risky it would be to revert a given commit based on downstream dependency analysis.\r
\r
### See recent activity\r
\r
```bash\r
slg status\r
slg status --path src/\r
```\r
\r
Shows recent indexed commits and index freshness.\r
\r
## MCP Server\r
\r
`slg` ships an MCP (Model Context Protocol) server, letting AI agents query git history directly:\r
\r
```bash\r
slg serve\r
# or\r
slg mcp\r
```\r
\r
Configure in your agent:\r
\r
```json\r
{\r
  "mcpServers": {\r
    "slg": {\r
      "command": "slg",\r
      "args": ["serve"]\r
    }\r
  }\r
}\r
```\r
\r
Available MCP tools: `slg_why`, `slg_blame`, `slg_bisect`, `slg_log`, `slg_diff`, `slg_revert_risk`, `slg_status`.\r
\r
## Tips\r
\r
- `slg why` works best with full-sentence natural language questions\r
- `slg bisect` is most effective when given a behavioral description rather than error text\r
- Prefix path filters with `--path` to narrow any command to a directory or file\r
- Run `slg doctor` if search results seem stale — it reports index coverage and age\r
- For large repos (10K+ commits) the initial `slg init` may take several minutes; subsequent `slg reindex` calls are incremental and fast\r