codecortex 0.2.0__py3-none-any.whl

codecortex-0.2.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: codecortex
+Version: 0.2.0
+Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
+Author: Shammai Hamilton
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hamilton-sky/codeintel
+Project-URL: Repository, https://github.com/hamilton-sky/codeintel
+Project-URL: Issues, https://github.com/hamilton-sky/codeintel/issues
+Project-URL: Changelog, https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,code-intelligence,code-search,llm,agents,lsp,semantic-search,knowledge-graph,static-analysis,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: fastembed>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
+Dynamic: license-file
+
+# codeintel
+
+A unified code-intelligence gateway — graph + LSP + semantic — that gives any coding agent a single safe API to search, trace, and understand any codebase.
+
+[![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
+
+## Quickstart
+
+```bash
+pip install codecortex
+```
+
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
+and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
+run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
+
+Or from source:
+
+```bash
+git clone https://github.com/hamilton-sky/codeintel.git
+cd codeintel
+pip install -e .
+```
+
+Register with your AI agent(s):
+
+```bash
+codeintel install            # registers with Claude, Codex, Gemini, Zed
+```
+
+Index a project, check what's ready, and run your first query:
+
+```bash
+codeintel index /path/to/your/project
+codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
+codeintel query --op search --target "authentication middleware"
+```
+
+## How it works
+
+A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
+
+```mermaid
+flowchart LR
+    A["AI agent · MCP"] --> GW
+    H["Harness · HTTP"] --> GW
+    C["Developer · CLI"] --> GW
+    GW["Gateway<br/>route · cache · safe-null"] -->|"auto: search"| SP[SemanticProvider]
+    GW -->|"auto: impact / callers / …"| GP[GraphProvider]
+    GW -->|"auto: symbol"| LP[LspProvider]
+    GP --> GB[("codebase-memory-mcp")]
+    LP --> LB[("language server")]
+    SP --> SB[("fastembed + sqlite-vec")]
+```
+
+> Full walkthrough: **[docs/architecture.md](docs/architecture.md)** · **[docs/query-flow.md](docs/query-flow.md)**.
+
+## Safe-null contract
+
+Every `Gateway.query()` call returns a dict with exactly these keys:
+
+```json
+{"ok": true, "op": "search", "target": "auth", "result": null, "engine": "semantic", "cached": false}
+```
+
+`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. An optional `reason` key explains null results (e.g. `"engine-unavailable"`, `"no-result"`). Callers must check `result is not None` before using the value.
+
+## Engines
+
+| Engine | Key ops | Install prereq |
+|---|---|---|
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` CLI on PATH — see [docs/graph.md](docs/graph.md) |
+| `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
+| `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
+
+Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
+
+Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
+
+## Documentation
+
+Full system docs live in [`docs/`](docs/) — start with the index:
+
+- **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
+- **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
+- Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
+
+## CLI reference
+
+| Command | Purpose |
+|---|---|
+| `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
+| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `codeintel index [project_root]` | Index a project for semantic search |
+| `codeintel serve` | Start the MCP server (stdio transport) |
+| `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote]` | Start the HTTP transport (loopback-only unless `--allow-remote`) |
+| `codeintel query --op OP --target TARGET [--engine auto]` | Run a single query and print the result |
+| `codeintel status [project_root]` | Show engine availability and index age |
+| `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
+| `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
+| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+
+Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
+
+## Config
+
+Create `.codeintel.toml` at your project root to override defaults:
+
+```toml
+backend      = "auto"                   # auto | graph | lsp | semantic
+semantic     = "on"                     # on | off
+reindex      = "on-demand"              # on-demand | never
+cosine_floor = 0.25                     # minimum similarity score for semantic hits
+max_chunks   = 500                      # max chunks to embed per project
+model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
+```
+
+## Privacy & dependencies
+
+**codeintel is local-first** — one local process, no cloud service, no API keys, no telemetry, and no per-query network. Its own code makes zero outbound HTTP calls, and the HTTP transport binds to `127.0.0.1` only.
+
+**Bundled (installed with the package, run locally):** `mcp` (the tool interface) · `sqlite-vec` (the semantic index, a local DB file) · `fastembed` (the local embedding model).
+
+**Optional external backends** — auto-detected on `PATH`; if one is absent, that engine returns a safe-null and the agent simply degrades to grep:
+
+| Engine | Needs on `PATH` | Third-party? |
+|---|---|---|
+| `graph` | `codebase-memory-mcp` | yes — external CLI |
+| `lsp` | `uvx` (fetches & runs serena from GitHub on first use) | yes — [oraios/serena](https://github.com/oraios/serena) |
+| `semantic` | *nothing external* | no — fully in-house |
+
+Not sure what's installed? `codeintel doctor` reports exactly which backends are present, whether this repo is indexed, and the command to fix each gap.
+
+**The only network touch is first-run setup:** `fastembed` downloads the `BAAI/bge-small-en-v1.5` weights once (cached under `~/.cache`, fully offline thereafter); the optional backends also install on first use *if you opt in*. After that, **no code or data leaves your machine** — which is what makes `--engine all` safe to run on a private repo.
+
+## For agents
+
+Start the HTTP server, then POST queries to `/code/query`:
+
+```bash
+codeintel serve-http &   # listens on 127.0.0.1:8766 by default
+```
+
+```python
+import urllib.request, json
+
+def code_query(op: str, target: str, engine: str = "auto") -> dict:
+    body = json.dumps({"op": op, "target": target, "engine": engine}).encode()
+    req = urllib.request.Request(
+        "http://127.0.0.1:8766/code/query",
+        data=body,
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+result = code_query("search", "authentication middleware")
+if result["result"] is not None:
+    print(result["result"])   # ranked semantic matches
+```
+
+The response is always JSON-safe. Check `result["result"] is not None` before use. Never catch an exception from the gateway — it never raises.
+
+## Development
+
+```bash
+git clone https://github.com/hamilton-sky/codeintel.git
+cd codeintel
+pip install -e .[dev]
+pytest tests/ -q            # full suite, ~1s
+```

codecortex-0.2.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+codecortex-0.2.0.dist-info/licenses/LICENSE,sha256=DIRvhlH8EulEUOYQxKDFFiimJrlVT5-kCKxQIgi2m7c,1073
+codeintel/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+codeintel/__main__.py,sha256=3MpEhdpAfHiO0rwIB7hxXM_mDN3RovPQBLXNH36aLUg,15189
+codeintel/cache.py,sha256=MvZjxK899I-qUH1emLySII03cgT-d6ucxIOCOfjlNVM,2107
+codeintel/config.py,sha256=Q7Mgq3UleJO6cpBKr1S7I1SeRbyL_rDekmCi8iasy9s,1133
+codeintel/doctor.py,sha256=jiPuZzS801xfWwTyeVO9UHUxQqAJ-YqTlX-_epZfoyI,6659
+codeintel/gateway.py,sha256=1c0rtjGGcgaa63Klk79LtdeOTl2ld8cvcnFlRSpKNsg,8929
+codeintel/http_server.py,sha256=NH07e3uq7hp8H3e6ghmjeUx6TyWJ1a1A8CNZf3XRuLw,3543
+codeintel/indexer.py,sha256=QKQtVu79DsEf1qSj9pLSdrspy5ajgzuNmupaZFL128s,9578
+codeintel/injector.py,sha256=UGj5luzPJ-oX50Ks6BbZ2O2ChdDq4cOFway6OB2d4co,2521
+codeintel/installer.py,sha256=RhVTB-J-YM4f0SpYiTVd5Ztb9E2SKxrJgpUBuorzJ6A,3014
+codeintel/mapper.py,sha256=JN-lMO1CXIyDKSwHfzp0JuK396FR41XhFgtAip77G0E,7493
+codeintel/onboarding.py,sha256=TOpRKkFvN2UesA7lW233s5PUJTFj98i7sby953EGWIQ,8846
+codeintel/policy.py,sha256=mUAlk9oYoszQLEcvoroFLRd9DSTzho7YcbM7xb6RS-k,935
+codeintel/provider.py,sha256=SlIModATCANJA4VyJs_Rz24bpQfzHG8ljHfpS1LWa8c,1214
+codeintel/reindexer.py,sha256=zFNeLgPRZPfeczc5Cx3aPYkJpyrjd6AHyvuqsrLGf8E,4443
+codeintel/reset.py,sha256=8Mpak4Tj5e-yTcM3_EnZJzbJPwPV2o8xpxGjv-wk9EE,3675
+codeintel/searcher.py,sha256=R9PV7jSx-GO--qmh65FXlYxpbKbjCnxV-EF9hGe8hZU,4588
+codeintel/semantic_db.py,sha256=m6s8aN7_KJOUSuu_1kNNHu6ZocqzEWTVAa8Y6xBO140,2661
+codeintel/server.py,sha256=9eo531Hj1XZYz3I6Zx2DQZ-fsYPYtmIRJH2TTe5yRjo,7031
+codeintel/term.py,sha256=csbSYD8euC13FnnpThy8kylDgZeejQ6j6Ol6Gu21Clo,6819
+codeintel/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codeintel/providers/graph.py,sha256=0nj7P2ncTkm68ITxMkti3ZOPfvoIpEPyTLdyGQ7efnI,18916
+codeintel/providers/lsp.py,sha256=3jn2bMfo5jiaL4_X3kIjzzxLsL475xIZsT-okWy-vgg,16759
+codeintel/providers/none.py,sha256=VI84XQkT7opQm6rBAEn0CdM8CNVlKGWYmjAhyeWbHeg,783
+codeintel/providers/semantic.py,sha256=Yka9Puyd8LqY2jfvjoJzAsSMZvb3S-cViQC6fuesdUk,5397
+codecortex-0.2.0.dist-info/METADATA,sha256=WfiL2GZ0JN1VhuKX2GTkIi70q4uA6kB2NrRVL9Po2XI,9853
+codecortex-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+codecortex-0.2.0.dist-info/entry_points.txt,sha256=zrYfo95-8JkK0G2e5f9d94sYqqim7ZrdCW8knIfSy2U,54
+codecortex-0.2.0.dist-info/top_level.txt,sha256=DF3TH1hHLWrrnX-7HhfMX0OnS2EXgqPRhPbiL_oSekw,10
+codecortex-0.2.0.dist-info/RECORD,,

codecortex-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codecortex-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codeintel = codeintel.__main__:main

codecortex-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shammai Hamilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codecortex-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codeintel

codeintel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

codeintel/__main__.py

@@ -0,0 +1,361 @@
+import argparse
+import os
+import sys
+
+from codeintel import __version__
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="codeintel")
+    parser.add_argument("--version", action="version", version=f"codeintel {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Shared flags for the human-facing (styled) commands.
+    color_parent = argparse.ArgumentParser(add_help=False)
+    color_parent.add_argument("--no-color", action="store_true", help="Disable ANSI color output")
+    color_parent.add_argument("--ascii", action="store_true", help="Use ASCII-only glyphs")
+
+    subparsers.add_parser("serve", help="Start the MCP server")
+
+    # index subcommand
+    index_parser = subparsers.add_parser("index", help="Index a project for semantic search")
+    index_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # query subcommand
+    query_parser = subparsers.add_parser("query", help="Query the code intelligence engine")
+    query_parser.add_argument("--op", required=True, help="Query operation (e.g. search, symbol)")
+    query_parser.add_argument("--target", required=True, help="Query target")
+    query_parser.add_argument("--engine", default="auto", help="Engine to use (default: auto)")
+    query_parser.add_argument(
+        "--project-root",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # status subcommand
+    status_parser = subparsers.add_parser("status", help="Show code intelligence engine status")
+    status_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # serve-http subcommand
+    http_parser = subparsers.add_parser("serve-http", help="Start the HTTP transport server")
+    http_parser.add_argument("--port", type=int, default=8766, help="Port to listen on (default: 8766)")
+    http_parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
+    http_parser.add_argument("--allow-remote", action="store_true", help="Permit binding a non-loopback host (exposes an UNAUTHENTICATED endpoint)")
+
+    # install subcommand
+    install_parser = subparsers.add_parser("install", help="Register codeintel with AI agents")
+    install_parser.add_argument(
+        "--agent",
+        choices=["claude", "codex", "gemini", "zed", "all"],
+        default="all",
+        help="Agent to register with (default: all)",
+    )
+
+    # map subcommand
+    map_parser = subparsers.add_parser("map", help="Generate CODE_INTEL.md orientation file")
+    map_parser.add_argument("project_root", nargs="?", default=None)
+    map_parser.add_argument("--inject", action="store_true", help="Inject reference block into CLAUDE.md/AGENTS.md")
+    map_parser.add_argument("--budget", type=int, default=32768, help="Byte budget for CODE_INTEL.md (default: 32768)")
+
+    # doctor subcommand
+    doctor_parser = subparsers.add_parser("doctor", parents=[color_parent], help="Diagnose engine health + index status for a repo")
+    doctor_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    doctor_parser.add_argument("--deep", action="store_true", help="Also boot-check serena (slower; first boot pulls it via uvx)")
+    doctor_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report instead of the table")
+
+    # setup subcommand
+    setup_parser = subparsers.add_parser("setup", parents=[color_parent], help="Prepare backends and optionally index this repo")
+    setup_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    setup_parser.add_argument("--install-uv", action="store_true", help="Run `pip install uv` (provides uvx for the LSP engine)")
+    setup_parser.add_argument("--install-deps", action="store_true", help="Run `pip install -e .` (semantic engine deps)")
+    setup_parser.add_argument("--index", action="store_true", help="Index this repo now (first run downloads the ~50MB model)")
+    setup_parser.add_argument("--warm", action="store_true", help="Boot serena now (first run pulls it via uvx; slow)")
+    setup_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
+
+    # reset subcommand
+    reset_parser = subparsers.add_parser("reset", parents=[color_parent], help="Clear the semantic index (recover from a corrupt/stale DB)")
+    reset_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    reset_parser.add_argument("--all", action="store_true", help="Clear the ENTIRE index (all projects), not just this repo")
+    reset_parser.add_argument("--yes", "-y", action="store_true", help="Skip the confirmation prompt")
+    reset_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
+
+    args = parser.parse_args()
+
+    from codeintel import term
+    term.configure(
+        no_color=getattr(args, "no_color", False),
+        ascii_mode=(True if getattr(args, "ascii", False) else None),
+    )
+
+    if args.command == "serve":
+        from codeintel.server import run
+        run()
+
+    elif args.command == "index":
+        from codeintel.config import load_config
+        from codeintel.indexer import Indexer
+        from codeintel.semantic_db import SemanticDb, default_db_path
+
+        project_root = args.project_root or os.getcwd()
+        cfg = load_config(project_root)
+
+        db_path = default_db_path()
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        db = SemanticDb(db_path)
+        try:
+            db.init()
+            count = Indexer(
+                db,
+                model_name=str(cfg.get("model") or "BAAI/bge-small-en-v1.5"),
+                window=int(cfg.get("window", 20)),
+                stride=int(cfg.get("stride", 10)),
+                max_chunks=int(cfg.get("max_chunks", 500)),
+            ).index(project_root)
+            if count > 0:
+                print(f"Indexed {count} chunks")
+            else:
+                print("Nothing new to index")
+        finally:
+            db.close()
+
+        # best-effort graph reindex
+        import shutil
+        if shutil.which("codebase-memory-mcp"):
+            try:
+                from codeintel.reindexer import Reindexer
+                Reindexer()._graph_reindex(project_root)
+            except Exception:
+                pass
+
+        # best-effort map refresh after index
+        try:
+            from codeintel.providers.graph import GraphProvider
+            from codeintel.mapper import MapGenerator
+            _provider = GraphProvider()
+            _gen = MapGenerator(_provider)
+            _content = _gen.generate(project_root)
+            _gen.write(project_root, _content)
+        except Exception:
+            pass
+
+    elif args.command == "map":
+        from codeintel.providers.graph import GraphProvider
+        from codeintel.mapper import MapGenerator
+        from codeintel.injector import Injector
+
+        project_root = args.project_root or os.getcwd()
+        try:
+            provider = GraphProvider()
+        except Exception:
+            provider = None
+        gen = MapGenerator(provider)
+        try:
+            content = gen.generate(project_root, budget_bytes=args.budget)
+            path = gen.write(project_root, content)
+            print(f"Wrote {path} ({len(content.encode())} bytes)")
+            if args.inject:
+                inj_path, inj_action = Injector().inject(project_root)
+                if inj_path:
+                    print(f"Inject: {inj_action} block in {inj_path}")
+                else:
+                    print(f"Inject: {inj_action}")
+        except Exception as exc:
+            # Never-raise parity with the MCP code.map handler — degrade, don't crash.
+            print(f"map failed: {exc}")
+        sys.exit(0)
+
+    elif args.command == "query":
+        try:
+            import time
+
+            from codeintel import server
+            project_root = args.project_root or os.getcwd()
+            engine = args.engine if args.engine != "auto" else None
+            gw = server._build_gateway()
+
+            def _run_query():
+                return gw.query(
+                    op=args.op,
+                    target=args.target,
+                    engine=engine,
+                    role="",
+                    project_root=project_root,
+                )
+
+            result = _run_query()
+
+            # The LSP engine warms a serena session in a background thread and returns
+            # reason:warming on the first call. A one-shot CLI process would otherwise always
+            # exit on 'warming' (the subprocess dies with it). Wait — bounded, never-raise —
+            # for the session to boot, re-querying the same gateway (session is cached per root).
+            if result.get("result") is None and result.get("reason") == "warming":
+                print("(lsp warming up — waiting for the language server...)", file=sys.stderr)
+                deadline = time.monotonic() + 45.0
+                while time.monotonic() < deadline:
+                    time.sleep(0.5)
+                    result = _run_query()
+                    if result.get("result") is not None or result.get("reason") != "warming":
+                        break
+
+            value = result.get("result")
+            if value is not None:
+                print(value)
+            else:
+                reason = result.get("reason", "unknown")
+                hint = result.get("hint")
+                print(f"No result (reason: {reason})")
+                if hint:
+                    print(f"  hint: {hint}", file=sys.stderr)
+        except Exception as exc:
+            print(f"No result (reason: {exc})")
+        sys.exit(0)
+
+    elif args.command == "status":
+        try:
+            from codeintel import server
+
+            project_root = args.project_root or os.getcwd()
+            status = server.code_status_handler({})
+
+            print("Engine status:")
+            for engine in ["graph", "lsp", "semantic"]:
+                available = status.get(engine, False)
+                state = "available" if available else "unavailable"
+                print(f"  {engine:<10} {state}")
+
+            from codeintel.semantic_db import default_db_path
+            db_path = default_db_path()
+            if os.path.exists(db_path):
+                import datetime
+                mtime = os.path.getmtime(db_path)
+                age = datetime.datetime.now() - datetime.datetime.fromtimestamp(mtime)
+                hours = int(age.total_seconds() // 3600)
+                minutes = int((age.total_seconds() % 3600) // 60)
+                print(f"\nIndex age: {hours}h {minutes}m  ({db_path})")
+            else:
+                print(f"\nIndex: not found  ({db_path})")
+        except Exception as exc:
+            print(f"Status unavailable: {exc}")
+        sys.exit(0)
+
+    elif args.command == "doctor":
+        try:
+            from codeintel import doctor as _doctor
+
+            project_root = args.project_root or os.getcwd()
+            report = _doctor.run_doctor(project_root, deep=args.deep)
+            if args.json:
+                import json as _json
+                print(_json.dumps(report, indent=2))
+            else:
+                print(_doctor.render_doctor_text(report))
+            # Exit non-zero when a repo-critical engine is unhealthy, so scripts/CI can gate on it.
+            sys.exit(0 if report.get("summary", {}).get("healthy") else 1)
+        except Exception as exc:
+            print(f"doctor unavailable: {exc}")
+            sys.exit(0)
+
+    elif args.command == "setup":
+        try:
+            from codeintel import onboarding
+
+            project_root = args.project_root or os.getcwd()
+            report = onboarding.run_setup(
+                project_root,
+                install_uv=args.install_uv,
+                install_deps=args.install_deps,
+                do_index=args.index,
+                warm_lsp=args.warm,
+            )
+            if args.json:
+                import json as _json
+                print(_json.dumps(report, indent=2))
+            else:
+                print(onboarding.render_setup_text(report))
+            healthy = report.get("doctor", {}).get("summary", {}).get("healthy")
+            sys.exit(0 if healthy else 1)
+        except Exception as exc:
+            print(f"setup unavailable: {exc}")
+            sys.exit(0)
+
+    elif args.command == "reset":
+        try:
+            from codeintel import reset as _reset
+
+            project_root = args.project_root or os.getcwd()
+            preview = _reset.run_reset(project_root, all_projects=args.all, apply=False)
+            if not args.yes:
+                if not sys.stdin.isatty():
+                    print("refusing to reset without --yes in a non-interactive shell")
+                    sys.exit(1)
+                target = "ALL projects" if args.all else project_root
+                count = preview.get("count", 0)
+                ans = input(f"Reset semantic index for {target} ({count} entries)? [y/N] ").strip().lower()
+                if ans not in ("y", "yes"):
+                    print("aborted")
+                    sys.exit(0)
+            report = _reset.run_reset(project_root, all_projects=args.all, apply=True)
+            if args.json:
+                import json as _json
+                print(_json.dumps(report, indent=2))
+            else:
+                print(report.get("detail", "reset complete"))
+            sys.exit(0)
+        except Exception as exc:
+            print(f"reset unavailable: {exc}")
+            sys.exit(0)
+
+    elif args.command == "serve-http":
+        try:
+            from codeintel.http_server import run
+            run(host=args.host, port=args.port, allow_remote=args.allow_remote)
+        except KeyboardInterrupt:
+            pass
+        except Exception as exc:
+            # A startup failure (e.g. port in use) should print a friendly line, not a traceback.
+            # SystemExit from the non-loopback guard is BaseException — it passes through here.
+            print(f"serve-http failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.command == "install":
+        from codeintel.installer import Installer
+
+        installer = Installer()
+        if args.agent == "all":
+            results = installer.register_all()
+        else:
+            results = [installer.register(args.agent)]
+
+        any_ok = False
+        for r in results:
+            agent = r["agent"]
+            path = r["path"]
+            action = r["action"]
+            if action == "registered":
+                print(f"v {agent}: registered at {path}")
+                any_ok = True
+            elif action == "already":
+                print(f"~ {agent}: already registered at {path}")
+                any_ok = True
+            else:
+                print(f"x {agent}: failed — {r['reason']}")
+
+        sys.exit(0 if any_ok else 1)
+
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()