Everything you need to run and debug Scubiee.

Scubiee is a local context engine for AI coding tools (Cursor, Claude Code, Kiro, Copilot, and more). You need Python 3.10+. You do not need to clone the GitHub repo — install from PyPI.

It indexes your repository, embeds code with CodeRank (GPU when available), and exposes search / map / focus over MCP. Your source stays on your machine; only the embedding model downloads once during setup (~270 MB).

Scubiee runs a local daemon that maintains an index of each enrolled repository — parsed structure, chunks, embedding vectors, and graph relationships. A thin MCP server connects your AI tool. When the agent asks “where is billing handled?”, Scubiee returns ranked locations (map) and focused code spans (focus) — not guessed filenames. Incremental sync keeps the index fresh after edits and git pull.

The four layers

Most problems mean one layer is missing or stale. Why agents say managed: false: layer 3 or 4 is missing — not a broken index by itself.

Memorize this sequence

• init does not write MCP. After init you still need connect.
• setup alone does not make a repo managed. You still need init inside the project.
• Adding a second repo only needs init (and Special-4 connect inside that project).

Core concepts

Managed states

• Unmanaged — never initialized; use native tools
• Managed / active — enrolled and indexed; MCP tools available
• Paused — enrolled but sync blocked; run scubiee activate .
• Wiped — all Scubiee data removed; back to unmanaged

The problem without Scubiee

• Discovery noise — agents grep broadly, read wrong files, or hallucinate paths.
• Stale context — files changed since the chat started; the agent does not know.
• No shared index — every session re-explores the repo from scratch.
• Cloud search tradeoffs — uploading code raises privacy and compliance concerns.
• DIY RAG complexity — embeddings, chunking, incremental sync, and MCP wiring takes weeks.

Profile selection (why setup picks a profile)

What the daemon does

A local HTTP service (default http://127.0.0.1:8765) serves search, grep, and index operations to MCP and CLI. It runs background sync for enrolled repos, respects RAM admission and embed batching, and is restarted by a lightweight watchdog if it crashes. A small local service keeps your index warm and answers search requests in milliseconds.

Time expectations

Facts any assistant needs

Paste this page (or the topic you care about) into ChatGPT / Claude / etc. These facts prevent wrong advice:

• Product CLI + MCP server key = scubiee (not “context-engine”).
• Data lives under ~/.scubiee and <repo>/.scubiee.
• Order is always setup → init → connect → reload MCP. Skipping connect leaves agents unmanaged.
• Continue after pause/stop with scubiee resume — there is no wake command.
• Windows Access denied on upgrade → scubiee unlock-tool, not Admin/reboot.
• machine_not_setup / missing FastEmbed → scubiee setup --repair.
• Share scubiee diagnose --no-tests --desktop → Desktop/scubiee-diagnose.json (not your source tree).

Correct order matters. init does not write MCP config — connect does. Then reload MCP in the IDE.

macOS / Linux

uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
uv tool update-shell
# open a new terminal
scubiee setup
cd your-repo
scubiee init .
scubiee connect --cursor
# reload MCP in your IDE

Windows (PowerShell)

uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
uv tool update-shell
# open a NEW PowerShell window
scubiee setup
cd C:\path\to\your\repo
scubiee init .
scubiee connect --cursor
# Cursor → Settings → MCP → refresh

Prefer uv tool install over pip on Windows — clearer upgrades and fewer PATH collisions. Always pin --index-url https://pypi.org/simple on Windows. On Windows, shims usually live in %USERPROFILE%\.local\bin — run uv tool update-shell then open a new terminal.

What setup does

• Detects hardware (CUDA, DirectML for discrete AMD/NVIDIA, MLX on Apple Silicon, or CPU)
• Installs the correct ONNX Runtime + FastEmbed stack
• Downloads the CodeRank FP16 embedding model (~270 MB, cached)
• Calibrates embed batch size and saves ~/.scubiee/accel.json

After a broken / forced reinstall: always run scubiee setup --repair before init. First-time happy path can use plain scubiee setup; use --repair after upgrades or when deps look missing.

Verify

scubiee --version
scubiee setup --status
scubiee doctor .
scubiee search "a symbol in your repo" .
scubiee diagnose --no-tests --desktop

scubiee --version prints which Python runs Scubiee — prefer the uv tool path (…\uv\tools\scubiee\Scripts\python.exe on Windows). In the agent, call MCP status() once. Expect managed: true, ok: true after init + connect + reload.

Once setup, init, and connect are done, these are the commands you use day to day.

Typical workflow

cd your-project
scubiee status .          # index health + sync state
scubiee sync .            # after git pull / large edits
scubiee search "AuthService" .

Keep the index fresh

Multiple repos

scubiee list
scubiee activate /path/to/repo
scubiee pause /path/to/repo --reason "maintenance"
scubiee remove /path/to/other --delete-store

Stop / resume (machine-wide)

scubiee stop      # stop engine, free GPU / file locks
scubiee resume    # bring Scubiee back — NOT "wake"

Consent / auto modes

scubiee settings --show
scubiee settings --mode automatic   # IDE open → register + index
scubiee settings --mode mcp_cli     # first MCP use asks consent

Prefs file: ~/.scubiee/prefs.json.

Engine & dashboard

scubiee engine status .
scubiee engine ensure . --wait 45
scubiee dashboard --status
scubiee dashboard --no-open
scubiee resources

Engine logs: ~/.scubiee/engine.log, ~/.scubiee/watchdog.log. Dashboard port is dynamic — use --status for the URL.

Useful environment variables

Connect installs MCP configuration and agent rules so your coding tool uses Scubiee for retrieval instead of random greps. Prefer connect after every upgrade so rules and project pins stay current.

setup vs init vs connect

scubiee connect --cursor
scubiee connect --claude-code
scubiee connect --codex
scubiee connect --cursor --dry-run
scubiee connect --all --dry-run
scubiee disconnect --cursor

Cursor workspace pin (critical)

Cursor does not expand ${workspaceFolder} in global ~/.cursor/mcp.json. A literal token makes MCP resolve to your home folder → managed: false.

• Always run scubiee connect --cursor from the project you want managed.
• That writes project .cursor/mcp.json with an absolute CTX_REPO pin.
• Global MCP entry should not use unexpanded workspace tokens for CTX_REPO.
• After connect: Cursor → Settings → MCP → refresh (or restart Cursor) until the scubiee server shows green.
• On Windows, MCP should run via the uv tool shim (%APPDATA%\uv\tools\scubiee\Scripts\…), not a random conda Python.

Multiple repos in one Cursor app

One MCP process is shared across chats. A pin must not make an unindexed sidebar repo look managed.

• On status() (and later locate tools), pass root = that chat’s Workspace Path.
• Managed is true only if that folder (walking up) has .scubiee/id.json and is in the registry.
• Other chats: managed: false after one status() — use native tools; do not keep calling Scubiee.
• After a successful status(), you may pass project_id (ce_…) instead of the full path.

Special-4 (per-repo connect)

These hosts do not resolve the open folder from user-global MCP alone. Run connect inside each project:

All supported tools (13)

• Cursor--cursor
• Claude Code--claude-code
• Codex--codex
• Kiro--kiroper-repo
• Windsurf--windsurf
• GitHub Copilot--copilotper-repo
• Cline--clineper-repo
• Roo Code--roo-codeper-repo
• Continue--continue
• Zed--zed
• OpenCode--opencode
• Amp--amp
• Pi--pi

Disconnect with scubiee disconnect --<flag>. MCP cannot start or wrong Python? Re-run connect for that tool, or setup --repair, then reload MCP.

Full integrations reference

Connect commands

Agent rule behavior

connect installs rules that: (1) call status() once at session start; (2) if managed + ok → use Scubiee tools; (3) if warming → use tools, do not poll status() every turn; (4) if unmanaged → native tools; retry status() only after user runs init/connect. Paused/stopped → user runs scubiee resume.

Agents should call status() once at session start — not every turn. The MCP server key in mcp.json is scubiee. It talks to the local daemon (default http://127.0.0.1:8765).

What the agent rule expects

1. Call status() once at session start (pass root = workspace path when several repos share one MCP)
2. If managed + ok → use Scubiee tools for discovery (map / grep / focus), not native Grep / find by default
3. If warming → use tools; wait ~5s and retry the tool once; do not busy-loop on status()
4. If unmanaged → native tools; retry status() only after you run init/connect
5. If paused/stopped → run scubiee resume (not wake)

Tool catalog (phase surface)

Recommended agent flow

1. status(root=<workspace path>)     # once
2. map(query="auth middleware")    # find areas
3. focus(...)                        # deepen a hit
4. grep(pattern="AuthService")      # exact text if needed
5. Read/Edit only the lines you need

• Empty grep/glob with truncated: false means no match in indexed scope — not “file missing on disk.”
• After mid-session init, ask the agent to call status() once again.
• Stale results after large edits: run scubiee sync . (or wait for background refresh), then search again.
• Tip: put a unique string in a .py file in scope, sync, then search to verify the index.
• If the agent ignores MCP forever: MCP green? → scubiee connect --cursor (refreshes rules) → reload MCP → ask it to call status() once.

What connect writes for the agent

connect / setup install a Cursor rule at ~/.cursor/rules/scubiee.mdc that encodes the status → managed → Scubiee tools policy above. Re-run connect after upgrades so the rule matches the installed CLI.

Most Windows failures are file locks from Cursor MCP / the daemon holding %APPDATA%\uv\tools\scubiee — not ACL permissions. Admin PowerShell does not help. Reboot only works because it kills the locker — use unlock-tool instead.

Access denied on upgrade / reinstall

Symptom: uv tool install --force cannot overwrite Scripts; later No module named 'pipeline'.

scubiee unlock-tool
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
scubiee setup --repair
scubiee connect --cursor

unlock-tool turns MCP off (so Cursor cannot respawn), stops lockers, and frees the tool directory. Prefer scubiee upgrade when the CLI still works — it unlocks before swapping the package.

CLI already broken

If scubiee itself cannot start, use the repair scripts from the repo (or download them), then reinstall:

powershell -ExecutionPolicy Bypass -File scripts/uninstall-uv-scubiee.ps1
# or:
powershell -ExecutionPolicy Bypass -File scripts/repair-uv-scubiee.ps1
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
scubiee setup --repair

Do not lead with reboot or raw Remove-Item while Cursor is open — partial deletes leave No module named 'pipeline'.

Important paths

Embedding model: nomic-ai/CodeRankEmbed (~270 MB FP16 on GPU, ~132 MB INT8 on CPU). Requirements: Python 3.10+, ~500 MB–1 GB disk. Network only for install + model download. HuggingFace is only needed once — MCP works offline after.

Current Scubiee ignores Intel iGPU / AMD APU for DirectML so setup does not hang. Apple Silicon should show mlx after repair — not stay on CPU.

scubiee setup --status
scubiee setup --profile cpu --repair    # force CPU
scubiee setup --profile dml --repair    # discrete AMD escape hatch
scubiee setup --profile mlx --repair    # Apple Silicon
scubiee setup --profile cuda --repair   # Linux NVIDIA

Provider profiles

Embedding model: nomic-ai/CodeRankEmbed (FP16 on GPU paths). Setup auto-detects the best profile; force one only when auto-detection is wrong.

Model files by profile

CPU profiles use a dual thread budget: 35% of cores for bootstrap/full reindex, 15% for background sync — so indexing stays invisible during active coding.

Always cd into the project root before init. Scubiee uses the current directory as the root — do not run bare init from your home folder. Indexes stay on your machine under ~/.scubiee (never leave the device except the one-time embedding model download during setup).

Where data lives

MCP key is scubiee. Fresh installs do not use or migrate .context-engine. Daemon HTTP is localhost-only; MCP is stdio to your IDE.

Init flags

cd your-repo
scubiee init .
scubiee init . --fast                       # .py under common roots
scubiee init . --fast --roots packages,src   # large monorepo
scubiee init . --confirm                     # when >400 files
scubiee init . --no-index                    # register only
scubiee sync .                               # after git pull / edits
scubiee search "query" .
scubiee list

Fast mode indexes only .py under common roots (packages, src, lib, app, …) or your --roots list. Use it for a first pass on large monorepos. Default full index still skips vendor, node_modules, .git, etc.

• Refusing to index home / drive root

  Cause: Safety — Scubiee will not silently index C:\\Users\\you, /Users/you, C:\\, or /

  cd into your project, then scubiee init .. Only use --confirm on a broad path if you truly mean it.

• >400 files need indexing

  Cause: Safety gate on large first index / sync

  Re-run with --confirm, or scope with --fast --roots …. Power users can raise the cap with CTX_INCREMENTAL_MAX_TOUCH.

• never_index error

  Cause: Path was blocked with scubiee never-index

  Clear via dashboard forget / lifecycle remove. Block intentionally with scubiee never-index . --reason "…".

• project_id_mismatch / stale home registration

  Cause: Home folder was enrolled earlier by mistake

  Copy

  scubiee list
  scubiee remove C:\Users\YOUR_USER --delete-store
  # delete leftover id.json under home if present

• Search misses fresh edits

  Run scubiee sync .. Test with a unique token in a .py file that is in scope, then search for that token.

Repo lifecycle

Wipe removes Scubiee's index and config, not your Git working tree.

scubiee resume is machine-wide. scubiee activate . unpause a single repo. There is no wake command.

When anything fails, run this triage order before guessing. Share Desktop/scubiee-diagnose.json when opening an issue.

scubiee --version
scubiee setup --status
scubiee preflight .
scubiee doctor .
scubiee list
scubiee diagnose --no-tests --desktop

If semantic preflight fails: scubiee setup --repair, then retry. If the daemon is cold: scubiee engine ensure . --wait 45.

Commands that matter for install health

Then match your symptom below.

scubiee setup --repair
scubiee setup --status
scubiee init .

scubiee setup --repair
scubiee diagnose --no-tests --desktop
scubiee init .

scubiee upgrade
# or manually:
scubiee unlock-tool          # Windows if Access denied
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
scubiee setup --repair
scubiee connect --cursor     # refresh MCP + rules after every bump

Error codes reference

When JSON shows error or exit code is non-zero, match the code below. Full context: symptom → why → fix.

Setup & machine

Enrollment & path

Lifecycle

MCP / engine status fields

Doctor install identity (0.3.13+)

Diagnose JSON — what to check

• What is Scubiee?

  A local code context engine that indexes your repositories and connects to AI coding tools via MCP — semantic search, graph-aware retrieval, and live re-indexing on your hardware.

• Do I need to clone the GitHub repo?

  No. Install from PyPI with uv tool install scubiee.

• What Python version?

  3.10 or newer.

• What's MCP?

  Model Context Protocol — a standard way for AI assistants to call external tools like semantic search. Scubiee registers as server name scubiee in mcp.json.

• Which AI tools work?

  Cursor, Claude Code, Copilot, Kiro, Cline, Roo Code, Continue, Zed, OpenCode, Amp, Pi, Windsurf, Devin Desktop, and more — see Connect agents.

• Does init connect Cursor?

  No. connect writes MCP + rules. init only enrolls/indexes the repo.

• uv or pip?

  Prefer uv tool install — isolated CLI, clearer upgrades on Windows.

• Why setup --repair?

  Safest after fresh install, upgrade, or broken reinstall. Installs missing FastEmbed/ORT extras and refreshes accel.json.

• Where is the embedding model?

  Downloaded during setup (~270 MB FP16 CodeRank). Cached under FastEmbed cache dirs (~/.cache/fastembed/ and related).

• Does my code leave the machine?

  No — indexing and search are local. Only the embedding model downloads during setup.

• Does MCP work offline?

  Yes after setup. HuggingFace is only needed once for the model download.

• How do I remove a repo from Scubiee?

  scubiee wipe . --confirm — deletes Scubiee data (index, .scubiee, repo MCP/rules), not your source files.

• How do I uninstall completely?

  scubiee stop → quit IDE → unlock-tool (Windows) → wipe --all --confirm --package. Re-run until audit.remaining is empty.

• Why does Cursor say managed: false?

  Run scubiee init . and scubiee connect --cursor from the project, then reload MCP.

• How do I share diagnostics?

  scubiee diagnose --no-tests --desktop → send Desktop/scubiee-diagnose.json.

• Agent still uses native Grep?

  Confirm MCP is green, re-run connect to refresh rules, then ask the agent to call status() once.

• Access denied on Windows upgrade?

  scubiee unlock-tool → reinstall → setup --repair. Not Admin/reboot.

• No module named 'pipeline'?

  Half-deleted uv tool env — unlock-tool or scripts/repair-uv-scubiee.ps1, then reinstall + setup --repair.

• Windows laptop with only Intel UHD / AMD APU?

  Use cpu profile (not DirectML). Discrete AMD/NVIDIA → dml. Verify with setup --status.

• Apple Silicon stuck on CPU?

  Default should be mlx (Metal). Run setup --profile mlx --repair.

• status() shows warming?

  Daemon is starting. Retry the MCP tool once after a few seconds — do not poll status() every turn.

• What does --fast / --confirm do?

  --fast indexes .py under common roots (or --roots). --confirm is required when >400 files would be touched.

Run scubiee <subcommand> --help for flags on your installed version.

Setup & indexing

scubiee setup
scubiee setup --repair
scubiee setup --status
scubiee setup --profile cpu --repair
scubiee init <path>
scubiee init . --fast --roots packages,src
scubiee init . --confirm
scubiee init . --no-index
scubiee search "query" <path>
scubiee sync <path>
scubiee sync . --confirm
scubiee rebuild .
scubiee status <path>
scubiee list

Connect & lifecycle

scubiee connect --cursor
scubiee connect --all --dry-run
scubiee disconnect --cursor
scubiee stop
scubiee resume
scubiee pause .
scubiee activate .
scubiee upgrade
scubiee unlock-tool
scubiee remove <path> --delete-store
scubiee never-index . --reason "…"

Diagnostics & engine

scubiee doctor <path>
scubiee doctor . --fix
scubiee doctor --all
scubiee preflight .
scubiee preflight . --lexical-only
scubiee diagnose --no-tests --desktop
scubiee engine ensure . --wait 45
scubiee engine status .
scubiee dashboard --status
scubiee resources
scubiee migrate --check-all

Mental model — three programs, four layers

Scubiee is local software — not a cloud API and not an IDE extension. Three processes share one Python package (pipeline module from uv tool or pip):

init = layer 3 only. Without connect (layer 4), agents show managed: false. connect without setup + init leaves MCP with nothing to search.

Recommended workflows

First-time install

uv tool install --force scubiee==0.3.14 --index-url https://pypi.org/simple --refresh
scubiee setup --repair
cd /path/to/your/repo
scubiee init .
scubiee connect --cursor
# Reload MCP in IDE
scubiee doctor .
scubiee status .

Daily development

Usually nothing — daemon and background sync keep indexes fresh. When needed:

scubiee sync .              # after git pull or large edits
scubiee status .            # freshness / chunk counts
scubiee search "auth middleware" .

After every upgrade

scubiee upgrade
scubiee setup --repair        # if doctor shows missing ORT/fastembed
scubiee connect --cursor      # refresh MCP env + rules
# Reload MCP
scubiee doctor .

CI / automation

scubiee preflight . || exit 1
scubiee init /repo --confirm --fast --roots packages,src
scubiee certify /repo --skip-daemon
scubiee test quick /repo

Exit codes & JSON output

Piped/non-TTY commands emit JSON on stdout. Use scubiee status --json to force JSON on a terminal. Common fields: ok, error, hint, needs_confirm, deferred.

Safety gates (--confirm)

Scubiee refuses to silently index home, drive root, or trees with >25,000 indexable files (counts indexable files with skip rules — not raw disk count). Commands: init, sync, sync-now, register. Narrow scope with init . --fast --roots packages,src.

Command categories

Global stop vs per-repo pause

Common mistake: per-repo pause but agent says run resume — that is global. Per-repo needs activate .. connect and setup --repair auto-resume if globally stopped.

Full command index

Environment variables

Connect writes most MCP env vars into IDE config — you rarely set them manually.

Command relationships

Enrollment: init vs register vs initialize

Indexing: index vs sync vs sync-now vs rebuild

Rule: daily edits → sync. Corruption / model change → rebuild. First time → init.

Cleanup: remove vs wipe

Lifecycle decision matrix

Commands allowed when globally stopped

connect and setup --repair auto-resume if globally stopped. Help (-h / --help) always works.

Symptom → command FAQ

Install & setup

IDE / MCP / index

Full machine cleanup when you want Scubiee gone. Indexing and search are local — your code never leaves the machine; wipe only deletes local state (and optionally the package). On Windows, free locks first — raw uv tool uninstall while MCP is running often fails with Access denied and can leave a half-deleted env (No module named 'pipeline').

What wipe removes

• Machine home ~/.scubiee (registry, indexes, accel, logs)
• Per-repo <repo>/.scubiee/ markers
• Cursor MCP + rules (~/.cursor/mcp.json, ~/.cursor/rules/scubiee.mdc, project pins)
• With --package: the uv/pip scubiee install
• With --keep-models: keep the CodeRank / FastEmbed download cache

Recommended (all platforms)

scubiee stop
# quit Cursor / disable MCP
scubiee unlock-tool          # Windows — free uv tool locks
scubiee wipe --all --confirm --package

Read JSON audit.remaining. Re-run until clean. Then reload Cursor so MCP picks up the new state. --yes is an alias of --confirm.

Wipe flags

Repo-only wipe

cd /path/to/repo
scubiee wipe .
# or
scubiee remove . --delete-store

CLI already broken (Windows)

powershell -ExecutionPolicy Bypass -File scripts/uninstall-uv-scubiee.ps1
# or repair + reinstall:
powershell -ExecutionPolicy Bypass -File scripts/repair-uv-scubiee.ps1
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
scubiee setup --repair

Mac / Linux if CLI is gone

rm -rf ~/.scubiee
# edit ~/.cursor/mcp.json — remove "scubiee" from mcpServers
uv tool uninstall scubiee

Share diagnostics (not your code)

scubiee diagnose --no-tests --desktop
# → Desktop/scubiee-diagnose.json (machine/profile health only)
# optional: short tail of ~/.scubiee/engine.log

Scubiee 0.3.14 is a local repository-context service with three faces: a CLI for setup and lifecycle, a daemon/runtime that owns indexing and retrieval, and an MCP adapter your IDE talks to. The central contract: a coding tool may use Scubiee when the repo is managed and healthy; otherwise it falls back to native tools. Your code never leaves your machine for search — only the embedding model downloads once during setup (~270 MB FP16 or ~132 MB INT8 on CPU).

System diagram

Repository lifecycle states

What connect writes

Machine setup — what it does

1. Detects hardware — CUDA, DirectML, MLX, or CPU fallback
2. Installs runtime wheels — FastEmbed, ONNX Runtime for profile
3. Downloads CodeRankEmbed (~270 MB FP16) via HuggingFace/FastEmbed cache
4. Calibrates embed throughput → batch size in accel.json
5. Does not scan repos, write MCP, or index without init

Why setup --repair: upgrades and broken Windows reinstalls leave stale accel.json while ORT wheels were deleted. Repair re-runs detection and pip installs.

Init — what it does

1. Validates path — refuses $HOME, C:\, / (safety)
2. Assigns or reads project_id (ce_…) in id.json
3. Updates registry.json
4. Runs index pipeline: scan → parse → graph → chunk → embed → FAISS
5. Starts or attaches daemon for this repo

Fast mode: only .py under standard roots or --roots. Confirm gate: >400 indexable files. One project id can map to multiple checkout paths (worktrees).

Search stages (MCP phase surface)

grep/glob search the index, not every file on disk if never indexed. Why search misses new code: file out of scope, sync not run, or wrong repo in multi-root Cursor.

Upgrades (0.3.14+)

scubiee upgrade: unlocks Windows locks → stops processes → swaps package → runs migration plan → restarts daemon. Always follow with setup --repair if diagnose shows missing libs, and connect to refresh MCP/rules.

Features in depth

Full index sequence

repository admission → capability/provider validation → Merkle scan and diff baseline → Graphify parsing and RepoIR → graph construction → symbol/file chunk generation → metadata enrichment and compression → CodeRankEmbed embeddings → FAISS/TurboQuant vector write → chunks + Merkle + metadata + manifest publication

Each phase has a different failure boundary. Admission and capability checks happen before expensive work. Embedding is performed only after the chunk set is known. Artifacts are published as a coherent index generation.

Retrieval path

query → capability/search readiness → BM25 lexical candidates → dense FAISS candidates → Graphify structural affinity → RRF or min-rank fusion → graph/context expansion → final hits

WarmSearchEngine is the readiness boundary. A cold dense index surfaces through status/ capability info instead of being mistaken for healthy semantic search.

Product identity

Engineering components

MCP surfaces

Selected via CTX_MCP_SURFACE. Default is phase — optimized for map → focus → grep workflow.

MCP tools — agent benefits

Global rule contract

call status() once
if managed == true and ok == true:
    use Scubiee discovery tools
else:
    ignore this Scubiee rule for the rest of the session
    use native search/read tools

The rule does not authorize indexing or writes — only discovery routing. Enrollment and destructive lifecycle actions remain explicit CLI operations.

Model precision & CPU thread budget

CPU thread budget: bootstrap/full reindex uses 35% of cores (min 2); background incremental sync uses 15% (min 1). GPU profiles set threads=1 and offload to GPU.

Incremental sync environment defaults

Failure modes

Identity & Git worktrees

A repository is identified by evidence from: in-repo .scubiee/id.json, trusted registry, per-project store, Git common directory/worktree family, and current path + Git metadata. A Git worktree may have a .git pointer file — the resolver uses Git common-directory evidence without rejecting worktrees. When a repo moves or has duplicate ID evidence, prefer scubiee init over manually editing IDs.

Operator runbook

# First install
uv tool install --force scubiee==0.3.14 --index-url https://pypi.org/simple --refresh
scubiee setup --repair
scubiee preflight
scubiee init . && scubiee connect --cursor
# Health check
scubiee doctor . --all
scubiee resources --refresh
# Stale index
scubiee sync .
scubiee sync-now .
scubiee rebuild .
# Repair
scubiee setup --repair
scubiee doctor --all --fix
scubiee migrate . --check-all

Privacy & security

• Code stays local — indexing, embedding, and search run on your machine. There is no Scubiee-hosted repository upload service.
• Model download only — HuggingFace/FastEmbed model fetch during setup (~270 MB FP16 or ~132 MB INT8 on CPU). After that, offline search works.
• You control deletion — scubiee wipe removes local indexes and metadata; wipe --all --confirm audits leftovers honestly.
• Open install — package on PyPI; inspectable CLI and local data under ~/.scubiee.

Honest footnotes

• Your AI tool (Cursor, Copilot, etc.) may still send code to its own model provider — that is separate from Scubiee.
• Scubiee writes MCP config and rule files into IDE config directories; those files contain paths, not your source code.
• scubiee diagnose output may include paths and versions for support — review before sharing.

Who Scubiee is for

Not the primary audience: teams wanting hosted multi-user cloud search, single-file editors with no cross-repo discovery, or environments where Python 3.10+ and ~300 MB model cache is impossible.

Data & storage paths

CTX_VECTORDB_ROOT can override the default vector root. Legacy .context-engine paths are not used. Override home with CTX_HOME (advanced/testing only).

~/.scubiee/ — full map

Index store artifacts

Under projects/<project_id>/: meta.json, Merkle/manifest, chunk store, graph, FAISS vectors, lexical index. Size scales with indexed source. Deleting id.json but keeping registry may allow recovery on next init; deleting both creates new ce_… id → full re-index.

Install locations & MCP files

uv tool: Windows %APPDATA%\uv\tools\scubiee\, Unix ~/.local/share/uv/tools/scubiee/ — contains Scripts/python.exe MCP uses. MCP configs: Cursor global + project .cursor/mcp.json; Kiro/Copilot/Cline/Roo project-local files. Wipe repo removes project-local; wipe --all removes global MCP too.

Environment variables

What delete/wipe removes

Storage invariants

• Repository identity and registry state must agree for daemon routing.
• A denied or never-indexed repository must not receive an automatic index.
• Provider and capability checks must pass before embedding/publishing work.
• Retrieval must use a consistent published generation — not partial writes.
• Incremental changes must update Merkle, chunk, metadata, graph, and vector state together or escalate to a full rebuild.
• A daemon bound to one repository must not silently answer a request for another repository.
• Removing a repository store and wiping all machine data are explicit operations — not side effects of search or status.

Setup & indexing commands

Diagnostics & lifecycle commands

CLI command tree

Issue cheatsheet

Comparisons

vs native IDE search / agent grep

vs cloud code intelligence

vs build-your-own RAG

Terminology & brand rules

Use-case stories

• Security-conscious team — approved because nothing leaves the laptop; model download was the only outbound call.
• Monorepo developer — map('billing webhook handler') pointed the agent at the right package first try.
• Windows laptop user — CPU profile avoided the DirectML hang on Intel graphics.
• Multi-IDE user — same index served Cursor and Copilot after connect in each workspace.
• Upgrade survivor — unlock-tool + setup --repair fixed Access denied without reinstalling Windows.

Support bundle

scubiee --version
scubiee setup --status
scubiee doctor .
scubiee diagnose --no-tests --desktop
# → Desktop/scubiee-diagnose.json (paths + versions, not source code)