Codemesh

What is Codemesh?

Codemesh is an MCP server that gives AI coding agents a persistent, queryable knowledge graph. It indexes codebases into a graph of symbols, edges, and embeddings, enabling agents to explore, trace, and ask questions without wasting tokens on discovery. It is for developers using AI coding agents on real-world codebases.

How to use Codemesh?

Install the npm package globally (npm install -g @pyalwin/codemesh), then index your project (codemesh index --with-embeddings). Configure your MCP client (e.g., Claude Code, Claude Desktop, Cursor) with the codemesh MCP server pointing to your project root. The agent gets six codemesh_* tools: codemesh_answer, codemesh_explore, codemesh_trace, codemesh_enrich, codemesh_workflow, codemesh_status. Alternatively, use CLI mode by exporting CODEMESH_PROJECT_ROOT and calling codemesh explore ... directly via Bash.

Key features of Codemesh

• Persistent, queryable code knowledge graph
• 71% cheaper and 72% faster than baseline Grep+Read
• 82% fewer tool calls (8 vs 45 on average)
• Agent write-back: enrich graph with summaries and workflows
• MCP and CLI integration modes
• Supports semantic search, impact analysis, call tracing

Use cases of Codemesh

• Reducing token waste when agents explore large codebases
• Quickly answering complex code questions without reading all files
• Tracing call chains across many files in a single tool call
• Persisting agent learning across sessions via write-back enrichment

FAQ from Codemesh

How do I install Codemesh?

Run npm install -g @pyalwin/codemesh or run directly with npx -y @pyalwin/codemesh.

What is the difference between MCP Server and CLI mode?

MCP Server works via structured tool calls and is best for Opus and complex workflows. CLI mode has zero MCP overhead, calls codemesh directly via Bash, and is recommended for Sonnet/Haiku and speed-sensitive workflows.

Does Codemesh require any special runtime or dependencies?

It requires Node.js and npm. It has no other external dependencies. The codebase must be a local project directory.

How does the agent write-back work?

The agent can call codemesh_enrich and codemesh_workflow tools to persist summaries, concepts, and multi-file flows into the graph. These enrichments survive re-indexing and are available across sessions.

What is the recommended way to run the index?

Run codemesh index --with-embeddings from the project root. This creates symbols, edges, and embeddings for all files. The index step takes seconds to minutes depending on codebase size.