{"id":50388255,"url":"https://github.com/0xsyncroot/codewiki","last_synced_at":"2026-05-30T16:30:33.422Z","repository":{"id":360196800,"uuid":"1249058034","full_name":"0xsyncroot/codewiki","owner":"0xsyncroot","description":"Code intelligence over a tree-sitter knowledge graph — MCP server + CLI + interactive graph UI for AI agents. 18 languages, 16 frameworks, i18n search. Rust.","archived":false,"fork":false,"pushed_at":"2026-05-25T13:03:10.000Z","size":1499,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T13:13:24.359Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xsyncroot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T10:01:57.000Z","updated_at":"2026-05-25T13:03:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0xsyncroot/codewiki","commit_stats":null,"previous_names":["0xsyncroot/codewiki"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/0xsyncroot/codewiki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fcodewiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fcodewiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fcodewiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fcodewiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xsyncroot","download_url":"https://codeload.github.com/0xsyncroot/codewiki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fcodewiki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33700863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-05-30T16:30:32.614Z","updated_at":"2026-05-30T16:30:33.416Z","avatar_url":"https://github.com/0xsyncroot.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeWiki\n\n**Local code knowledge graph for AI agents. Tree-sitter parsed, SQLite stored, MCP served.**\n\n[![CI](https://github.com/0xsyncroot/codewiki/actions/workflows/ci.yml/badge.svg)](https://github.com/0xsyncroot/codewiki/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.2.1-green.svg)](CHANGELOG.md)\n[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://www.rust-lang.org)\n\nInstead of reading whole source files, your AI agent asks the graph:\n\n```\ncodewiki_callers(\"OrderService\")   → 3 ms, exact answer\ncodewiki_impact(\"AuthService\")     → 6 ms, full blast radius\ncodewiki_context(\"basket checkout\")→ 4 ms, ranked entry points + key code\n```\n\nMeasured across **11 real-world repos and 157 tasks** (Python, Rust, TypeScript,\nJavaScript, C#, Java, C++, Go — from 83-file libraries up to the 2k-file jellyfin .NET\nserver, the 17k-file kubernetes, and the 39k-file TypeScript compiler), CodeWiki uses\n**~74% fewer tool-calls and ~98% fewer tokens** than grepping and reading files, at\n**near-identical recall (0.88 vs 0.92)**. 100% local, single static binary — no cloud,\nno telemetry, no API keys.\n\n---\n\n## Table of contents\n\n- [What it is](#what-it-is)\n- [Why it pays off](#why-it-pays-off)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [MCP tools](#mcp-tools)\n- [Editor and agent support](#editor-and-agent-support)\n- [CLI commands](#cli-commands)\n- [Graph UI](#graph-ui)\n- [Maintenance and incremental sync](#maintenance-and-incremental-sync)\n- [Performance](#performance)\n- [Languages and frameworks](#languages-and-frameworks)\n- [Enterprise](#enterprise)\n- [Architecture](#architecture)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What it is\n\nCodeWiki parses your codebase with [tree-sitter](https://tree-sitter.github.io/tree-sitter/)\nand stores the result in a local SQLite knowledge graph: nodes (functions, classes,\ninterfaces, enums, structs, routes, components) and typed edges (calls, imports,\ninherits, implements, route-to-handler, DI bindings).\n\nThe graph is exposed to AI coding agents via a\n[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server —\n9 `codewiki_*` tools that Claude Code, Cursor, Codex, and other MCP-capable agents call\nover stdio JSON-RPC. Agents get sub-millisecond structural answers instead of reading\nfiles, and the index is built once then maintained automatically (see\n[*Maintenance*](#maintenance-and-incremental-sync)).\n\nKey properties:\n\n- **18 languages** — C, C++, C#, Dart, Go, Java, JavaScript, Kotlin, Lua, Pascal, PHP,\n  Python, Ruby, Rust, Scala, Swift, TypeScript, and Vue\n  (plus additional component/template grammars; see\n  [*Languages and frameworks*](#languages-and-frameworks)).\n- **16 framework resolvers** — Angular, ASP.NET / Razor, Django, Express, FastAPI, Flask,\n  NestJS, Rails, Laravel, React, Vue, Svelte, Spring, Gin (Go web), Vapor (Swift web),\n  and Cargo workspaces.\n- **FTS5 full-text search** — Unicode-aware BM25 ranking with hybrid graph-path scoring.\n- **Fully incremental** — a 1-file change re-syncs in tens of milliseconds; the rest of\n  the graph is untouched (see [*Maintenance*](#maintenance-and-incremental-sync)).\n- **Docstring extraction** — Python, Rust, Go, TypeScript/JavaScript, C#.\n- **100% local** — grammars are bundled in the binary; no network access after install.\n\n---\n\n## Why it pays off\n\nAn MCP-driven agent-savings harness runs **6 task archetypes** (locate, callers, callees,\nfeature, impl, blast) over **11 real repos across four size tiers** — **157 cases** — and\ncompares CodeWiki to a **grep + read-full-files baseline**, the surface a tool-less agent\nactually uses. Every answer is scored for recall against a frozen ground-truth oracle (the\nbaseline is scored on the *identical* oracle). Tokens = output bytes ÷ 4 (conservative).\nPricing: Claude Sonnet $3.00 / 1M input tokens. Fresh cold run on `codewiki 0.2.0`. Full\nmethodology, recall caveat, and raw data: [`benchmark/README.md`](benchmark/README.md)\n(source: [`results-savings.tsv`](benchmark/results-savings.tsv)).\n\n| Language | Repo | Files | Tool-call reduction | Token reduction |\n|----------|------|------:|:-------------------:|:---------------:|\n| C++ | nlohmann/json | 499 | 69% | **98%** |\n| Go | gin-gonic/gin | 99 | 75% | **96%** |\n| TypeScript | colinhacks/zod | 408 | 62% | **99%** |\n| Rust | BurntSushi/ripgrep | 101 | 75% | **98%** |\n| Python | pallets/flask | 83 | 65% | **95%** |\n| Java | google/gson | 262 | 77% | **95%** |\n| JavaScript | expressjs/express | 141 | 60% | **95%** |\n| C# | dotnet-architecture/eShopOnWeb | 269 | 78% | **79%** |\n| **Overall** | **157 cases / 11 repos** | — | **74%** | **98%** |\n\nAcross all 157 cases (155 scored) CodeWiki uses **74% fewer tool-calls and 98% fewer\ntokens** than grep+read, saving **~$16.98** of input tokens over the run. The token win is\nso large because the baseline reads whole candidate files while CodeWiki returns a small,\nranked, structurally-resolved slice. (C#'s 79% on eShopOnWeb is a small-repo artefact: its\nfiles are already cheap to read, so there is little to save — on the large .NET repo\njellyfin the same six archetypes hit **98%**; recall stays on par, 0.87 vs 0.94.)\n\n**The saving grows with repo size.** CodeWiki's per-query answer stays bounded\n(~0.6–1.4k tokens) no matter how big the codebase, while the grep+read baseline explodes:\n\n| Size tier | Repos | Avg CW tokens/query | Avg baseline tokens/query | Token reduction |\n|-----------|-------|--------------------:|--------------------------:|:---------------:|\n| Small (\u003c300 files) | flask, express, gin, eShopOnWeb, ripgrep | 601 | 16,142 | **96%** |\n| Medium (300–700) | zod, gson, json | 935 | 51,079 | **98%** |\n| Large .NET (~2k .cs) | jellyfin | 1,442 | 69,365 | **98%** |\n| Enterprise (\u003e15k) | kubernetes (17k), microsoft/TypeScript (39k) | 865 | **108,573** | **99%** |\n\nOn a 17k–39k-file monorepo a single scoped grep plus the file reads it forces costs\n**~109k tokens per query**; CodeWiki answers the same task in ~900. The biggest codebases\n— where agent token budgets hurt most — are where CodeWiki saves the most.\n\n**Honest recall note.** CodeWiki now **nearly matches** the baseline's completeness while\nkeeping the token/call win: mean recall is **0.88 for CodeWiki vs 0.92 for the grep+read\nbaseline** (0.877 vs 0.921 over the 155 scored cases). The oracle is not rigged for\nCodeWiki — the baseline still *edges* recall, and CodeWiki delivers *near-baseline answers\nat ~2% of the tokens*. CodeWiki *wins* recall on 30 of the 155 scored cases (structural\n`callees`/`impl`/`blast` tasks), loses on 29 (almost all `feature`-comprehension queries —\nthe residual gap is concentrated there), and ties on the rest. Two cases (C# `EfRepository`\nblast, Go `Reconciler` impl) are kept **UNSCORABLE** on purpose — we will not score\nCodeWiki against an oracle derived from its own newly-synthesized edges. The suite keeps\nhard and expected-to-lose cases (overloaded names, deep `feature` tasks, high-fanout blast\nradius) — no cherry-picking. Full methodology, weakness analysis, per-case breakdown, and\nthe disclosure of what changed since the prior report:\n[`benchmark/README.md`](benchmark/README.md).\n\nThe savings compound: the index is built once and maintained automatically at a per-edit\ncost in milliseconds (see [*Maintenance*](#maintenance-and-incremental-sync)), so every\nsubsequent query is effectively free.\n\n### Worked example — 5 .NET tasks\n\n\u003e **Different baseline.** This per-task trace uses a more economical\n\u003e **grep-then-read-*minimal*-files** baseline (read only the files a task strictly needs),\n\u003e not the read-*whole*-files baseline of the cross-language table above. That is why the\n\u003e token reduction here (~83%) is lower than the headline 97% — both are honest; they\n\u003e simply measure against different baselines. Full trace:\n\u003e [`benchmark/README.md`](benchmark/README.md) (§4 .NET worked example).\n\nMeasured across 5 realistic tasks on eShopOnWeb (254 .cs) and jellyfin (2,065 .cs), freshly\nre-run on `codewiki 0.2.0`. Byte counts from real CLI output and file sizes; tokens =\nbytes ÷ 4 (conservative). Pricing: Claude Sonnet $3.00 / 1M input tokens.\n\n| Task | CW calls | Baseline calls | Call reduction | CW tokens | Baseline tokens | Token reduction | $ saved |\n|------|:--------:|:--------------:|:--------------:|:---------:|:---------------:|:--------------:|:-------:|\n| DI consumers (`IBasketService`) | 2 | 6 | **67%** | 380 | 3,476 | **89%** | $0.009 |\n| Feature comprehension (basket checkout) | 1 | 6 | **83%** | 1,017 | 6,842 | **85%** | $0.018 |\n| Interface→impls (`IRepository`) | 2 | 6 | **67%** | 624 | 4,219 | **85%** | $0.011 |\n| Blast radius (`OrderService` refactor) | 1 | 5 | **80%** | 246 | 1,959 | **87%** | $0.005 |\n| Cross-cutting: auth config (jellyfin) | 2 | 4 | **50%** | 2,034 | 8,158 | **75%** | $0.018 |\n| **Average** | **1.6** | **5.4** | **70%** | **860** | **4,930** | **83%** | **$0.012** |\n\nInterface→impl queries traverse real `implements` edges — `codewiki impact IRepository`\nreturns the concrete `EfRepository` implementation directly (Task 3).\n\n---\n\n## Install\n\nCodeWiki ships as a **single self-contained binary** — all tree-sitter grammars are\nbundled, with no runtime dependencies. Every GitHub Release attaches CI-built binaries\nfor four targets, each with a matching SHA-256 checksum. **No toolchain, no compiling,\nno cloning required.**\n\n### 1. One-liner (recommended)\n\nThe install scripts auto-detect your platform, download the matching pre-built binary\nfrom the **latest** GitHub Release, verify its SHA-256 checksum, and place `codewiki`\non your PATH. Nothing is compiled.\n\n**Linux / macOS:**\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/0xsyncroot/codewiki/main/install.sh | sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://raw.githubusercontent.com/0xsyncroot/codewiki/main/install.ps1 | iex\n```\n\n**Install location:** `~/.local/bin` on Unix, `%LOCALAPPDATA%\\Programs\\codewiki` on\nWindows (added to your user PATH automatically on Windows). Override with `--dir \u003cpath\u003e`\n(sh) or `-Dir \u003cpath\u003e` (PowerShell).\n\n**Pin a version** instead of taking the latest:\n\n```sh\n# Linux / macOS\ncurl -fsSL https://raw.githubusercontent.com/0xsyncroot/codewiki/main/install.sh | sh -s -- --version v0.2.1\n```\n\n```powershell\n# Windows PowerShell\n\u0026 ([scriptblock]::Create((irm https://raw.githubusercontent.com/0xsyncroot/codewiki/main/install.ps1))) -Version v0.2.1\n```\n\n### 2. Manual download\n\nPrefer not to pipe a script to your shell? Download the asset for your platform from the\n[Releases page](https://github.com/0xsyncroot/codewiki/releases), verify it, extract, and\nput `codewiki` on your PATH.\n\n| OS | Arch | Release asset |\n|----|------|---------------|\n| Linux | x86_64 | `codewiki-x86_64-unknown-linux-gnu.tar.gz` |\n| Linux | ARM64 | `codewiki-aarch64-unknown-linux-gnu.tar.gz` |\n| macOS | Apple Silicon | `codewiki-aarch64-apple-darwin.tar.gz` |\n| Windows | x86_64 | `codewiki-x86_64-pc-windows-msvc.zip` |\n\n\u003e macOS Intel (`x86_64`): build from source for now (see below) — a pre-built Intel binary will return in a later release.\n\nEach asset has a matching `\u003casset\u003e.sha256`. Download both, then verify and install:\n\n**Linux / macOS:**\n\n```sh\n# Replace \u003casset\u003e with the filename for your platform from the table above.\nsha256sum -c \u003casset\u003e.sha256        # macOS: shasum -a 256 -c \u003casset\u003e.sha256\ntar -xzf \u003casset\u003e                   # extracts ./codewiki\ninstall -m 755 codewiki ~/.local/bin/codewiki\n```\n\n**Windows (PowerShell):**\n\n```powershell\n# Verify: the printed hash must match the contents of the .sha256 file.\nGet-FileHash codewiki-x86_64-pc-windows-msvc.zip -Algorithm SHA256\nExpand-Archive codewiki-x86_64-pc-windows-msvc.zip -DestinationPath $env:LOCALAPPDATA\\Programs\\codewiki\n# Add %LOCALAPPDATA%\\Programs\\codewiki to your PATH.\n```\n\n### Verify the install\n\n```sh\ncodewiki --version\n# codewiki 0.2.1\n```\n\nThe binary includes every feature — graph UI, FTS5 search, full language support — by\ndefault. No extra flags needed.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e3. Build from source\u003c/b\u003e (optional — for development only)\u003c/summary\u003e\n\nEnd users do not need this; the installers above ship a verified pre-built binary.\nBuilding from source requires a recent stable Rust toolchain (CI builds on current\n`stable`):\n\n```sh\ngit clone https://github.com/0xsyncroot/codewiki\ncd codewiki\ncargo build --release   # binary: ./target/release/codewiki\n```\n\n\u003c/details\u003e\n\n---\n\n## Quick start\n\nCodeWiki is **wired into your agent once, machine-wide**, and then works in\nevery project you index. Two steps get you productive:\n\n**1. Wire your agent once (machine-wide).** Run this a single time per machine —\nnot per project:\n\n```sh\ncodewiki install --target claude\n# (or: cursor | codex | opencode | hermes | all)\n```\n\nThis registers `codewiki serve --mcp` as an MCP server in your agent's global\nconfig. One registration serves **every** project you open.\n\n**2. Index each project.** In each repository you want code intelligence for:\n\n```sh\ncodewiki init\n# Creates + indexes ./.codewiki/ (DB + git hooks).\n# Indexed 141 files, 2,291 nodes, 6,374 edges in 0.3s.\n```\n\nThat's it — restart your agent once after step 1, and from then on every\n`codewiki init`'d project is instantly available.\n\n**Why this works.** The MCP server is **cwd-aware**: it resolves the\n`.codewiki/` index from the project the agent is working in. So a single global\nregistration transparently serves all your projects. Open a project you haven't\nindexed yet and the tools stay live — they simply prompt you to run\n`codewiki init` to enable code intelligence there. After you `codewiki init` a\nproject that was already open, restart your agent (or reconnect the MCP server)\nso it picks up the new index.\n\n**Shortcut.** To do both steps for the current project in one command:\n\n```sh\ncodewiki setup\n# Indexes this project and wires your detected agent(s).\n```\n\nVerify everything is healthy at any time:\n\n```sh\ncodewiki doctor\n```\n\n`codewiki doctor` runs 6 checks: binary on PATH, index initialized, index non-empty,\nfreshness, agent wired (global or local), git hook installed.\n\n---\n\n## MCP tools\n\nAll 9 tools are served by `codewiki serve --mcp` (wired automatically by `codewiki install`).\nThe MCP server keeps the SQLite connection open — query latency is sub-millisecond.\n\n| Tool | Description |\n|------|-------------|\n| `codewiki_search` | Find a symbol by name — exact, fuzzy, or namespace-qualified |\n| `codewiki_context` | AI-focused context for a task description — ranked entry points + key code |\n| `codewiki_callers` | All call sites of a symbol |\n| `codewiki_callees` | Everything a symbol calls |\n| `codewiki_impact` | Transitive blast radius of changing a symbol (depth 3) |\n| `codewiki_node` | Symbol signature, source span, and docstring |\n| `codewiki_explore` | Several related symbols' source in one capped call |\n| `codewiki_files` | Indexed files under a directory path with metadata |\n| `codewiki_status` | Index health: file count, node/edge counts, DB size |\n\n---\n\n## Editor and agent support\n\nCodeWiki ships a standard [Model Context Protocol](https://modelcontextprotocol.io)\nstdio server (`codewiki serve --mcp`, JSON-RPC over stdin/stdout, protocol `2024-11-05`),\nso it works with **any MCP-compatible agent**. For the agents below, a one-command\ninstaller writes the MCP config (and agent instructions) for you:\n\n| Agent | Install command | Notes |\n|-------|-----------------|-------|\n| Claude Code | `codewiki install --target claude` | Writes `~/.claude.json` (global) or `./.mcp.json` (local); adds a CodeWiki block to `CLAUDE.md`. |\n| Cursor | `codewiki install --target cursor` | Writes `~/.cursor/mcp.json` (global) or `./.cursor/mcp.json` (local); local installs also add `./.cursor/rules/codewiki.mdc`. |\n| Codex CLI | `codewiki install --target codex` | Global only — writes `[mcp_servers.codewiki]` to `~/.codex/config.toml` and a block to `~/.codex/AGENTS.md`. |\n| opencode | `codewiki install --target opencode` | Writes `~/.config/opencode/opencode.jsonc` (global) or `./opencode.jsonc` (local); adds a block to `AGENTS.md`. |\n| Hermes Agent | `codewiki install --target hermes` | Global only — writes `mcp_servers.codewiki` to `$HERMES_HOME/config.yaml` (defaults to `~/.hermes/config.yaml`). |\n\nPass `--location local` to wire the current project instead of your user-wide config\n(Codex CLI and Hermes Agent are global-only). `codewiki install --target all` configures\nevery detected agent at once, and `codewiki setup` indexes the project and wires agents\nin a single step. Run `codewiki uninstall --target \u003cname\u003e` to cleanly remove a config.\n\n### Any other MCP client (manual)\n\nAny MCP-capable client — including editors and assistants without a first-class\ninstaller above — can use CodeWiki by registering the stdio server directly. The\ncanonical invocation is `codewiki serve --mcp`. A typical `mcpServers` entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"codewiki\": {\n      \"type\": \"stdio\",\n      \"command\": \"codewiki\",\n      \"args\": [\"serve\", \"--mcp\"]\n    }\n  }\n}\n```\n\nIf your client launches MCP servers without inheriting the project working directory,\nadd `--path` so CodeWiki finds the right index, e.g.\n`\"args\": [\"serve\", \"--mcp\", \"--path\", \"/abs/path/to/project\"]`. Place the entry in\nwhatever config file your client reads (the schema varies by client) and restart it.\n\n---\n\n## CLI commands\n\n**Common — start here:**\n\n```\ncodewiki setup        Index + wire MCP in one step  [START HERE]\ncodewiki status       Index statistics\ncodewiki doctor       Diagnostics and health checks\ncodewiki query        Search a symbol by name\ncodewiki context      AI-focused context for a task\n```\n\n**Advanced:**\n\n```\ncodewiki init         Initialize .codewiki/ for this project\ncodewiki index        Re-index all files (or --path \u003cdir\u003e)\ncodewiki sync         Sync changed files into the index\ncodewiki serve        MCP server (--mcp for stdio JSON-RPC)\ncodewiki files        List indexed files\ncodewiki callers      Callers of a symbol\ncodewiki callees      Callees of a symbol\ncodewiki impact       Blast radius of a symbol change\ncodewiki affected     Symbols affected by a set of changed files\n```\n\n**Management:**\n\n```\ncodewiki install      Wire agent configs (subset of setup)\ncodewiki uninstall    Remove from agent configs\ncodewiki uninit       Remove .codewiki/ from this project\ncodewiki snapshot     Export index to a portable SQLite file\ncodewiki restore      Restore index from a snapshot\n```\n\nRun `codewiki \u003ccommand\u003e --help` for full option details.\n\n---\n\n## Graph UI\n\n`codewiki graph` launches a local web viewer for interactive exploration of the\nknowledge graph:\n\n- **Force-directed graph** — nodes (functions, classes, routes, components) and edges\n  (calls, imports, inherits, implements) rendered in the browser\n- **Neighbourhood explorer** — click any node to focus on its immediate call graph\n- **Filter by kind and language** — narrow the view to classes, interfaces, routes, or\n  a specific language\n- **Node detail panel** — signature, file location, docstring, and related symbols\n- **Impact view** — highlight the transitive blast radius of a selected symbol\n\nThe graph UI is included in every default build:\n\n```sh\n# Launch (opens http://localhost:7007 by default):\ncodewiki graph\n\n# Custom port, no auto-open:\ncodewiki graph --port 8080 --no-open\n```\n\nFor a minimal binary without the graph UI (rare, e.g. server-side MCP-only deploys):\n\n```sh\ncargo build --release --no-default-features --features bundled-sqlite,wasmtime-grammars\n```\n\n---\n\n## Maintenance and incremental sync\n\n**The graph stays current automatically — at negligible cost.** This is the single\nauthoritative description of how the index is kept fresh; the savings sections above\ncross-link here rather than restate it.\n\n`codewiki init` installs two complementary auto-sync paths:\n\n- **Git hooks** (`post-commit`, `post-merge`, `post-checkout`) run `codewiki sync`\n  detached in the background after a commit, merge, or branch switch, so git is never\n  blocked. They work on **every** filesystem, including WSL `/mnt` drives.\n- **Live file watcher** inside `codewiki serve --mcp` re-syncs on file saves, using a\n  **2-second debounce** (`WatcherConfig::default()`) that coalesces a multi-file burst\n  into one sync cycle. The watcher does not fire on WSL `/mnt` (drvfs/9p) drives — inotify\n  events don't cross the 9p protocol — which is exactly why the git hooks exist as the\n  fallback there.\n\nIncremental sync is truly incremental: only changed files and their direct dependants are\nre-extracted and re-resolved, so sync time stays proportional to the change size, not the\nrepo size. A 2,065-file .NET repo re-syncs a single edit in 66 ms.\n\n**Measured 1-file sync (tool-reported parse/DB-write time, fresh on `codewiki 0.2.0`):**\n\n| Repo | Files | Sync time |\n|------|------:|:---------:|\n| flask (Python) | 83 | 22 ms |\n| express (JavaScript) | 141 | 21 ms |\n| zod (TypeScript) | 408 | 32 ms |\n| json (C++) | 499 | 43 ms |\n| jellyfin (C#, 2,065 .cs) | 2,065 | 66 ms |\n| kubernetes (Go, 17,176 files) | 17,176 | 74 ms |\n| microsoft/TypeScript (39,296 files) | 39,296 | 202 ms |\n\n**The cost story:** index once (~0.2–2.1 s for the per-language repos, ~1 min for the\n17k–39k-file monorepos), then maintain at tens of milliseconds per change. Use\n`codewiki index` instead of `sync` for whole-repo rewrites (a mass reformat is ~2× slower\nthrough the incremental path). Every subsequent query reuses the same graph for sub-ms\nresponses, so the ~98% token / ~74% tool-call savings (see\n[*Why it pays off*](#why-it-pays-off)) repeat every session.\n\n---\n\n## Performance\n\nFull tables, scale analysis, and the agent-savings study live in\n[`benchmark/README.md`](benchmark/README.md). All figures below are a fresh run on\n`codewiki 0.2.0`. Machine: Intel Core i7-14700KF (14 cores / 28 threads), 31 GiB RAM,\nWSL2.\n\n**Cross-language results — 8 real repos (one per language, shallow clones of `main`):**\n\nThis table is a **performance** benchmark — cold-index speed, search latency, and\nincremental sync. The token / tool-call savings for these same 8 repos are in\n[*Why it pays off*](#why-it-pays-off).\n\n| Repo | Language | Files | Cold-index | files/s | Search p50 | Sync (1 file) |\n|------|----------|------:|:----------:|--------:|:----------:|:-------------:|\n| pallets/flask | Python | 83 | 0.19 s | 430 | 3 ms | 22 ms |\n| BurntSushi/ripgrep | Rust | 101 | 0.36 s | 278 | 3 ms | 24 ms |\n| expressjs/express | JavaScript | 141 | 0.26 s | 542 | 2 ms | 21 ms |\n| colinhacks/zod | TypeScript | 408 | 0.57 s | 720 | 2 ms | 32 ms |\n| dotnet-architecture/eShopOnWeb | C# | 269 | 0.15 s | 1,793 | 2 ms | 27 ms |\n| google/gson | Java | 262 | 0.49 s | 538 | 3 ms | 33 ms |\n| nlohmann/json | C++ | 499 | 1.01 s | 494 | 4 ms | 43 ms |\n| gin-gonic/gin | Go | 99 | 0.26 s | 376 | 2 ms | 22 ms |\n\nAll 8 index cleanly — zero crashes, zero FK errors — including C++ (`nlohmann/json`,\n499 files, 13,438 graph nodes). \"Search p50\" is the `query` latency; `callers`/`callees`\nare comparable, `impact`/`context` run 2–33 ms depending on fan-out.\n\n**Scale:** holds to enterprise size. **kubernetes** (Go, 17,176 files) cold-indexes in\n**55 s** into a 208k-node / 971k-edge graph, and **microsoft/TypeScript** (the TS\ncompiler, 39,296 files) in **62 s** — both clean, exit 0, ~1.1–1.5 GB peak RSS. The\n100k-file cold-index extrapolates to **~14 min** (O(n^1.5), target ≤ 20 min) at ~4 GB\npeak RSS. Full scale table and the enterprise breakdown: [*Enterprise*](#enterprise) and\n[`benchmark/README.md`](benchmark/README.md).\n\n**Search latency** (CLI p50, includes binary cold-start):\n- Exact / fuzzy / callers / callees: **2–4 ms** across all 8 languages\n- Impact / context query: **2–33 ms** (varies with graph fan-out)\n- Via persistent MCP server: sub-millisecond\n\n---\n\n## Languages and frameworks\n\n**18 languages:**\n\nC, C++, C#, Dart, Go, Java, JavaScript, Kotlin, Lua, Pascal, PHP, Python,\nRuby, Rust, Scala, Swift, TypeScript, and Vue.\n\nPlus additional grammars for component, template, and form dialects — Svelte, Luau,\nLiquid, Razor, and Delphi form files (DFM).\n\n**16 framework resolvers:**\n\n| Framework | Extracted |\n|-----------|-----------|\n| **Angular** | `@Component` / `@Directive` / `@Pipe` / `@Injectable` / `@NgModule` nodes; DI constructor injection; routing (`loadComponent`, lazy routes, guards); standalone `imports:[]` bindings |\n| **ASP.NET / Razor** | HTTP routes (`[HttpGet/Post/Delete]`, minimal API, `MapGroup`, SignalR hubs); DI registrations; namespace-qualified symbols; interface / struct / enum / record discrimination; method signatures; `is_async` detection |\n| **Django** | URL patterns, views, models |\n| **Express** | Route handlers, middleware chains |\n| **FastAPI** | Route decorators, dependency injection |\n| **Flask** | Blueprint routes, view functions |\n| **NestJS** | Controllers, guards, interceptors, modules |\n| **Rails** | Routes (`resources`, `get/post`), controllers |\n| **Laravel** | Route facades, controllers |\n| **React** | Component exports, hook calls |\n| **Vue** | SFC components, `\u003cscript setup\u003e`, Composition API |\n| **Svelte** | Component exports, stores |\n| **Spring** | `@RequestMapping`, `@GetMapping`, beans |\n| **Gin (Go web)** | `r.GET/POST/…` routes for Gin / chi / Echo / gorilla mux / net/http → route nodes + handler resolution |\n| **Vapor (Swift web)** | `app/routes/router .get/post/…` routes; controller, Fluent model, and middleware resolution |\n| **Cargo workspace** | Workspace members → module nodes; inter-crate `use` resolution; path-dependency edges |\n\n---\n\n## Enterprise\n\nCodeWiki is production-tested on enterprise-scale codebases. All figures below are fresh\n`codewiki 0.2.0` runs on shallow clones:\n\n| Metric | Result |\n|--------|--------|\n| kubernetes (Go, 17,176 files) | 55 s index, 208,425 nodes / 970,801 edges, 779,688 refs resolved, 1.49 GB RSS, exit 0 |\n| microsoft/TypeScript (39,296 files) | 62 s index, 312,521 nodes / 442,014 edges, 1.11 GB RSS, exit 0 (clean, no crash) |\n| 100k-file cold index | ~14 min (extrapolated; on-curve with the measured 17k / 39k real-repo runs) |\n| 100k-file peak RAM | ~4 GB (extrapolated; sub-linear O(n^0.62) memory scaling) |\n| OrchardCore (5,203 .cs) | 9.0 s index, 72,345 nodes / 227,444 edges, 505 interfaces, 97 enums, 3,663 implements edges, fully qualified names |\n| jellyfin (2,065 .cs) | 2.1 s index, 19,911 nodes / 46,648 edges, 209 interfaces, 385 routes, 5,852 import edges, 1,019 async methods |\n| ABP framework (3,497 .cs) | 1.9 s index, 26,133 nodes / 50,632 edges, 623 interfaces, namespace-qualified (`Volo.Abp.Domain.Services::DomainService`) |\n| .NET enterprise verdict | **READY** — interfaces/enums/structs correctly classified, namespaces qualified, signatures stored, async detected, `implements` edges resolved |\n\nFull benchmark suite and .NET audit: [`benchmark/README.md`](benchmark/README.md).\n\n**Privacy:** all indexing and querying runs locally. No data leaves the machine.\nNo embedding model, no external API, no telemetry. Single static binary —\ncopy it anywhere, run it, works.\n\n---\n\n## Architecture\n\nCargo workspace under `crates/` — eight product crates plus a test-only helper\n(`codewiki-testutil`):\n\n| Crate | Role |\n|-------|------|\n| `codewiki-cli` | Binary entry point, `clap` CLI, installer, onboarding UI |\n| `codewiki-mcp` | MCP server (rmcp, stdio JSON-RPC), 9 tool handlers |\n| `codewiki-extraction` | tree-sitter AST walker, 18-language extractors, docstring extraction |\n| `codewiki-storage` | SQLite schema, FTS5 Unicode search, WAL mode, graph query API |\n| `codewiki-resolution` | Import resolver, 16 framework resolvers, name matcher, incremental pipeline |\n| `codewiki-sync` | File watcher (`notify`), gitignore walk, git hook installation |\n| `codewiki-core` | Shared types: `Node`, `Edge`, `CodeWikiError`, `Config` |\n| `codewiki-graph` | Graph web UI (axum HTTP, embedded force-graph frontend) |\n\nData flow: **tree-sitter extraction** → **SQLite / FTS5** → **reference resolution** → **graph edges** → **MCP tools** / **graph UI**.\n\n---\n\n## Roadmap\n\n- **wiki-md generation** — generate structured Markdown documentation from the graph\n  (per-module API docs, architecture diagrams, call-graph narratives) as a first-class\n  output format. This is the next major capability after the graph itself.\n\n---\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for build, test, and\npull-request guidelines, and the [code of conduct](CODE_OF_CONDUCT.md) for community\nexpectations. To report a security issue, follow the process in [SECURITY.md](SECURITY.md).\nBenchmark methodology and how to reproduce the numbers live in\n[`benchmark/README.md`](benchmark/README.md).\n\n---\n\n## License\n\nMIT licensed (© 2026 0xsyncroot). See [LICENSE](LICENSE). As a derivative work of\nCodeGraph, the CodeGraph attribution and a verbatim copy of its original MIT copyright\nnotice (© 2026 Colby McHenry) are reproduced in [NOTICE](NOTICE), as the MIT License\nrequires. Third-party crate and tree-sitter grammar attributions are listed in\n[LICENSE-THIRD-PARTY.md](LICENSE-THIRD-PARTY.md) (generated by `cargo about`).\n\n---\n\n## Credits\n\nCodeWiki is a Rust port and derivative of [CodeGraph](https://github.com/colbymchenry/codegraph)\nby Colby McHenry (MIT). It reimplements CodeGraph's architecture in Rust — including\nthe SQLite schema, resolution algorithms, search/scoring, and MCP tool interface —\nwith added optimisations, framework resolvers (Angular, full ASP.NET / .NET), a graph\nweb UI, and i18n / Unicode search. See [NOTICE](NOTICE) for the full attribution,\nwhich reproduces CodeGraph's original MIT copyright notice as required.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xsyncroot%2Fcodewiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xsyncroot%2Fcodewiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xsyncroot%2Fcodewiki/lists"}