{
"markdown": "\n\n# Codemesh\n\n**Intelligent code knowledge graph for AI coding agents**\n\n**71% cheaper, 72% faster, 82% fewer tool calls** vs baseline Grep+Read\\\non 6 real-world repos (Sonnet 4.6) — from a single `codemesh index`.\n\n[](https://www.npmjs.com/package/@pyalwin/codemesh)\n[]()\n[]()\n[]()\n[]()\n\n[Benchmarks](#benchmarks) · [Quick Start](#quick-start) · [Integrations](#client-integrations) · [Write-Back](#agent-write-back-the-graph-that-gets-smarter) · [How It Works](#how-it-works) · [API Reference](#mcp-tools) · [Full Results](docs/benchmark-results.md)\n\n
\n\n---\n\n## The Problem\n\nAI coding agents waste **40-80% of their tokens on discovery** — grepping through files, reading irrelevant code, and rebuilding context they've already seen in previous sessions.\n\nOn a 600-file codebase, a typical exploration task involves 10+ file reads before the agent even knows what's relevant.\n\n```\nBefore: Agent → Grep → 50 matches → Read 10 files → Understand → Work\nAfter: Agent → codemesh_explore → 3 relevant files → codemesh_trace → full path → Work\n```\n\nCodemesh is an MCP server that gives agents a persistent, queryable knowledge graph. The graph gets smarter over time: agents write back what they learn, so the next session starts informed.\n\n---\n\n## Benchmarks\n\nBenchmarked on 6 real-world codebases (Alamofire, Excalidraw, VS Code, Swift Compiler, pydantic-validators, pydantic-basemodel) with Claude Sonnet 4.6, compared alongside baseline and graph-based approaches for context.\n\nFull methodology, per-repo breakdowns, and pairwise comparisons: [`docs/benchmark-results.md`](docs/benchmark-results.md) | [Early pydantic evals](docs/experiments/pydantic-eval-results.md)\n\n### Cost\n\n| Mode | Alamofire | Excalidraw | VS Code | Swift Compiler[^swift] | pydantic-validators | pydantic-basemodel | **Avg** |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| Baseline | $0.54 | $0.89 | $0.21 | $0.83 | $1.32 | $0.78 | $0.76 |\n| **Codemesh MCP** | **$0.25** | **$0.21** | **$0.16** | **$0.23** | **$0.33** | **$0.13** | **$0.22** |\n| Codemesh CLI | $0.67 | $0.51 | $0.16 | $0.83 | $1.00 | $0.18 | $0.56 |\n| Codegraph | $0.37 | $0.56 | $0.57 | $0.74 | $0.29 | $0.19 | $0.45 |\n\n### Time\n\n| Mode | Alamofire | Excalidraw | VS Code | Swift[^swift] | pydantic-v | pydantic-b | **Avg** |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| Baseline | 180s | 191s | 87s | 199s | 352s | 232s | 207s |\n| **Codemesh MCP** | **78s** | **45s** | **35s** | **87s** | **72s** | **32s** | **58s** |\n| Codemesh CLI | 226s | 177s | 62s | 227s | 235s | 51s | 163s |\n| Codegraph | 134s | 180s | 192s | 199s | 75s | 60s | 140s |\n\n### Tool calls (agent turns)\n\n| Mode | Alamofire | Excalidraw | VS Code | Swift[^swift] | pydantic-v | pydantic-b | **Avg** |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| Baseline | 31 | 48 | 12 | 29 | 84 | 65 | 45 |\n| **Codemesh MCP** | **9** | **5** | **3** | **14** | **14** | **3** | **8** |\n| Codemesh CLI | 30 | 32 | 12 | 56 | 64 | 9 | 34 |\n| Codegraph | 31 | 35 | 44 | 44 | 20 | 12 | 31 |\n\n### Quality (1–10, LLM-as-judge)\n\n| Mode | Alamofire[^alamo] | Excalidraw | VS Code | Swift Compiler | pydantic-validators | pydantic-basemodel | **Avg** |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| Baseline | n/a | 9 | 8 | 7 | 2 | 9 | 7.0 |\n| **Codemesh MCP** | 9 | 9 | 7 | 8 | 7 | 7.8 | **7.9** |\n| Codemesh CLI | 9 | 7 | 7 | 9 | 1 | 8.4 | 6.9 |\n| Codegraph | 8 | 9 | 8.7 | 8 | 8 | 9 | **8.4** |\n\n### Cost savings: Codemesh MCP vs Baseline\n\n| Repo | Baseline | Codemesh MCP | **Cost saved** | **Time saved** |\n|---|---:|---:|---:|---:|\n| Alamofire | $0.54 | $0.25 | **−54%** | **−57%** (180s → 78s) |\n| Excalidraw | $0.89 | $0.21 | **−76%** | **−76%** (191s → 45s) |\n| VS Code | $0.21 | $0.16 | **−24%** | **−60%** (87s → 35s) |\n| Swift Compiler[^swift] | $0.83 | $0.23 | **−72%** | **−56%** (199s → 87s) |\n| pydantic-validators | $1.32 | $0.33 | **−75%** | **−79%** (352s → 72s) |\n| pydantic-basemodel | $0.78 | $0.13 | **−83%** | **−86%** (232s → 32s) |\n| **Average** | **$0.76** | **$0.22** | **−71%** | **−72%** |\n\n> [!NOTE]\n> **Codemesh MCP** achieves the lowest cost and fastest time of any mode tested — **71% cheaper and 72% faster than baseline** on average across 6 repos, using **82% fewer tool calls** (8 vs 45). Quality is comparable to baseline (7.9 vs 7.0); Codegraph edges Codemesh on quality (8.4) but at roughly double the cost ($0.45 vs $0.22). Every repo shows cost and time savings — including the comprehension-heavy queries (Excalidraw, pydantic-basemodel) that regressed in prior builds of codemesh.\n\n[^swift]: Swift Compiler's codemesh index failed to complete (indexer regression on 30k+ file codebases — see [known issues](docs/benchmark-results.md)). The codemesh numbers above reflect agent behavior with an empty retrieval graph, falling back to Read + LSP — still ahead of baseline, but unrepresentative of codemesh's capability on a properly-indexed Swift repo.\n[^alamo]: Baseline for Alamofire hit a judge error (score recorded as 0 but not meaningful); excluded from the Baseline average.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @pyalwin/codemesh\n```\n\nOr run directly without installing:\n\n```bash\nnpx -y @pyalwin/codemesh --help\n```\n\n\nBuild from source
\n\n```bash\ngit clone https://github.com/pyalwin/codemesh.git\ncd codemesh\nnpm install && npm run build\nnpm link\n```\n\n \n\n> Verify the install: `codemesh --version` should print the package version.\n\n### 2. Index your project\n\n```bash\ncd /your/project\ncodemesh index --with-embeddings\n```\n\n```\nIndexed 656 files\n Symbols found: 16733\n Edges created: 33266\n Duration: 10009ms\n PageRank: 13843 nodes scored\n Embeddings: 13187 symbols embedded\n```\n\n### 3. Choose your mode\n\nCodemesh offers two ways to integrate with AI agents:\n\n\nOption A: MCP Server (structured tool calls)
\n\nAdd to your Claude Code MCP config (`~/.claude/mcp-servers.json` or project `.mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"codemesh\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pyalwin/codemesh\"],\n \"env\": {\n \"CODEMESH_PROJECT_ROOT\": \"/path/to/your/project\"\n }\n }\n }\n}\n```\n\nThe agent gets native MCP tools:\n\n- `codemesh_answer` — one-call question answering (PRIMARY)\n- `codemesh_explore` — search, context (multi-target), impact\n- `codemesh_trace` — follow call chains\n- `codemesh_enrich` / `codemesh_workflow` — write back\n- `codemesh_status` — health check\n\n**Best for:** Opus, structured workflows, enrichment/write-back\n\n \n\n\nOption B: CLI Mode (via Bash — zero MCP overhead)
\n\nNo MCP config needed. The agent calls codemesh directly via Bash:\n\n```bash\nexport CODEMESH_PROJECT_ROOT=/path/to/your/project\n\n# Primary — one-call question answering:\ncodemesh explore answer \"How does request handling work?\"\n\n# Follow-up commands:\ncodemesh explore search \"request flow\"\ncodemesh explore context Source/Core/Session.swift Source/Core/Request.swift\ncodemesh explore trace Session.request --depth 5\ncodemesh explore semantic \"network request handling\" # requires --with-embeddings\n```\n\nAll commands return JSON to stdout. No MCP server process, no protocol overhead.\n\n**Best for:** Sonnet/Haiku, speed-sensitive workflows, simpler setup\n\n \n\n### Which mode should I use?\n\n| | MCP Server | CLI Mode |\n|---|---|---|\n| **Setup** | MCP config file | Just `export CODEMESH_PROJECT_ROOT` |\n| **Overhead** | MCP protocol per call | Zero — direct subprocess |\n| **Enrichment** | Native `codemesh_enrich` tool | Via `Bash(\"codemesh enrich ...\")` |\n| **Best model** | Opus (follows MCP well) | **Sonnet** (55% cheaper, 61% faster than baseline) |\n| **Recommended** | Complex codebases | **Default choice** |\n\n### 4. Use it\n\nThe agent now has 6 new tools. Query the graph before reading code:\n\n```\nYou: \"Find how pydantic handles validation\"\n\nAgent calls: codemesh_answer({ question: \"How does pydantic handle validation?\" })\n gets: 9 relevant files ranked by PageRank, call chains, \n git hotspots, co-change relationships, 5 suggested reads\n\nAgent calls: Read(\"pydantic/functional_validators.py\", lines 1-50)\n reads: only the specific lines suggested by the answer tool\n\nAgent calls: codemesh_enrich({ path: \"pydantic/functional_validators.py\",\n summary: \"Primary V2 validator API...\" })\n saves: summary for next session\n```\n\n---\n\n## Client Integrations\n\nCodemesh speaks the Model Context Protocol, so any MCP-compatible client can use it. Paste one of the snippets below, restart the client, and the six `codemesh_*` tools show up in the agent's toolbox.\n\n\nClaude Code (CLI)
\n\nAdd to `~/.claude/mcp-servers.json` (user-wide) or `.mcp.json` (project-local):\n\n```json\n{\n \"mcpServers\": {\n \"codemesh\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pyalwin/codemesh\"],\n \"env\": {\n \"CODEMESH_PROJECT_ROOT\": \"/absolute/path/to/your/project\"\n }\n }\n }\n}\n```\n\n \n\n\nClaude Desktop (macOS / Windows app)
\n\nEdit `claude_desktop_config.json`:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"codemesh\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pyalwin/codemesh\"],\n \"env\": {\n \"CODEMESH_PROJECT_ROOT\": \"/absolute/path/to/your/project\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. Codemesh's tools will appear in the tool picker (hammer icon).\n \n\n\nCursor — stop the agent from wandering your codebase
\n\nCursor reads `.cursor/mcp.json` per project (or `~/.cursor/mcp.json` for all projects):\n\n```json\n{\n \"mcpServers\": {\n \"codemesh\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pyalwin/codemesh\"],\n \"env\": {\n \"CODEMESH_PROJECT_ROOT\": \"${workspaceFolder}\"\n }\n }\n }\n}\n```\n\nOpen **Settings → MCP**, confirm `codemesh` is green, then mention it in a prompt (`@codemesh how does auth work?`) to nudge the agent toward graph queries instead of recursive Grep.\n \n\n\nWindsurf / VS Code (Continue)
\n\nAdd to `~/.continue/config.json` under `experimental.modelContextProtocolServers`:\n\n```json\n{\n \"experimental\": {\n \"modelContextProtocolServers\": [\n {\n \"transport\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pyalwin/codemesh\"],\n \"env\": {\n \"CODEMESH_PROJECT_ROOT\": \"/absolute/path/to/your/project\"\n }\n }\n }\n ]\n }\n}\n```\n \n\n---\n\n## Agent Write-Back: the graph that gets smarter\n\nEvery other code-intelligence tool indexes your repo once and hands the agent a read-only view. Codemesh lets the agent **teach the graph** as it works — summaries, workflows, and cross-concept links persist across sessions and survive re-indexing.\n\n```ts\n// Session 1 — agent reads unfamiliar code, then writes back what it learned.\ncodemesh_enrich({\n path: \"pydantic/functional_validators.py\",\n summary: \"Primary V2 validator API. `@field_validator` wraps \"\n + \"`_decorators.FieldValidatorDecoratorInfo`; `mode='before'|'after'` \"\n + \"toggles pre/post-coercion execution. Extends BaseValidator.\",\n concepts: [\"validation\", \"decorators\", \"v2-api\"]\n})\n\n// Session 1 — agent traces a multi-file flow, records the path.\ncodemesh_workflow({\n name: \"pydantic field validation\",\n description: \"Request → BaseModel.__init__ → SchemaValidator → field_validator\",\n files: [\n \"pydantic/main.py\",\n \"pydantic/_internal/_model_construction.py\",\n \"pydantic/functional_validators.py\"\n ]\n})\n\n// Session 2 (days later) — same question, different agent instance.\ncodemesh_answer({ question: \"How does pydantic validate fields?\" })\n// → returns the enriched summary AND the 3-file workflow from Session 1\n// before the agent reads a single line. Zero rediscovery cost.\n```\n\nThe graph now knows things no static analyzer could infer: why a file matters, which files move together, what a maintainer called a concept. Re-indexing rebuilds the structural layer (files, symbols, imports, calls) but **preserves every enrichment** — entries only go stale when their referenced files change.\n\nSee `codemesh_enrich` and `codemesh_workflow` under [MCP Tools](#mcp-tools).\n\n---\n\n## How It Works\n\n```\n ┌──────────────────────────────────┐\n │ Knowledge Graph │\n │ │\n │ ┌──────────┐ ┌───────────────┐ │\n │ │Structural│ │ Semantic │ │\n │ │ (auto) │ │ (agents) │ │\n │ │ │ │ │ │\n │ │ files │ │ summaries │ │\n │ │ symbols │ │ workflows │ │\n │ │ imports │ │ concepts │ │\n │ │ calls │ │ enrichments │ │\n │ └──────────┘ └───────────────┘ │\n │ │\n │ ┌──────────┐ ┌───────────────┐ │\n │ │ Git │ │ Search │ │\n │ │ Intel │ │ │ │\n │ │ │ │ FTS5 (exact) │ │\n │ │ hotspots │ │ Trigram (fuzzy)│ │\n │ │ co-change│ │ LanceDB (sem) │ │\n │ │ churn │ │ PageRank │ │\n │ └──────────┘ └───────────────┘ │\n │ │\n │ SQLite + LanceDB │\n └────────────┬──────────────────────┘\n │\n ┌────────────┴──────────────────────┐\n │ MCP Server / CLI (7 tools) │\n │ │\n │ answer · explore · trace │\n │ enrich · workflow · status │\n └────────────────────────────────────┘\n```\n\n**Structural layer** (automatic) — Tree-sitter parses your code into files, symbols (functions, classes, methods), and relationships (imports, calls, extends). Rebuilt on each index.\n\n**Semantic layer** (agent-built) — As agents work with your code, they write back summaries and workflow paths. These survive re-indexing and accumulate across sessions. Invalidated when referenced files change.\n\n---\n\n## MCP Tools\n\n| Tool | Purpose | Example |\n|---|---|---|\n| `codemesh_answer` | **One-call context assembly** — returns all relevant files, call chains, hotspots, suggested reads | `codemesh_answer({ question: \"How does auth work?\" })` |\n| `codemesh_explore` | Search, context (multi-target), impact analysis | `codemesh_explore({ action: \"search\", query: \"auth\" })` |\n| `codemesh_trace` | Follow call chains with source code | `codemesh_trace({ symbol: \"login\", depth: 5 })` |\n| `codemesh_enrich` | Write back what you learned for future sessions | `codemesh_enrich({ path: \"src/auth.py\", summary: \"...\" })` |\n| `codemesh_workflow` | Record multi-file workflow paths | `codemesh_workflow({ name: \"login flow\", files: [...] })` |\n| `codemesh_status` | Graph health check | `codemesh_status()` |\n\n---\n\n## CLI\n\n```bash\ncodemesh index # structural + git intel + pagerank\ncodemesh index --with-embeddings # + semantic vectors (~80MB model, zero API cost)\ncodemesh status # graph statistics\ncodemesh rebuild # purge and re-index\n\ncodemesh explore answer \"question\" # one-call context assembly (PRIMARY)\ncodemesh explore search \"query\" # FTS5 + trigram + semantic search\ncodemesh explore context file1 file2 # multi-target context\ncodemesh explore trace symbol --depth 5 # follow call chains\ncodemesh explore semantic \"query\" # vector similarity (needs embeddings)\ncodemesh explore impact file # reverse dependencies\n```\n\n---\n\n## Optional: Hooks & Skills\n\n\nSkill — teaches agents the graph-first workflow
\n\nCopy `skills/codemesh.md` to `~/.claude/skills/` or your project's `.claude/skills/`.\n\n```bash\n# Install the skill so Claude Code loads the workflow automatically\ncp /path/to/codemesh/skills/codemesh.md /your/project/.claude/skills/\n```\n\nThe skill instructs agents to query the graph before using Grep/Read, and to write back via `codemesh_enrich` after reading code.\n \n\n\nHooks — automatic pre-read context injection
\n\nAdd to `.claude/settings.json`:\n\n```json\n{\n \"hooks\": {\n \"pre_tool_use\": [{\n \"matcher\": \"Read\",\n \"command\": \"/path/to/codemesh/hooks/pre-read.sh\"\n }],\n \"post_tool_use\": [{\n \"matcher\": \"Read\",\n \"command\": \"/path/to/codemesh/hooks/post-read.sh\"\n }]\n }\n}\n```\n\n- **Pre-read** — Injects cached summaries before file reads\n- **Post-read** — Nudges the agent to enrich after reading unfamiliar files\n \n\n---\n\n## Supported Languages\n\n\n\n| TypeScript | JavaScript | Python | Go | Rust | Java | C# | \n
\n\n| Ruby | PHP | C | C++ | Swift | Kotlin | Dart | \n
\n
\n\nAny language with a [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar can be added.\n\n---\n\n## Graph Data Model\n\n### Nodes\n\n| Type | Source | Key Fields |\n|:--|:--|:--|\n| `file` | Static (tree-sitter) | `path`, `hash`, `last_indexed_at` |\n| `symbol` | Static (tree-sitter) | `name`, `kind`, `file_path`, `line_start`, `line_end`, `signature` |\n| `concept` | Agent-written | `summary`, `last_updated_by`, `stale` |\n| `workflow` | Agent-written | `description`, `file_sequence`, `last_walked_at` |\n\n### Edges\n\n| Type | Direction | Source |\n|:--|:--|:--|\n| `contains` | file → symbol | Static |\n| `imports` | file → file | Static |\n| `calls` | symbol → symbol | Static |\n| `extends` | symbol → symbol | Static |\n| `describes` | concept → file/symbol | Agent |\n| `related_to` | concept → concept | Agent |\n| `traverses` | workflow → file | Agent |\n\n---\n\n## Architecture\n\n```\ncodemesh/\n├── src/\n│ ├── index.ts # MCP server entry (stdio transport)\n│ ├── server.ts # Tool registration (zod schemas)\n│ ├── graph/\n│ │ ├── types.ts # Node/edge type definitions\n│ │ ├── storage.ts # StorageBackend interface (swappable)\n│ │ └── sqlite.ts # SQLite + FTS5 implementation\n│ ├── indexer/\n│ │ ├── indexer.ts # File walking, hashing, incremental indexing\n│ │ ├── parser.ts # Tree-sitter AST extraction\n│ │ └── languages.ts # Language registry (ext → grammar)\n│ ├── tools/ # 6 MCP tool handlers\n│ └── cli.ts # CLI entry point\n├── skills/codemesh.md # Agent education skill\n├── hooks/ # Pre/post read hooks\n└── eval/ # Eval framework (5 tasks, 3 models)\n```\n\nStorage is **backend-agnostic**. The `StorageBackend` interface abstracts all persistence. v1 uses SQLite with FTS5 for zero-dependency local operation. The interface supports swapping to Memgraph, Neo4j, or other graph databases.\n\n---\n\n## Eval Framework\n\nReproducible evaluation harness with LLM-as-judge scoring:\n\n```bash\n# Setup\nnpm install -g @pyalwin/codemesh\ngit clone --depth 1 https://github.com/Alamofire/Alamofire.git /tmp/alamofire\n# ... clone other repos ...\n\n# Index\nCODEMESH_PROJECT_ROOT=/tmp/alamofire codemesh index\n\n# Run benchmarks\npython3 eval/head_to_head.py --model sonnet alamofire excalidraw vscode swift-compiler\n```\n\nSee [`docs/benchmark-results.md`](docs/benchmark-results.md) for full methodology and results. Early pydantic evals are archived in [`docs/experiments/`](docs/experiments/).\n\n---\n\n## vs. Existing Tools\n\n| Feature | [CodeGraph](https://github.com/colbymchenry/codegraph) | [Graphify](https://github.com/safishamsi/graphify) | [Axon](https://github.com/harshkedia177/axon) | **Codemesh** |\n|:--|:--:|:--:|:--:|:--:|\n| Structural indexing | Yes | Yes | Yes | Yes |\n| FTS search | Yes | — | Yes | Yes |\n| Agent write-back | — | — | — | **Yes** |\n| Workflow memory | — | — | — | **Yes** |\n| Hook interception | — | — | — | **Yes** |\n| Backend-swappable | — | — | — | **Yes** |\n| Eval framework | — | — | — | **Yes** |\n| Published benchmarks | — | — | — | **Yes** |\n\n---\n\n## Development\n\n```bash\nbun install # Install dependencies\nbun run build # Compile TypeScript\nbun run test # Run 102 tests\nbun run dev # Watch mode\nbun run lint # Type check\n```\n\n---\n\n## Contributing\n\nContributions welcome. Areas for improvement:\n\n- **More languages** — Add tree-sitter grammars and language-specific extractors\n- **AST-diff invalidation** — Function-level instead of file-level staleness detection\n- **Graph backends** — Memgraph/Neo4j adapters for `StorageBackend`\n- **Semantic search** — Embedding columns alongside FTS5\n- **Agent adoption** — Better patterns for agents to prefer graph tools naturally\n\n---\n\n## License\n\nMIT\n",
"bytes": 21907,
"sha": "09e2c5920e5c7f717bd6bf224f790e1c621a2dc37480464075e4de0d1ca6115f",
"repo_slug": "pyalwin/codemesh",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_pyalwin_codemesh_715707c7/readme"
}