{"id":45954905,"url":"https://github.com/justrach/codedb","last_synced_at":"2026-05-03T18:08:08.097Z","repository":{"id":341136379,"uuid":"1169005307","full_name":"justrach/codedb","owner":"justrach","description":"High-performance MCP server, code graph engine \u0026 evolutionary algorithm platform in Zig. 33 tools: GitHub project management, agent swarm orchestration, iterative review-fix loops, blast radius analysis, and code navigation via Model Context Protocol.","archived":false,"fork":false,"pushed_at":"2026-03-04T14:25:49.000Z","size":534,"stargazers_count":7,"open_issues_count":46,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T21:55:50.062Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justrach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T03:42:40.000Z","updated_at":"2026-03-04T14:25:54.000Z","dependencies_parsed_at":"2026-03-02T15:00:43.513Z","dependency_job_id":null,"html_url":"https://github.com/justrach/codedb","commit_stats":null,"previous_names":["justrach/codedb"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/justrach/codedb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justrach%2Fcodedb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justrach%2Fcodedb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justrach%2Fcodedb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justrach%2Fcodedb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justrach","download_url":"https://codeload.github.com/justrach/codedb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justrach%2Fcodedb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30141261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T16:58:46.102Z","status":"ssl_error","status_checked_at":"2026-03-05T16:58:45.706Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-28T13:25:21.173Z","updated_at":"2026-05-03T18:08:08.088Z","avatar_url":"https://github.com/justrach.png","language":"Zig","funding_links":[],"categories":["Zig","\u003ca name=\"Zig\"\u003e\u003c/a\u003eZig","Openai"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/codedb.png\" alt=\"codedb\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/justrach/codedb/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/justrach/codedb?style=flat-square\u0026label=version\" alt=\"Release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/justrach/codedb/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/justrach/codedb?style=flat-square\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/zig-0.15-f7a41d?style=flat-square\" alt=\"Zig 0.15\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-alpha-orange?style=flat-square\" alt=\"Alpha\" /\u003e\n  \u003ca href=\"https://deepwiki.com/justrach/codedb\"\u003e\u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ecodedb\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003eCode intelligence server for AI agents. Zig core. MCP native. Zero dependencies.\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  Structural indexing · Trigram search · Word index · Dependency graph · File watching · MCP + HTTP\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-status\"\u003eStatus\u003c/a\u003e ·\n  \u003ca href=\"#-install\"\u003eInstall\u003c/a\u003e ·\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#-mcp-tools\"\u003eMCP Tools\u003c/a\u003e ·\n  \u003ca href=\"#-benchmarks\"\u003eBenchmarks\u003c/a\u003e ·\n  \u003ca href=\"#️-architecture\"\u003eArchitecture\u003c/a\u003e ·\n  \u003ca href=\"#-data--privacy\"\u003eData \u0026 Privacy\u003c/a\u003e ·\n  \u003ca href=\"#-building-from-source\"\u003eBuilding\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Status\n\n\u003e **Alpha software — API is stabilizing but may change**\n\u003e\n\u003e codedb works and is used daily in production AI workflows, but:\n\u003e - **Parser support** — Zig, C/C++, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart/Flutter\n\u003e - **Lightweight outline support** — Java, Kotlin, Svelte, Vue, Astro, shell, CSS/SCSS, SQL, protobuf, Fortran, LLVM IR, MLIR, and TableGen\n\u003e - **No auth** — HTTP server binds to localhost only\n\u003e - **Snapshot format** may change between versions\n\u003e - **MCP protocol** is JSON-RPC 2.0 over stdio (stable)\n\n| What works today                                       | What's in progress                       |\n|--------------------------------------------------------|------------------------------------------|\n| 16 MCP tools for full codebase intelligence            | Deeper parser coverage and edge-case handling |\n| Trigram v2: integer doc IDs, batch-accumulate, merge intersect | Incremental segment-based indexing |\n| 538x faster than ripgrep on pre-indexed queries        | WASM target for Cloudflare Workers       |\n| O(1) inverted word index for identifier lookup         | Multi-project support                    |\n| Structural outlines (functions, structs, imports)      | mmap-backed trigram index                |\n| Reverse dependency graph                               |                                          |\n| Atomic line-range edits with version tracking          |                                          |\n| Auto-registration in Claude, Codex, Gemini, Cursor     |                                          |\n| Polling file watcher with filtered directory walker    |                                          |\n| Portable snapshot for instant MCP startup              |                                          |\n| Singleton MCP with PID lock + 1h idle timeout          |                                          |\n| Sensitive file blocking (.env, credentials, keys)      |                                          |\n| Codesigned + notarized macOS binaries                  |                                          |\n| SHA256 checksum verification in installer              |                                          |\n| Cross-platform: macOS (ARM/x86), Linux (ARM/x86)      |                                          |\n\n---\n\n## ⚡ Install\n\n```bash\ncurl -fsSL https://codedb.codegraff.com/install.sh | bash\n```\n\nDownloads the binary for your platform and auto-registers codedb as an MCP server in **Claude Code**, **Codex**, **Gemini CLI**, and **Cursor**. The installer prints the exact `codedb mcp` command it registered plus hook setup pointers for Codex and Claude Code.\n\n### Updating or repairing an older install\n\nIf `codedb update` fails on an older release, rerun the installer:\n\n```bash\ncurl -fsSL https://codedb.codegraff.com/install.sh | bash\n```\n\nThis replaces the `codedb` binary with the latest GitHub Release and keeps your existing MCP registrations, config, caches, and snapshots. Use this path for any release whose built-in updater cannot fetch release checksums.\n\n### v0.2.579 MCP hotfix and release checksums\n\nThis note applies to `v0.2.579` only. Earlier `v0.2.579` binaries were rebuilt\nand re-uploaded on May 2, 2026 because they passed the normal Zig test suite but\nmissed an MCP end-to-end regression: after `codedb_index` reported success,\nfollow-up MCP queries could still see an empty in-memory project (`files: 0`,\n`scan: loading_snapshot`, empty `tree`/`find`/`search`, or `file not indexed`).\n\nThe fixed `v0.2.579` release assets were rebuilt from source commit\n`1b634f0ba5cd1072e9ca54cabf442b573e034f53`. The values below are SHA256\nchecksums for the uploaded binaries, not Git commit SHAs:\n\n| Binary | SHA256 |\n|--------|--------|\n| `codedb-darwin-arm64` | `b5bddba01767e38e9723f28c7b3ff55370c4eda5f9e0e84172aaec1ff5094cb2` |\n| `codedb-darwin-x86_64` | `cf2a9ec511f99fd839d2349cc17e671cd9566260cf601b8b23dd649665c22999` |\n| `codedb-linux-arm64` | `955b0288c5cfb5c360f7b814cd3cc288ecc42c63a569f65fac358bd9454d788b` |\n| `codedb-linux-x86_64` | `201dfe26bec33b3569c44a3d4893c51822bc793e06fab69fd93e81c0354232ee` |\n\nIf you installed `v0.2.579` before this hotfix, rerun the installer above so the\nbinary matches the final uploaded checksum for your platform.\n\n| Platform | Binary | Signed |\n|----------|--------|--------|\n| macOS ARM64 (Apple Silicon) | `codedb-darwin-arm64` | ✅ codesigned + notarized |\n| macOS x86_64 (Intel) | `codedb-darwin-x86_64` | ✅ codesigned + notarized |\n| Linux ARM64 | `codedb-linux-arm64` | — |\n| Linux x86_64 | `codedb-linux-x86_64` | — |\n\nOr install manually from [GitHub Releases](https://github.com/justrach/codedb/releases/latest).\n\n---\n\n## ⚡ Quick Start\n\n### As an MCP server (recommended)\n\nAfter installing, codedb is automatically registered. Just open a project and the 16 MCP tools are available to your AI agent.\n\n```bash\n# Manual MCP start (auto-configured by install script)\ncodedb mcp /path/to/your/project\n```\n\n### As an HTTP server\n\n```bash\ncodedb serve /path/to/your/project\n# listening on localhost:7719\n```\n\n### CLI\n\n```bash\ncodedb tree /path/to/project          # file tree with symbol counts\ncodedb outline src/main.zig           # symbols in a file\ncodedb find AgentRegistry             # find symbol definitions\ncodedb search \"handleAuth\"            # full-text search (trigram-accelerated)\ncodedb word Store                     # exact word lookup (inverted index, O(1))\ncodedb hot                            # recently modified files\n```\n\n---\n\n## 🔧 MCP Tools\n\n16 tools over the Model Context Protocol (JSON-RPC 2.0 over stdio):\n\n| Tool | Description |\n|------|-------------|\n| `codedb_tree` | Full file tree with language, line counts, symbol counts |\n| `codedb_outline` | Symbols in a file: functions, structs, imports, with line numbers |\n| `codedb_symbol` | Find where a symbol is defined across the codebase |\n| `codedb_search` | Trigram-accelerated full-text search (supports regex, scoped results) |\n| `codedb_word` | O(1) inverted index word lookup |\n| `codedb_hot` | Most recently modified files |\n| `codedb_deps` | Reverse dependency graph (which files import this file) |\n| `codedb_read` | Read file content (supports line ranges, hash-based caching) |\n| `codedb_edit` | Apply line-range edits (replace, insert, delete — atomic writes) |\n| `codedb_changes` | Changed files since a sequence number |\n| `codedb_status` | Index status (file count, current sequence) |\n| `codedb_snapshot` | Full pre-rendered JSON snapshot of the codebase |\n| `codedb_bundle` | Batch multiple read-only queries in one call (max 20 ops) |\n| `codedb_remote` | Query indexed public repos via api.wiki.codes — no local clone needed |\n| `codedb_projects` | List all locally indexed projects on this machine |\n| `codedb_index` | Index a local folder and create a codedb.snapshot |\n\n\n### `codedb_remote` — Cloud Intelligence\n\nQuery any indexed public GitHub repo without cloning it. `codedb_remote` always uses `api.wiki.codes`; the old `codegraff` backend name is no longer a supported route. Omit `backend`, or keep `backend=\"wiki\"` only for older prompts.\n\n```\n# Check what the remote slug supports\ncodedb_remote repo=\"vercel/next.js\" action=\"actions\"\n\n# Get a compact directory summary instead of dumping a huge file list\ncodedb_remote repo=\"vercel/next.js\" action=\"tree\" expand=false\n\n# Page a file tree by prefix and limit\ncodedb_remote repo=\"vercel/next.js\" action=\"tree\" prefix=\"packages/\" limit=100\n\n# Search for code in a dependency\ncodedb_remote repo=\"justrach/merjs\" action=\"search\" query=\"handleRequest\"\n\n# Read a small file slice\ncodedb_remote repo=\"openai/codex\" action=\"read\" path=\"codex-rs/core/src/codex.rs\" lines=\"1-80\"\n\n# Exact symbol lookup\ncodedb_remote repo=\"justrach/codedb\" action=\"symbol\" query=\"buildSnapshot\"\n\n# Check dependency CVE evidence; scope can be runtime or all\ncodedb_remote repo=\"axios/axios\" action=\"cves\" scope=\"runtime\"\n\n# Raw wiki slugs are accepted for repos that are indexed that way\ncodedb_remote repo=\"chromium\" action=\"policy\"\n```\n\n**Remote actions:** `actions`, `tree`, `outline`, `search`, `read`, `symbol`, `policy`, `deps`, `score`, `cves`, `commits`, `branches`, `dep-history`\n\nFor Codex and Claude Code hook examples around `codedb_remote`, see [`docs/hooks-labs.md`](docs/hooks-labs.md).\n\n**Note:** This tool calls `https://api.wiki.codes`. No API key required. The repo must already be indexed by the public service.\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `codedb tree` | Show file tree with language and symbol counts |\n| `codedb outline \u003cpath\u003e` | List all symbols in a file |\n| `codedb find \u003cname\u003e` | Find where a symbol is defined |\n| `codedb search \u003cquery\u003e` | Full-text search (trigram, case-insensitive) |\n| `codedb search --regex \u003cpattern\u003e` | Regex search |\n| `codedb word \u003cidentifier\u003e` | Exact word lookup via inverted index |\n| `codedb hot` | Recently modified files |\n| `codedb snapshot` | Write codedb.snapshot to project root |\n| `codedb serve` | HTTP daemon on :7719 |\n| `codedb mcp [path]` | JSON-RPC/MCP server over stdio |\n| `codedb update` | Self-update to the latest release; if it fails on an older build, rerun the curl installer above |\n| `codedb nuke` | Uninstall codedb, remove caches/snapshots, and deregister MCP integrations |\n| `codedb --version` | Print version |\n\n**Options:** `--no-telemetry` (or set `CODEDB_NO_TELEMETRY` env var)\n\n### Example: agent explores a codebase\n\n```bash\n# 1. Get the file tree\ncurl localhost:7719/tree\n# → src/main.zig      (zig, 55L, 4 symbols)\n#   src/store.zig     (zig, 156L, 12 symbols)\n#   src/agent.zig     (zig, 135L, 8 symbols)\n\n# 2. Drill into a file\ncurl \"localhost:7719/outline?path=src/store.zig\"\n# → L20: struct_def Store\n#   L30: function init\n#   L55: function recordSnapshot\n\n# 3. Find a symbol across the codebase\ncurl \"localhost:7719/symbol?name=AgentRegistry\"\n# → {\"path\":\"src/agent.zig\",\"line\":30,\"kind\":\"struct_def\"}\n\n# 4. Full-text search\ncurl \"localhost:7719/search?q=handleAuth\u0026max=10\"\n\n# 5. Check what changed\ncurl \"localhost:7719/changes?since=42\"\n```\n\n---\n\n## 📊 Benchmarks\n\nMeasured on Apple M4 Pro, 48GB RAM. MCP = pre-indexed warm queries (20 iterations avg). CLI/external tools include process startup (3 iterations avg). Ground truth verified against Python reference implementation.\n\n### Latency — codedb MCP vs codedb CLI vs ast-grep vs ripgrep vs grep\n\n**codedb repo** (20 files, 12.6k lines):\n\n| Query | codedb MCP | codedb CLI | ast-grep | ripgrep | grep | MCP speedup |\n|-------|-----------|-----------|----------|---------|------|-------------|\n| File tree | **0.04 ms** | 52.9 ms | — | — | — | **1,253x** vs CLI |\n| Symbol search (`init`) | **0.10 ms** | 54.1 ms | 3.2 ms | 6.3 ms | 6.5 ms | **549x** vs CLI |\n| Full-text search (`allocator`) | **0.05 ms** | 60.7 ms | 3.2 ms | 5.3 ms | 6.6 ms | **1,340x** vs CLI |\n| Word index (`self`) | **0.04 ms** | 59.7 ms | n/a | 7.2 ms | 6.5 ms | **1,404x** vs CLI |\n| Structural outline | **0.05 ms** | 53.5 ms | 3.1 ms | — | 2.4 ms | **1,143x** vs CLI |\n| Dependency graph | **0.05 ms** | 2.2 ms | n/a | n/a | n/a | **45x** vs CLI |\n\n**merjs repo** (100 files, 17.3k lines):\n\n| Query | codedb MCP | codedb CLI | ast-grep | ripgrep | grep | MCP speedup |\n|-------|-----------|-----------|----------|---------|------|-------------|\n| File tree | **0.05 ms** | 54.0 ms | — | — | — | **1,173x** vs CLI |\n| Symbol search (`init`) | **0.07 ms** | 54.4 ms | 3.4 ms | 6.3 ms | 3.6 ms | **758x** vs CLI |\n| Full-text search (`allocator`) | **0.03 ms** | 54.1 ms | 2.9 ms | 5.1 ms | 3.7 ms | **1,554x** vs CLI |\n| Word index (`self`) | **0.04 ms** | 54.7 ms | n/a | 6.3 ms | 4.2 ms | **1,518x** vs CLI |\n| Structural outline | **0.04 ms** | 54.9 ms | 3.4 ms | — | 2.5 ms | **1,243x** vs CLI |\n\n**rtk-ai/rtk repo** (329 files) — codedb vs rtk vs ripgrep vs grep:\n\n| Tool | Search \"agent\" | Speedup |\n|------|---------------|---------|\n| codedb (pre-indexed) | **0.065 ms** | baseline |\n| rtk | 37 ms | 569x slower |\n| ripgrep | 45 ms | 692x slower |\n| grep | 80 ms | 1,231x slower |\n\n### Token Efficiency\n\ncodedb returns structured, relevant results — not raw line dumps. For AI agents, this means dramatically fewer tokens per query:\n\n| Repo | codedb MCP | ripgrep / grep | Reduction |\n|------|-----------|---------------|-----------|\n| codedb (search `allocator`) | ~20 tokens | ~32,564 tokens | **1,628x fewer** |\n| merjs (search `allocator`) | ~20 tokens | ~4,007 tokens | **200x fewer** |\n\n### Indexing Speed\n\ncodedb v0.2.57 uses worker-local parallel scan with deterministic merge — each worker builds its own partial index, then results are merged on the main thread:\n\n| Repo | Files | Cold start | Per file | vs v0.2.56 |\n|------|-------|-----------|----------|-----------|\n| codedb | 20 | **17 ms** | 0.85 ms | — |\n| merjs | 100 | **16 ms** | 0.16 ms | — |\n| 5,200 mixed files | 5,200 | **310 ms** | 0.06 ms | — |\n| [openclaw/openclaw](https://github.com/openclaw/openclaw) | 6,315 | **346 ms** | 0.05 ms | **10× faster** |\n\nIndexes are built once on startup. After that, the file watcher keeps them updated incrementally (single-file re-index: **\u003c2ms**). Queries never re-scan the filesystem. For repos \u003e1000 files, file contents are released after indexing to save ~300-500MB.\n\n### Background Resource Usage (`openclaw`, 6,315 files, Apple M4 Pro)\n\n| Metric | v0.2.56 | v0.2.57 | Delta |\n|--------|---------|---------|-------|\n| Steady-state RSS | 1,867 MB | 1,706 MB | −161 MB |\n| `git` subprocesses / min (idle) | ~30 | ~0 | **mtime-gated** |\n\nThe watcher now stats `.git/HEAD` mtime before forking `git rev-parse HEAD`. On an idle repo the subprocess never fires.\n### Why codedb is fast\n\n- **MCP server** indexes once on startup → all queries hit in-memory data structures (O(1) hash lookups)\n- **CLI** pays ~55ms process startup + full filesystem scan on every invocation\n- **ast-grep** re-parses all files through tree-sitter on every call (~3ms)\n- **ripgrep/grep** brute-force scan every file on every call (~5-7ms)\n- The MCP advantage: **index once, query thousands of times at sub-millisecond latency**\n\n### Feature Matrix\n\n| Feature | codedb MCP | codedb CLI | ast-grep | ripgrep | grep | ctags |\n|---------|-----------|-----------|----------|---------|------|-------|\n| Structural parsing | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |\n| Trigram search index | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Inverted word index | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Dependency graph | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Version tracking | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Multi-agent locking | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Pre-indexed (warm) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| No process startup | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| MCP protocol | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Full-text search | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |\n| Atomic file edits | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |\n| File watcher | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |\n\n\u003e **codedb = tree-sitter + search index + dependency graph + agent runtime.** Zero external dependencies. Pure Zig. Single binary.\n\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────┐     ┌─────────────┐\n│  HTTP :7719 │     │  MCP stdio  │\n│  server.zig │     │  mcp.zig    │\n└──────┬──────┘     └──────┬──────┘\n       │                   │\n       └───────┬───────────┘\n               │\n    ┌──────────▼──────────┐\n    │     Explorer        │\n    │   explore.zig       │\n    │  ┌───────────────┐  │\n    │  │ WordIndex      │  │\n    │  │ TrigramIndex   │  │\n    │  │ Outlines       │  │\n    │  │ Contents       │  │\n    │  │ DepGraph       │  │\n    │  └───────────────┘  │\n    └──────────┬──────────┘\n               │\n    ┌──────────▼──────────┐\n    │      Store          │──── data.log\n    │    store.zig        │\n    └──────────┬──────────┘\n               │\n    ┌──────────▼──────────┐\n    │     Watcher         │ ← polls every 2s\n    │   watcher.zig       │\n    │  (FilteredWalker)   │\n    └─────────────────────┘\n```\n\n**No SQLite. No dependencies.** Purpose-built data model:\n\n- **Explorer** — structural index engine. Parses Zig, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, and Dart. Maintains outlines, trigram index, inverted word index, content cache, and dependency graph behind a single mutex.\n- **Store** — append-only version log. Every mutation (snapshot, edit, delete) gets a monotonically increasing sequence number. Version history capped at 100 per file.\n- **Watcher** — polling file watcher (2s interval). `FilteredWalker` prunes `.git`, `node_modules`, `zig-cache`, `__pycache__`, etc. before descending.\n- **Agents** — first-class structs with cursors, heartbeats, and exclusive file locks. Stale agents reaped after 30s.\n\n### Threading Model\n\n| Thread | Role |\n|--------|------|\n| Main | HTTP accept loop or MCP read loop |\n| Watcher | Polls filesystem every 2s via `FilteredWalker` |\n| ISR | Rebuilds snapshot when stale flag is set |\n| Reap | Cleans up stale agents every 5s |\n| Per-connection | HTTP server spawns a thread per connection |\n\nAll threads share a `shutdown: atomic.Value(bool)` for graceful termination.\n\n---\n\n## 🔒 Data \u0026 Privacy\n\ncodedb collects anonymous usage telemetry to improve the tool. Telemetry is **on by default** — written to `~/.codedb/telemetry.ndjson` and periodically synced to the codedb analytics endpoint. **No source code, file contents, file paths, or search queries are collected** — only aggregate tool call counts, latency, and startup stats.\n\n| Location | Contents | Purpose |\n|----------|----------|---------|\n| `~/.codedb/projects/\u003chash\u003e/` | Trigram index, frequency table, data log | Persistent index cache |\n| `~/.codedb/telemetry.ndjson` | Aggregate tool calls and startup stats | Local telemetry log |\n| `./codedb.snapshot` | File tree, outlines, content, frequency table | Portable snapshot for instant MCP startup |\n\n**Not stored:** No source code is sent anywhere. No file contents, file paths, or search queries are collected in telemetry. Sensitive files auto-excluded (`.env*`, `credentials.json`, `secrets.*`, `.pem`, `.key`, SSH keys, AWS configs).\n\nTo disable telemetry: set `CODEDB_NO_TELEMETRY=1` or pass `--no-telemetry`.\n\nTo sync the local NDJSON file into Postgres for analysis or dashboards, use [`scripts/sync-telemetry.py`](./scripts/sync-telemetry.py) with the schema in [`docs/telemetry/postgres-schema.sql`](./docs/telemetry/postgres-schema.sql). The data flow is documented in [`docs/telemetry.md`](./docs/telemetry.md).\n\n```bash\ncodedb nuke                # uninstall binary, clear caches/snapshots, remove MCP registrations\nrm -rf ~/.codedb/          # cache-only cleanup if you want to keep the binary installed\nrm -f codedb.snapshot      # remove snapshot from current project only\n```\n\n---\n\n## 🔨 Building from Source\n\n**Requirements:** Zig 0.15+\n\n```bash\ngit clone https://github.com/justrach/codedb.git\ncd codedb\nzig build                              # debug build\nzig build -Doptimize=ReleaseFast       # release build\nzig build test                         # run tests\nzig build bench                        # run benchmarks\n```\n\nBinary: `zig-out/bin/codedb`\n\n### Cross-compilation\n\n```bash\nzig build -Doptimize=ReleaseFast -Dtarget=x86_64-linux\nzig build -Doptimize=ReleaseFast -Dtarget=aarch64-linux\nzig build -Doptimize=ReleaseFast -Dtarget=x86_64-macos\n```\n\n### Releasing\n\n```bash\n./release.sh 0.2.0              # build, codesign, notarize, upload to GitHub Releases\n./release.sh 0.2.0 --dry-run    # preview without executing\n```\n\n---\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustrach%2Fcodedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustrach%2Fcodedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustrach%2Fcodedb/lists"}