Scubiee
Local Context Engine: Merkle sync → Graphify AST → mix compress → CodeRankEmbed FP16 (MLX on Apple Silicon, FastEmbed CUDA/DirectML/CPU elsewhere) → TurboQuant/FAISS → Conductor R_plan
Install (no git clone)
Requires Python 3.10+. Two steps on a clean machine.
Recommended — uv (fast, isolated CLI; no venv juggling):
uv tool install scubiee
scubiee setup
Always pin the PyPI index on Windows (avoids stale uv cache and broken partial upgrades):
uv tool install --force scubiee==0.2.49 --index-url https://pypi.org/simple
scubiee setup --repair
If uv tool install scubiee==X.Y.Z says “no version found”, run uv cache clean and retry with --index-url https://pypi.org/simple.
Broken install (failed to locate pyvenv.cfg, faiss errors): quit Cursor, then scripts/repair-uv-scubiee.ps1. See docs/web-info/uninstall-windows.md.
Uninstall / uv tool uninstall Access denied: run scubiee stop, then scubiee wipe --all --yes --package, reload Cursor. Do not use raw uv tool uninstall while MCP is running.
Upgrade later: uv tool install --force scubiee --index-url https://pypi.org/simple then scubiee setup --repair.
Note: uv tool upgrade scubiee refreshes dependencies but may not bump the scubiee version — use --force with an explicit version when release notes say to.
Alternative — pip:
pip install -U scubiee
scubiee setup
npm (optional wrapper — installs Python package + runs setup):
npm install -g scubiee
Then scubiee init <repo> (or ctx init) for each codebase, and reload MCP in Cursor (Settings → MCP → refresh).
After uv tool install scubiee, add tools to PATH once per machine:
uv tool update-shell # restart terminal after
# or one session: export PATH="$HOME/.local/bin:$PATH" (Windows: see uv's hint)
scubiee setup picks CUDA (NVIDIA), DirectML (Windows AMD/Intel), MLX FP16 (Apple Silicon Metal), CoreML (Intel Mac), or CPU. On a MacBook, uv tool install scubiee / pip install scubiee pulls FastEmbed, ONNX Runtime, and MLX — no [mlx] / [coreml] extra required. Then scubiee setup (or scubiee setup --repair after an upgrade) writes the MLX FP16 profile. Opt out: CTX_MLX=0 or scubiee setup --profile cpu.
If PyPI is behind GitHub, install the tagged release:
uv tool install "scubiee @ git+https://github.com/Usmansayed/new-context-engine.git@v0.2.6"
scubiee setup
From a git checkout (contributors): uv pip install -e ".[dml]" (or pip install -e .) then scubiee setup. Maintainers: see docs/publish-setup.md.
Use
Inside the engine process there are three managers only:
| Manager | Role |
|---|---|
| RuntimeManager | Workspace lifecycle, publish search generation after sync, serve queries |
| IndexManager | Merkle probe, full index, incremental sync |
| ResourceManager | CPU/RAM admission and embed batching |
A tiny watchdog sidecar (not a manager) polls /health and restarts the daemon if it crashes. Disable: CTX_WATCHDOG=0.
Install-and-forget check (isolated port/home):
.\.venv\Scripts\python.exe -u scripts\sim_install_forget.py
Use
In Cursor: call MCP tools after reload.
CLI (optional):
ctx index .
ctx search "login validate"
ctx sync .
ctx status .
Or: python -m pipeline index .
Default pre-embed compression is mix with a 512-char cap (locked). Opt out: CTX_COMPRESS=off.
Resource management
Indexing and embedding run at the calibrated batch. The resource manager only pauses if free RAM is near empty (default under 256 MB). CPU spikes and Windows “RAM % used” (file cache) do not stop work.
ctx resources # live pressure + hardware
ctx resources --refresh # re-detect CPU/RAM/GPU/libs
ctx init # also writes hardware.json + picks fastest ORT backend
Disable entirely: CTX_RM_DISABLE=1. Emergency floor: CTX_RM_MIN_FREE_RAM_MB.
Cursor MCP
After install, MCP tools talk to the local Context Engine service (CTX_ENGINE_URL, default http://127.0.0.1:8765). The MCP process auto-starts that service if needed.
Tools: search_code, locate_capability, grep_code, file_outline, status, sync_index, set_repo, register_project.
Dashboard (optional): http://127.0.0.1:8765/dashboard
Advanced (usually unnecessary):
ctx engine status
ctx engine stop
ctx engine run . # foreground service
ctx engine start also starts the watchdog sidecar. Logs: ~/.context-engine/watchdog.log.
Registration modes (dashboard or CLI):
| Mode | Trigger |
|---|---|
| Automatic (default) | IDE/MCP open registers the project once, then incremental indexing |
| MCP / CLI | No auto-init; first tool call returns a consent prompt; use register_project (optional always_allow) or ctx register |
ctx settings --mode automatic
ctx settings --mode mcp_cli
ctx register . --always-allow --fast
ctx serve . # open http://127.0.0.1:8765/dashboard
On open (automatic): resolves a stable project id, indexes if needed (CTX_AUTO_INDEX=1), then keeps the index fresh every 5 minutes (changed files only — graph patch + embed together).
Project data
| Location | Role |
|---|---|
<repo>/.context-engine/id.json |
Tiny identity (project_id). Prefer gitignore. |
~/.context-engine/prefs.json |
Registration mode + indexing prefs |
~/.context-engine/projects/<project_id>/ |
Chunks, graph, merkle, embed cache |
~/.context-engine/registry.json |
Maps project_id ↔ paths, registered, always_allow |
~/.context-engine/vectordb/ |
FAISS + TurboQuant collections |
Path moved → id file recovers the store. Id file deleted → registry path recovers. Both gone → new id + reindex.
Layout
| Path | Role |
|---|---|
packages/pipeline/ |
Index, embed, FAISS+TurboQuant, MCP, sync |
packages/conductor/ |
Retrieval fusion (R_plan, etc.) |
packages/graphify/ |
Bundled AST / graph |
packages/enrich/, metadata/, repo_ir/ |
Chunk enrichment |
scripts/install* |
Setup + MCP install |
tests/ |
Unit / integration tests |
docs/ |
Design notes + ship notes |
See VENDOR.md and docs/compress-mix-shipped.md.
1 maintainer
Release files for scubiee 0.3.0
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.0.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| scubiee-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.1 MB
Release files / scubiee-0.3.0.tar.gz
| Download URL | scubiee-0.3.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9739b68c3f280601e8960bb9232799ffa15eb80e72891da9c038e959e5aa9984
|
|
BLAKE2b-256 checksum How to use checksums |
f21b2a6f162388f934497592abd9faafd85147a4d9e1d4ea342eac7a6210a220
|
| 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.0-py3-none-any.whl
| Download URL | scubiee-0.3.0-py3-none-any.whl |
|---|---|
| Size | 1.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a7c7b23dc2c401b1488ab0bb3f0ec73f765d97281dee0c02f7b7f5158f9147df
|
|
BLAKE2b-256 checksum How to use checksums |
a9f1aeaa1dec417eab71f6e3e5ae6ab85db939ad10ce04c7f0e69689e0d7257d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
