Design from justrach/turbodb — adapted from turbodb's lazy-serve architecture.
Problem
MCP server blocks until the full scan completes. On openclaw (4,950 files), startup takes 42 seconds before the first query can be served. Agents wait with no feedback.
Evidence
Head-to-head benchmark:
- codedb: 42s before first query
- Competitor: 16ms to first query (indexes lazily in background)
Proposed Solution
Start serving MCP immediately, index in background:
- Load snapshot (if exists) → serve MCP immediately (<100ms)
- If no snapshot: walk file list only (~500ms) → serve partial tree/find results
- Background thread: build outlines → build trigrams → write snapshot
codedb_status reports scan progress (walking/indexing/ready)
Failing test
test "issue-207: MCP responds during background scan" {
// Start MCP server
// Send codedb_status before scan completes
// Verify response (even if partial results)
}
Expected impact
| Metric |
Before |
After |
| Time to first query |
42s |
<100ms (snapshot) or ~500ms (walk) |
| Full index available |
42s |
42s (same, but in background) |
Files to modify
src/main.zig — MCP startup path, decouple scanBg from serving
Problem
MCP server blocks until the full scan completes. On openclaw (4,950 files), startup takes 42 seconds before the first query can be served. Agents wait with no feedback.
Evidence
Head-to-head benchmark:
Proposed Solution
Start serving MCP immediately, index in background:
codedb_statusreports scan progress (walking/indexing/ready)Failing test
Expected impact
Files to modify
src/main.zig— MCP startup path, decouplescanBgfrom serving