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.
# 1. Install
uv tool install scubiee
# 2. Set up once per machine (downloads the model, picks CUDA / DirectML / MLX / CPU)
scubiee setup
# 3. Index a repo (run inside the repository)
cd /path/to/your/repo
scubiee init .
# 4. Connect your IDE, then reload MCP in the IDE
scubiee connect --cursor
initindexes the repo;connectwires 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?
pip install -U scubiee
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
setup (once) → init (per repo) → connect (per IDE)
│ │ │
▼ ▼ ▼
download model parse + embed MCP + agent rules
→ ~/.scubiee → reload IDE
AI coding tool ──MCP──► Scubiee daemon (localhost) ──► local index (~/.scubiee)
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
scubiee sync . # refresh the index after a big pull or refactor
scubiee status . # enrollment + engine health
scubiee search "auth middleware" . # search from the terminal, no IDE needed
scubiee doctor . # diagnose setup / accelerator issues
scubiee upgrade # update the package and rebind MCP
Pause / stop / wipe and the full lifecycle are in repo lifecycle. Every command and flag: commands reference.
Privacy
- Your code is parsed and embedded locally and stays on disk — nothing is sent anywhere for search.
- The model downloads once during
scubiee setup(~270 MB); after that, indexing works offline. - Data lives under
~/.scubiee(engine state) and<repo>/.scubiee(per-repo index).
Documentation
| Getting started | docs/web-info/getting-started.md |
| Install & debug | docs/web-info/install-and-debug.md |
| MCP tools reference | docs/web-info/mcp-tools-reference.md |
| Troubleshooting | docs/web-info/troubleshooting.md |
| System overview | docs/scubiee-overview.md |
| Full docs index | docs/README.md |
FAQ
Does init connect my IDE?
No. init indexes the repo; connect writes the MCP config and agent rules. Run both, then reload
MCP in the IDE.
Does my code get uploaded anywhere?
No. Only the embedding model downloads (once, during setup). Parsing, embedding, and search all
run locally.
My agent says managed: false.
Run scubiee init . and scubiee connect inside that repo, then reload MCP. For Kiro / Copilot /
Cline / Roo, run connect inside each repo.
Windows: GPU acceleration stopped working after an upgrade.
Run scubiee setup --repair. To prevent it recurring, install with the DirectML override — see
Windows / DirectML install.
Windows: "Access denied" during upgrade.
Run scubiee unlock-tool, then retry. Quitting the IDE first helps.
How do I file a bug with context?
scubiee diagnose --no-tests --desktop — attach the Desktop JSON plus a tail of
~/.scubiee/engine.log.
Contributing
git clone https://github.com/Usmansayed/scubiee
cd scubiee
uv pip install -e .
scubiee setup
Issues and pull requests are welcome. Please run scubiee certify before opening a PR.
PyPI: scubiee · Latest release: 0.3.146
License
Copyright © 2026 Usman Sayed. Licensed under the Apache License, Version 2.0.
1 maintainer
Metadata
1 maintainer
Release files for scubiee 0.3.147
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| scubiee-0.3.147.tar.gz | 1.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| scubiee-0.3.147-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.4 MB
Release files / scubiee-0.3.147.tar.gz
| Download URL | scubiee-0.3.147.tar.gz |
|---|---|
| Size | 1.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71025a1b77477fde6231caacb9304b5b8639baa7fe1e7794129f34b36d8fc122
|
|
BLAKE2b-256 checksum How to use checksums |
25a944cf16c61734df8bbe66bc19a0203546f8cce75097801753bdc1e8a322df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Release files / scubiee-0.3.147-py3-none-any.whl
| Download URL | scubiee-0.3.147-py3-none-any.whl |
|---|---|
| Size | 1.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55ccb3e88fb3f17bfd3f1d2a3a2201f115cafe0e1289d58c0bc39226e865dfff
|
|
BLAKE2b-256 checksum How to use checksums |
7cb8b6154fe26954861be26c2ce6be4c086876e4c0374696accfe1f0d992d26f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
