codecortex 0.2.0__tar.gz → 0.2.2__tar.gz

{codecortex-0.2.0/src/codecortex.egg-info → codecortex-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -33,10 +33,65 @@ 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.
+**One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+## Why an agent needs it
+
+Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
+
+- **"What calls this? What breaks if I change it?"** → the real call graph, which catches cross-file and module-level callers a text search silently misses.
+- **"Where is this symbol defined, and everywhere it's used?"** → the language server, with exact locations.
+- **"Where's the code that does X?"** (when you don't know the name) → semantic search over the repo.
+- **Always a clean answer.** Every call returns the same JSON envelope. A missing or broken backend degrades to a safe `null` *with a reason* — so the agent falls back to grep instead of crashing on an exception it can't reason its way out of.
+
+Net effect: fewer, sharper tool calls, less re-reading, and an agent that can see *structure* — callers, impact, call chains — that plain search can't.
+
+## What your agent can ask
+
+It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the default) codeintel picks the engine per operation:
+
+| Ask | `op` | Engine (auto) | Comes back as |
+|---|---|---|---|
+| Find code by meaning ("auth middleware") | `search` | semantic | ranked `path:line │ snippet` hits |
+| A symbol's definition **and** all references | `symbol` | lsp | definition body + reference list |
+| Who calls this? | `callers` | graph | caller symbols + files |
+| What does this call? | `callees` | graph | callee symbols + files |
+| Blast radius of a change | `impact` | graph | callers **and** callees together |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Find symbols by pattern | `pattern` | graph | matching nodes + locations |
+| Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
+| Everything about one symbol | `context` | graph + lsp | both views merged |
+
+Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
+
+**Example — "who uses `safe_null_result`?"**
+
+```jsonc
+// request
+{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+
+// response — always this exact envelope; `result` is ready-to-read markdown
+{
+  "ok": true, "op": "callers", "target": "safe_null_result",
+  "engine": "graph", "cached": false,
+  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
+}
+```
+
+The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+
+## What makes it good
+
+- **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
+- **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
+- **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
+- **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
+- **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
+- **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
+- **Honest about its own health.** `codeintel doctor` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+
 ## Quickstart
 
 ```bash
@@ -146,7 +201,7 @@ 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
+max_chunks   = 500                      # max chunks to embed per file
 model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
@@ -170,7 +225,16 @@ Not sure what's installed? `codeintel doctor` reports exactly which backends are
 
 ## For agents
 
-Start the HTTP server, then POST queries to `/code/query`:
+Register codeintel as an MCP server (`codeintel install`) and the agent gets four tools:
+
+| MCP tool | HTTP equivalent | Purpose |
+|---|---|---|
+| `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
+| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
+| `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
+
+Over MCP the agent calls `code.query` directly. Over HTTP, start the server and POST to `/code/query`:
 
 ```bash
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
@@ -202,5 +266,5 @@ The response is always JSON-safe. Check `result["result"] is not None` before us
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite, ~1s
+pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
 ```

{codecortex-0.2.0 → codecortex-0.2.2}/README.md

@@ -1,9 +1,64 @@
 # 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.
+**One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+## Why an agent needs it
+
+Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
+
+- **"What calls this? What breaks if I change it?"** → the real call graph, which catches cross-file and module-level callers a text search silently misses.
+- **"Where is this symbol defined, and everywhere it's used?"** → the language server, with exact locations.
+- **"Where's the code that does X?"** (when you don't know the name) → semantic search over the repo.
+- **Always a clean answer.** Every call returns the same JSON envelope. A missing or broken backend degrades to a safe `null` *with a reason* — so the agent falls back to grep instead of crashing on an exception it can't reason its way out of.
+
+Net effect: fewer, sharper tool calls, less re-reading, and an agent that can see *structure* — callers, impact, call chains — that plain search can't.
+
+## What your agent can ask
+
+It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the default) codeintel picks the engine per operation:
+
+| Ask | `op` | Engine (auto) | Comes back as |
+|---|---|---|---|
+| Find code by meaning ("auth middleware") | `search` | semantic | ranked `path:line │ snippet` hits |
+| A symbol's definition **and** all references | `symbol` | lsp | definition body + reference list |
+| Who calls this? | `callers` | graph | caller symbols + files |
+| What does this call? | `callees` | graph | callee symbols + files |
+| Blast radius of a change | `impact` | graph | callers **and** callees together |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Find symbols by pattern | `pattern` | graph | matching nodes + locations |
+| Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
+| Everything about one symbol | `context` | graph + lsp | both views merged |
+
+Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
+
+**Example — "who uses `safe_null_result`?"**
+
+```jsonc
+// request
+{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+
+// response — always this exact envelope; `result` is ready-to-read markdown
+{
+  "ok": true, "op": "callers", "target": "safe_null_result",
+  "engine": "graph", "cached": false,
+  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
+}
+```
+
+The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+
+## What makes it good
+
+- **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
+- **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
+- **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
+- **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
+- **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
+- **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
+- **Honest about its own health.** `codeintel doctor` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+
 ## Quickstart
 
 ```bash
@@ -113,7 +168,7 @@ 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
+max_chunks   = 500                      # max chunks to embed per file
 model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
@@ -137,7 +192,16 @@ Not sure what's installed? `codeintel doctor` reports exactly which backends are
 
 ## For agents
 
-Start the HTTP server, then POST queries to `/code/query`:
+Register codeintel as an MCP server (`codeintel install`) and the agent gets four tools:
+
+| MCP tool | HTTP equivalent | Purpose |
+|---|---|---|
+| `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
+| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
+| `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
+
+Over MCP the agent calls `code.query` directly. Over HTTP, start the server and POST to `/code/query`:
 
 ```bash
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
@@ -169,5 +233,5 @@ The response is always JSON-safe. Check `result["result"] is not None` before us
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite, ~1s
+pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
 ```

{codecortex-0.2.0 → codecortex-0.2.2/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -33,10 +33,65 @@ 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.
+**One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+## Why an agent needs it
+
+Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
+
+- **"What calls this? What breaks if I change it?"** → the real call graph, which catches cross-file and module-level callers a text search silently misses.
+- **"Where is this symbol defined, and everywhere it's used?"** → the language server, with exact locations.
+- **"Where's the code that does X?"** (when you don't know the name) → semantic search over the repo.
+- **Always a clean answer.** Every call returns the same JSON envelope. A missing or broken backend degrades to a safe `null` *with a reason* — so the agent falls back to grep instead of crashing on an exception it can't reason its way out of.
+
+Net effect: fewer, sharper tool calls, less re-reading, and an agent that can see *structure* — callers, impact, call chains — that plain search can't.
+
+## What your agent can ask
+
+It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the default) codeintel picks the engine per operation:
+
+| Ask | `op` | Engine (auto) | Comes back as |
+|---|---|---|---|
+| Find code by meaning ("auth middleware") | `search` | semantic | ranked `path:line │ snippet` hits |
+| A symbol's definition **and** all references | `symbol` | lsp | definition body + reference list |
+| Who calls this? | `callers` | graph | caller symbols + files |
+| What does this call? | `callees` | graph | callee symbols + files |
+| Blast radius of a change | `impact` | graph | callers **and** callees together |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Find symbols by pattern | `pattern` | graph | matching nodes + locations |
+| Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
+| Everything about one symbol | `context` | graph + lsp | both views merged |
+
+Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
+
+**Example — "who uses `safe_null_result`?"**
+
+```jsonc
+// request
+{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+
+// response — always this exact envelope; `result` is ready-to-read markdown
+{
+  "ok": true, "op": "callers", "target": "safe_null_result",
+  "engine": "graph", "cached": false,
+  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
+}
+```
+
+The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+
+## What makes it good
+
+- **Local-first and private.** One process on your machine — no cloud service, no API keys, no telemetry, no per-query network. Safe to point at a private repo, even with `--engine all`. (The one-time exception: `fastembed` downloads its embedding model once, then runs fully offline.)
+- **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
+- **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
+- **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
+- **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
+- **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
+- **Honest about its own health.** `codeintel doctor` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+
 ## Quickstart
 
 ```bash
@@ -146,7 +201,7 @@ 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
+max_chunks   = 500                      # max chunks to embed per file
 model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
@@ -170,7 +225,16 @@ Not sure what's installed? `codeintel doctor` reports exactly which backends are
 
 ## For agents
 
-Start the HTTP server, then POST queries to `/code/query`:
+Register codeintel as an MCP server (`codeintel install`) and the agent gets four tools:
+
+| MCP tool | HTTP equivalent | Purpose |
+|---|---|---|
+| `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
+| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
+| `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
+
+Over MCP the agent calls `code.query` directly. Over HTTP, start the server and POST to `/code/query`:
 
 ```bash
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
@@ -202,5 +266,5 @@ The response is always JSON-safe. Check `result["result"] is not None` before us
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite, ~1s
+pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
 ```

{codecortex-0.2.0 → codecortex-0.2.2}/src/codecortex.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/codeintel/providers/graph.py
 src/codeintel/providers/lsp.py
 src/codeintel/providers/none.py
 src/codeintel/providers/semantic.py
+tests/test_cache.py
 tests/test_doctor.py
 tests/test_e2e.py
 tests/test_gateway.py

codecortex-0.2.2/src/codeintel/__init__.py

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

{codecortex-0.2.0 → codecortex-0.2.2}/src/codeintel/cache.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import hashlib
 import os
 import threading
+from collections import OrderedDict
 from typing import Optional
 
 from codeintel.provider import Result
@@ -22,10 +23,15 @@ def _compute_hash(target: str, project_root: str) -> str:
 
 
 class ContentHashCache:
-    def __init__(self) -> None:
+    # Bounded: the server builds ONE gateway and reuses it across every request, so an unbounded
+    # store would grow for the life of the process. Capped as an LRU — past _max_entries the
+    # least-recently-used entry is evicted. Sized generously; an agent session touches at most a
+    # few hundred distinct (op, target, engine, root) keys, each holding a small Result.
+    def __init__(self, max_entries: int = 1024) -> None:
         self._lock = threading.Lock()
-        # key → (content_hash, Result)
-        self._store: dict[tuple[str, str, str, str], tuple[str, Result]] = {}
+        self._max_entries = max(1, int(max_entries))
+        # key → (content_hash, Result); OrderedDict preserves insertion/access order for LRU.
+        self._store: "OrderedDict[tuple[str, str, str, str], tuple[str, Result]]" = OrderedDict()
 
     def get(
         self,
@@ -41,10 +47,14 @@ class ContentHashCache:
         if entry is None:
             return None
         stored_hash, result = entry
+        # _compute_hash may read the target file — keep it OUTSIDE the lock (original intent).
         current_hash = f"{_compute_hash(target, project_root)}:{freshness}"
-        if current_hash == stored_hash:
-            return result
-        return None
+        if current_hash != stored_hash:
+            return None
+        with self._lock:
+            if key in self._store:  # may have been evicted between the two locked sections
+                self._store.move_to_end(key)  # mark most-recently-used
+        return result
 
     def put(
         self,
@@ -64,3 +74,6 @@ class ContentHashCache:
         content_hash = f"{_compute_hash(target, project_root)}:{freshness}"
         with self._lock:
             self._store[key] = (content_hash, result)
+            self._store.move_to_end(key)  # most-recently-used
+            while len(self._store) > self._max_entries:
+                self._store.popitem(last=False)  # evict least-recently-used

{codecortex-0.2.0 → codecortex-0.2.2}/src/codeintel/http_server.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import json
 import sys
-from http.server import BaseHTTPRequestHandler, HTTPServer
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
 from codeintel.server import code_doctor_handler, code_query_handler, code_status_handler
 
@@ -57,8 +57,12 @@ class _Handler(BaseHTTPRequestHandler):
         self._send_json(200, result)
 
 
-class CodeIntelHTTPServer(HTTPServer):
-    pass
+class CodeIntelHTTPServer(ThreadingHTTPServer):
+    # Threaded so one slow request (e.g. an LSP session warming, or a first-time index) can't
+    # block every other agent's query. The gateway is a shared singleton, but its mutable state
+    # is lock-guarded (query cache, reindexer, LSP sessions, graph project cache) and the
+    # semantic engine is thread-confined with WAL, so concurrent requests are safe.
+    daemon_threads = True
 
 
 _LOOPBACK_NAMES = {"localhost"}

{codecortex-0.2.0 → codecortex-0.2.2}/src/codeintel/injector.py

@@ -57,8 +57,12 @@ def _read_file(path: str) -> str | None:
 
 
 def _write_file(path: str, content: str) -> None:
-    with open(path, "w", encoding="utf-8") as f:
+    # Atomic: write a sibling temp file then os.replace it into place, so an interrupted
+    # write can never leave the user's CLAUDE.md/AGENTS.md truncated or half-written.
+    tmp = path + ".codeintel.tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
         f.write(content)
+    os.replace(tmp, path)
 
 
 def _update_block(content: str) -> tuple[str, str]:

{codecortex-0.2.0 → codecortex-0.2.2}/src/codeintel/installer.py

@@ -1,10 +1,20 @@
 from __future__ import annotations
 
 import json
+import os
 import pathlib
 
 _AGENTS = ["claude", "codex", "gemini", "zed"]
 
+
+def _atomic_write_text(path: pathlib.Path, text: str) -> None:
+    """Write via a sibling temp file + os.replace so an interrupted write can never truncate
+    the user's existing agent config (which holds unrelated settings) to a partial/empty file.
+    The temp lives in the same directory as ``path`` so the replace stays on one filesystem."""
+    tmp = path.with_name(path.name + ".codeintel.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
 _CONFIG: dict[str, dict] = {
     "claude": {
         "path": "~/.claude/settings.json",
@@ -80,7 +90,7 @@ class Installer:
 
             config_path.parent.mkdir(parents=True, exist_ok=True)
             _set_nested(data, spec["key"], spec["value"])
-            config_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+            _atomic_write_text(config_path, json.dumps(data, indent=2))
 
             return {
                 "agent": agent,

{codecortex-0.2.0 → codecortex-0.2.2}/src/codeintel/providers/graph.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import shutil
 import subprocess
+import threading
 import time
 from typing import Any, Optional
 
@@ -35,6 +36,7 @@ class GraphProvider:
 
     def __init__(self) -> None:
         self._project_cache: dict[str, Optional[str]] = {}
+        self._project_cache_lock = threading.Lock()  # concurrent HTTP requests share one provider
         self._detect_backend()
 
     def _detect_backend(self) -> None:
@@ -125,11 +127,16 @@ class GraphProvider:
         return exact if exact is not None else best_prefix_name
 
     def _resolve_project(self, project_root: str) -> Optional[str]:
-        if project_root in self._project_cache:
-            return self._project_cache[project_root]
+        with self._project_cache_lock:
+            if project_root in self._project_cache:
+                return self._project_cache[project_root]
+        # list_projects shells out — resolve it OUTSIDE the lock so a slow backend can't serialize
+        # every concurrent request. A rare duplicate lookup on first contact is harmless (the
+        # result is idempotent); we simply never hold the lock across a subprocess.
         raw = self._run("list_projects", {}, 3000)
         name = self._match_project(raw, project_root)
-        self._project_cache[project_root] = name
+        with self._project_cache_lock:
+            self._project_cache[project_root] = name
         return name
 
     def probe(self, project_root: str, timeout_ms: int = 3000) -> dict:

{codecortex-0.2.0 → codecortex-0.2.2}/src/codeintel/semantic_db.py

@@ -31,6 +31,18 @@ class SemanticDb:
             self._conn = sqlite3.connect(self.db_path)
             self._conn.enable_load_extension(True)
             self._conn.row_factory = sqlite3.Row
+            # Concurrency: the background Reindexer writes on a daemon thread while a foreground
+            # query indexes inline — two separate connections to this one file. With the SQLite
+            # default (busy_timeout=0) the loser of that write race gets an immediate
+            # "database is locked" and silently drops its work; a busy timeout makes it wait
+            # instead, and WAL lets a search read while a reindex writes. (reset.py already
+            # cleans up the -wal/-shm siblings WAL creates.) Never-raise: if the pragmas can't
+            # be applied, fall back to default locking rather than fail to open the db.
+            try:
+                self._conn.execute("PRAGMA busy_timeout=5000")
+                self._conn.execute("PRAGMA journal_mode=WAL")
+            except Exception:
+                pass
         return self._conn
 
     def init(self) -> None:

codecortex-0.2.2/tests/test_cache.py

@@ -0,0 +1,61 @@
+"""Unit tests for ContentHashCache — the LRU bound added in 0.2.2 so the long-lived server
+can't grow the query cache without limit. Real cache object, no mocks."""
+from __future__ import annotations
+
+from codeintel.cache import ContentHashCache
+
+
+def _result(tag: str) -> dict:
+    return {"ok": True, "op": "search", "target": tag, "result": f"r-{tag}",
+            "engine": "semantic", "cached": False}
+
+
+def _put(cache: ContentHashCache, tag: str) -> None:
+    cache.put("search", tag, "semantic", "", _result(tag), 0)
+
+
+def _get(cache: ContentHashCache, tag: str):
+    return cache.get("search", tag, "semantic", "", 0)
+
+
+def test_hit_returns_stored_result():
+    c = ContentHashCache()
+    _put(c, "x")
+    got = _get(c, "x")
+    assert got is not None and got["result"] == "r-x"
+
+
+def test_freshness_bump_busts_the_entry():
+    c = ContentHashCache()
+    _put(c, "x")                                   # stored at freshness 0
+    assert c.get("search", "x", "semantic", "", 1) is None  # a completed reindex invalidates it
+
+
+def test_null_result_is_not_cached():
+    c = ContentHashCache()
+    c.put("search", "x", "semantic", "", {"ok": True, "result": None}, 0)
+    assert _get(c, "x") is None
+
+
+def test_evicts_least_recently_used_past_capacity():
+    c = ContentHashCache(max_entries=3)
+    for t in ("t0", "t1", "t2"):
+        _put(c, t)
+    # Touch t0 so it becomes most-recently-used; t1 is now the LRU.
+    assert _get(c, "t0") is not None
+    _put(c, "t3")  # over capacity → evict the LRU (t1)
+
+    assert _get(c, "t1") is None       # evicted
+    assert _get(c, "t0") is not None   # kept — it was accessed most recently
+    assert _get(c, "t2") is not None   # kept
+    assert _get(c, "t3") is not None   # just inserted
+
+
+def test_capacity_is_never_exceeded():
+    c = ContentHashCache(max_entries=5)
+    for i in range(50):
+        _put(c, f"k{i}")
+    assert len(c._store) == 5
+    # The 5 most recent survive; older keys are gone.
+    assert _get(c, "k49") is not None
+    assert _get(c, "k0") is None

codecortex-0.2.0/src/codeintel/__init__.py

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