Usmansayed / scubiee

A local code-context engine for AI coding agents. 
 Index your repository on your own machine, and let agents find code by meaning —
 so they read the few spans that matter instead of grepping blindly through files.
 Quick start ·
 What your agent gets ·
 How it works ·
 Docs 
---
Run `scubiee connect` once and your AI assistant gets a **local, always-fresh index** of your
repo — ranked discovery and deep symbol focus — without uploading a single line of code.
- **Local-first.** Tree-sitter parsing + on-disk embeddings. Code never leaves your machine; the
 only network step is a one-time model download (~270 MB) during setup.
- **Built for agents.** Ships as an MCP server — works in
 Cursor, Claude Code, Copilot, Kiro, and other MCP clients.
- **A real engine, not cloud RAG.** A local daemon with live Merkle sync keeps the index current
 as you edit and pull — index once, stay fresh.
 Ranked map find hits and focused symbol spans — all against a local index. 
---
## Quick start
**Prerequisite:** Python 3.11+. We recommend uv as the installer.
 [code] 
> `init` indexes the repo; `connect` wires up the assistant. You need **both**, then reload MCP
> (Cursor: Settings → MCP → refresh). Other clients: `--claude-code`, `--copilot`, `--kiro`,
> `--all`. See getting started.
 Prefer pip? 
 [code] 
On **Windows with a GPU**, install so DirectML isn't clobbered on upgrade — see
Windows / DirectML install.
---
## What your agent gets
One MCP tool — **`map`** — with two configs. The agent picks one by what it knows, acts on the
first good answer, and stops.
| `map` config | Use when | Returns |
|---|---|---|
| **`find`** | You don't know where the code lives | Ranked locations **with the top result's code inline** — usually no follow-up read |
| **`focus`** | You know the symbol name(s) | The symbol's full body **+ callers/callees + sibling names**, in one unit |
| **`gate` / `status`** | At session start | A tiny managed-repo check + engine health |
Scubiee is a **locate layer**, not a replacement for your editor. Exact string / path lookups stay
on the host's native **Grep / Glob / Read**, and history stays on **git** — a one-line grep is
faster and more precise than a semantic search for a known string. The CLI mirrors the tool:
`scubiee map --config find|focus`.
→ Full tool reference: MCP tools ·
the two configs, in depth
---
## How it works
 [code] 
A small local daemon serves retrieval over three fused channels — a code **graph**
(calls/imports/defines), **BM25** lexical match, and **dense** embeddings (CodeRankEmbed, FAISS).
Background sync keeps enrolled repos fresh with a Merkle diff, so edits show up in seconds without
a full reindex. Everything — indexing, embedding, retrieval — runs on your machine.
→ Architecture deep-dive: how everything works ·
system overview
---
## Everyday commands
 [code] 
Pause / stop / wipe and the full lifecycle are in repo lifecycle.
Every command and flag: commands reference.
---
## Privacy
- **Your code** is parsed