Codemesh

Codemesh

Intelligent code knowledge graph for AI coding agents

71% cheaper, 72% faster, 82% fewer tool calls vs baseline Grep+Read\ on 6 real-world repos (Sonnet 4.6) — from a single codemesh index.

Benchmarks · Quick Start · Integrations · Write-Back · How It Works · API Reference · Full Results

---

The Problem

AI 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.

On a 600-file codebase, a typical exploration task involves 10+ file reads before the agent even knows what's relevant.

Before:  Agent → Grep → 50 matches → Read 10 files → Understand → Work

After: Agent → codemesh_map → expand chosen branches → read exact symbols → Work

Codemesh 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.

---

Benchmarks

Benchmarked 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.

Full methodology, per-repo breakdowns, and pairwise comparisons: docs/benchmark-results.md | Early pydantic evals

These historical runs used the earlier answer-first workflow. The map-first navigation workflow described below is evaluated in an exploratory Pydantic pilot; the figures in this section should not be read as its measured performance.

Cost

Time

Tool calls (agent turns)

Quality (1–10, LLM-as-judge)

Cost savings: Codemesh MCP vs Baseline

[!NOTE]

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.

---

Quick Start

1. Install

npm install -g @pyalwin/codemesh

Or run directly without installing:

npx -y @pyalwin/codemesh --help

Build from source

git clone https://github.com/pyalwin/codemesh.git

cd codemesh npm install && npm run build npm link

Verify the install: codemesh --version should print the package version.

2. Index your project

cd /your/project

codemesh index

The default index and retrieval path uses one SQLite database in .codemesh/. It does not generate embeddings or require a vector database. Existing vector artifacts from older runs are left untouched but are not used by this path.

Indexed 656 files

Symbols found: 16733 Edges created: 33266 Duration: 10009ms PageRank: 13843 nodes scored

3. Choose your mode

Codemesh offers two ways to integrate with AI agents:

Option A: MCP Server (structured tool calls)

Add to your Claude Code MCP config (~/.claude/mcp-servers.json or project .mcp.json):

{

"mcpServers": { "codemesh": { "command": "npx", "args": ["-y", "@pyalwin/codemesh"], "env": { "CODEMESH_PROJECT_ROOT": "/path/to/your/project" } } } }

The agent gets native MCP tools:

• codemesh_map — browse one level of the indexed repository or follow a link
• codemesh_source — read a revision-checked source view by symbol ID; ifHash avoids repeat delivery
• codemesh_inspect — inspect an exact symbol and its direct calls with bounded, exact source blocks
• codemesh_hydrate — verify saved symbol references and reopen exact source after a handoff
• codemesh_answer — optional ranked context assembly
• codemesh_explore — search, context (multi-target), impact
• codemesh_trace — follow call chains
• codemesh_enrich / codemesh_workflow — write back
• codemesh_recall — retrieve notes and workflows with freshness status
• codemesh_status — health check

Best for: Opus, structured workflows, enrichment/write-back

Option B: CLI Mode (via Bash — zero MCP overhead)

No MCP config needed. The agent calls codemesh directly via Bash:

export CODEMESH_PROJECT_ROOT=/path/to/your/project

Navigate one level at a time, then read a selected symbol:

codemesh explore map codemesh explore map --node 'dir:src' codemesh explore map --node 'file:src/server.ts' codemesh explore source 'symbol:src/server.ts:createServer' codemesh explore source 'symbol:src/server.ts:createServer' --mode preview codemesh explore inspect 'symbol:src/server.ts:createServer' --depth 1 --max-symbols 4 --compact codemesh explore hydrate --references '[{"id":"symbol:src/server.ts:createServer","bodyHash":"HASH"}]' --compact

Other exploration commands:

codemesh explore search "request flow" codemesh explore context Source/Core/Session.swift Source/Core/Request.swift codemesh explore trace Session.request --depth 5 codemesh explore recall --path src/server.ts codemesh remember --path src/server.ts --summary "Server tool registration" --session my-task

Exploration and write commands return JSON to stdout. No MCP server process is required.

Best for: Sonnet/Haiku, speed-sensitive workflows, simpler setup

Which mode should I use?

4. Use it

The agent can choose a path through the persistent graph before reading code:

You: "Find how pydantic handles validation"

Agent calls: codemesh_map({}) gets: immediate repository directories and files, each with an ID

Agent calls: codemesh_map({ node: "dir:pydantic" }) gets: immediate files and subdirectories

Agent calls: codemesh_map({ node: "file:pydantic/main.py" }) gets: top-level symbols, including BaseModel

Agent calls: codemesh_map({ node: "symbol:pydantic/main.py:BaseModel" }) gets: methods, including model_validate

Agent calls: codemesh_source({ id: "symbol:pydantic/main.py:BaseModel.model_validate" }) reads: only the selected symbol's source

Agent calls: codemesh_enrich({ path: "pydantic/functional_validators.py", summary: "Primary V2 validator API..." }) saves: summary for next session

---

Client Integrations

Codemesh speaks the Model Context Protocol, so any MCP-compatible client can use it. Paste one of the snippets below, restart the client, and the codemesh_* tools show up in the agent's toolbox.

Claude Code (CLI)

Add to ~/.claude/mcp-servers.json (user-wide) or .mcp.json (project-local):

{

"mcpServers": { "codemesh": { "command": "npx", "args": ["-y", "@pyalwin/codemesh"], "env": { "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project" } } } }

Claude Desktop (macOS / Windows app)

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": { "codemesh": { "command": "npx", "args": ["-y", "@pyalwin/codemesh"], "env": { "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project" } } } }

Restart Claude Desktop. Codemesh's tools will appear in the tool picker (hammer icon).

Cursor — stop the agent from wandering your codebase

Cursor reads .cursor/mcp.json per project (or ~/.cursor/mcp.json for all projects):

{

"mcpServers": { "codemesh": { "command": "npx", "args": ["-y", "@pyalwin/codemesh"], "env": { "CODEMESH_PROJECT_ROOT": "${workspaceFolder}" } } } }

Open Settings → MCP