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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for UsmanSayed from gravatar.com UsmanSayed

Requires

Python >=3.10

Provides Extra

cpu coreml dml cuda macos mlx embed-st mcp

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

scubiee-0.2.87-py3-none-any.whl (1.0 MB view details)

Uploaded Python 3

File details

Details for the file scubiee-0.2.87-py3-none-any.whl.

File metadata

  • Download URL: scubiee-0.2.87-py3-none-any.whl
  • Upload date:
  • Size: 1.0 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.5

File hashes

Hashes for scubiee-0.2.87-py3-none-any.whl
Algorithm Hash digest
SHA256 f34bb723559d2fe41ab3d250542f79ab60709c7eea8b4aee5f031d35c2e21928
MD5 35bc0fc09ed343faf150e37ea7d2bc9e
BLAKE2b-256 d6d4b38ccce9820046565d8d53b398787b75e0beec51ad8c7453585582a7de1a

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.2.87 This release

1 file

0.2.86

2 files

0.2.85

2 files

0.2.84

2 files

0.2.82

2 files

0.2.81

2 files

0.2.80

2 files

0.2.79

2 files

0.2.78

2 files

0.2.77

2 files

0.2.76

2 files

0.2.75

2 files

0.2.74

2 files

0.2.73

2 files

0.2.72

2 files

0.2.71

2 files

0.2.70

2 files

0.2.69

2 files

0.2.68

2 files

0.2.67

2 files

0.2.66

2 files

0.2.65

2 files

0.2.64

2 files

0.2.63

2 files

0.2.62

2 files

0.2.61

2 files

0.2.60

2 files

0.2.59

2 files

0.2.58

2 files

0.2.57

2 files

0.2.56

2 files

0.2.55

2 files

0.2.54

2 files

0.2.53

2 files

0.2.52

2 files

0.2.51

2 files

0.2.50

2 files

0.2.49

2 files

0.2.48

2 files

0.2.47

2 files

0.2.46

2 files

0.2.45

2 files

0.2.44

2 files

0.2.43

2 files

0.2.42

2 files

0.2.41

2 files

0.2.40

2 files

0.2.39

2 files

0.2.38

2 files

0.2.37

2 files

0.2.36

2 files

0.2.35

2 files

0.2.34

2 files

0.2.33

2 files

0.2.32

2 files

0.2.31

2 files

0.2.30

2 files

0.2.29

2 files

0.2.28

2 files

0.2.27

2 files

0.2.26

2 files

0.2.25

2 files

0.2.24

2 files

0.2.23

2 files

0.2.22

2 files

0.2.21

2 files

0.2.20

2 files

0.2.19

2 files

0.2.18

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.7

2 files

0.2.6

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page