Scubiee
Local Context Engine: Merkle sync → Graphify AST → mix compress → CodeRankEmbed (MLX FP16 on Apple Silicon, FastEmbed CUDA/DirectML elsewhere) → TurboQuant/FAISS → Conductor R_plan
Install (no git clone)
Requires Python 3.10+. Two steps on a clean machine:
pip install -U scubiee
ctx setup
npm (optional wrapper — same pip install + ctx setup):
npm install -g scubiee
Then ctx init <repo> for each codebase, and reload MCP in Cursor (Settings → MCP → refresh).
ctx setup picks CUDA (NVIDIA), DirectML (Windows AMD/Intel), MLX FP16 (Apple Silicon Metal), CoreML (Intel Mac), or CPU. On a MacBook, pip install -U scubiee already installs FastEmbed, ONNX Runtime, and MLX — no [mlx] / [coreml] extra required. Then ctx setup (or ctx setup --repair after an upgrade) writes the MLX FP16 profile. Opt out: CTX_MLX=0 or ctx setup --profile cpu.
If PyPI is behind GitHub, install the tagged release:
pip install "scubiee @ git+https://github.com/Usmansayed/new-context-engine.git@v0.2.6"
ctx setup
From a git checkout (contributors only): pip install -e . then ctx 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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file scubiee-0.2.32.tar.gz.
File metadata
- Download URL: scubiee-0.2.32.tar.gz
- Upload date:
- Size: 969.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
615df88ccec827dd6ddf0af0be70fde38eaa4ea8102fad95875772405e38ba58
|
|
| MD5 |
571addf9f4e35efe36d16535edbeeed2
|
|
| BLAKE2b-256 |
f8570021bd8460125ed92e43c5c232880c06393f465618b57dc3074c9f432036
|
File details
Details for the file scubiee-0.2.32-py3-none-any.whl.
File metadata
- Download URL: scubiee-0.2.32-py3-none-any.whl
- Upload date:
- Size: 961.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2199c443f7f71a1eb2ccc76a775237e3984f5181a42f79ecf865d6d5bdd6d53a
|
|
| MD5 |
f79bb504322bcb65d0862755b90fa4a1
|
|
| BLAKE2b-256 |
16e5e61f755800035f6322de9f4ec403678bea6fe16110db3cd042bc10c6a916
|
