Local context engine for AI coding tools.
Index your repository on your machine. Agents search by meaning - map · focus · grep - instead of grepping blindly through files.
Type scubiee connect once and your AI coding assistant gets a local index of the repo - ranked discovery, deep focus, and exact search - without uploading code to a vendor.
- Fully local. Tree-sitter + embeddings on disk. Code never leaves the machine. The only network step is a one-time model download at setup (~270 MB).
- Built for agents. MCP tools
map·focus·grepin Cursor, Claude Code, Copilot, Kiro, and more. - Not a cloud RAG. A real local engine with live Merkle sync. Index once, stay fresh as you edit and pull.
Ranked map hits, focused spans, exact grep - all against a local index.
Install
Requires Python 3.10+. Recommended installer: uv.
uv tool install scubiee
Or with pip
pip install -U scubiee
Setup (once per machine)
Downloads the embedding model and picks CUDA / DirectML / MLX / CPU for your hardware.
scubiee setup
Index a repo
Parses and embeds the project into ~/.scubiee. Run this inside the repository you want agents to understand.
cd /path/to/your/repo
scubiee init .
Connect your IDE
Wires MCP + agent rules so the assistant can call Scubiee. Then reload MCP in the IDE (Cursor: Settings → MCP → refresh).
scubiee connect --cursor
Other tools: --claude-code, --copilot, --kiro, --all, and more - see getting started.
init indexes. connect attaches the assistant. You need both.
What agents get
| Tool | Role |
|---|---|
map |
Ranked files & symbols — overview without dumping bodies |
pack_context |
Lean heatmap around a seed (default ladder step 2) |
expand_context / collect_hot_context |
Grow the graph / pull bodies when needed |
gate / status |
Tiny managed check + engine health at session start |
Also: workspace, expand. Exact/name lookup stays on host Grep/Glob/Read. Classic focus/grep/glob MCP tools are opt-in (CTX_MCP_EXPERIMENT=classic) — see MCP tools reference.
How it works
setup (once) → init (per repo) → connect (per IDE)
│ │ │
▼ ▼ ▼
download model parse + embed MCP + rules
~/.scubiee reload IDE
AI coding tool ──MCP──► Scubiee (localhost) ──► ~/.scubiee
A small local daemon serves search. Background sync keeps enrolled repos fresh. Indexing and retrieval stay on your machine.
Day-to-day
After a big pull or refactor, refresh the index:
scubiee sync .
Check enrollment and health:
scubiee status .
scubiee doctor .
Search from the terminal (no IDE required):
scubiee search "auth middleware" .
Upgrade the package and rebind MCP:
scubiee upgrade
Lifecycle (pause / stop / wipe) is covered in repo lifecycle. Full flag list: complete CLI reference.
Privacy
- Code stays on disk - parsed and embedded locally; nothing leaves for search.
- Model downloads once during
setup(~270 MB). After that, indexing is offline. - Data lives under
~/.scubieeand<repo>/.scubiee.
Docs
| Getting started | docs/web-info/getting-started.md |
| Install & debug | docs/web-info/install-and-debug.md |
| MCP tools | docs/web-info/mcp-tools-reference.md |
| Troubleshooting | docs/web-info/troubleshooting.md |
| How everything works | web-info/how-everything-works.md |
FAQ
Does init connect Cursor?
No. init indexes. connect writes MCP and rules. Then reload MCP.
Does my code get uploaded?
No. Only the embedding model downloads during setup.
Agent says managed: false?
Run init and connect in that project, then reload MCP. For Kiro / Copilot / Cline / Roo, run connect inside each repo.
Windows "Access denied" on upgrade?
scubiee unlock-tool, then retry. Quitting the IDE helps.
Need a support bundle?
scubiee diagnose --no-tests --desktop - attach the Desktop JSON and a tail of ~/.scubiee/engine.log.
PyPI: scubiee · Release: 0.3.15 · Contributors: uv pip install -e . then scubiee setup
License
Copyright 2026 Usman Sayed
Licensed under the Apache License, Version 2.0.
1 maintainer
Release files for scubiee 0.3.33
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.33.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| scubiee-0.3.33-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.8 MB
Release files / scubiee-0.3.33.tar.gz
| Download URL | scubiee-0.3.33.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9be47373f1ffa271639abe70814d2f9befb7fab3169c9ce2cca16f4bf571ae7d
|
|
BLAKE2b-256 checksum How to use checksums |
6b7e87c566325a0af4f3135a415ecaf9e6fcd6e7b18f45ebb3b2af959d375e2b
|
| 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.33-py3-none-any.whl
| Download URL | scubiee-0.3.33-py3-none-any.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
86ccee9ff00c04163ac1d774c860be1b04532f7d92d1c39629bc469c0a49a887
|
|
BLAKE2b-256 checksum How to use checksums |
29b169290bb006059570df3f7738f0f6bd3cc9d5dfc56c4e0ead3f8b67e20b0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
