kiliman/codemesh

📺 See It In Action

Watch: How Agent A explores and documents, then Agent B one-shots the same task - 2.6x faster!

📖 Read the story: Building CodeMesh - From Idea to Self-Improving Intelligence

What is CodeMesh?

CodeMesh lets AI agents write TypeScript code to orchestrate ANY MCP server. One prompt. One code block. Multiple servers working together.

Instead of exposing dozens of individual tools, CodeMesh provides just 3 tools:

1. discover-tools - See what's available (context-efficient overview)
2. get-tool-apis - Get TypeScript APIs for specific tools
3. execute-code - Execute TypeScript that calls multiple tools

🎉 The Innovation: Auto-Augmentation

When agents encounter unclear tool outputs, CodeMesh forces documentation before proceeding. This creates compound intelligence - each exploration helps ALL future agents.

Proven: Agent A explored and documented. Agent B one-shot the same task. 2.6x faster! 🚀

Installation

1. Add CodeMesh to Claude Desktop

claude mcp add codemesh npx -y codemesh

Or manually add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "codemesh"]
    }
  }
}

2. Create Configuration

Create a .codemesh/config.json file in your project directory to configure which MCP servers CodeMesh should connect to:

{
  "logging": {
    "enabled": true,
    "level": "info",
    "logDir": ".codemesh/logs"
  },
  "servers": [
    {
      "id": "filesystem",
      "name": "File System",
      "type": "stdio",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "timeout": 30000
    },
    {
      "id": "brave-search",
      "name": "Brave Search",
      "type": "stdio",
      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    {
      "id": "weather",
      "name": "Weather Server",
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  ]
}

Server Configuration Options

Each server entry supports:

• id (required) - Unique identifier for the server
• name (required) - Human-readable name
• type (required) - Server type: "stdio", "http", or "websocket"
• command (stdio only) - Command array to start the server
• cwd (stdio only) - Working directory for the command
• url (http/websocket only) - Server URL
• env (optional) - Environment variables for the server
• timeout (optional) - Connection timeout in milliseconds

Environment Variable Substitution

Use ${VAR} or ${VAR:-default} syntax in your config for secure credential management:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "ENDPOINT": "${API_ENDPOINT:-https://default.api.com}"
  }
}

This works with any environment variable manager (Doppler, 1Password, etc.) and keeps your config safe to commit.

Logging Configuration

Enable markdown-based file logging to track tool calls, code execution, and responses:

{
  "logging": {
    "enabled": true,
    "level": "info",
    "logDir": ".codemesh/logs"
  }
}

Options:

• enabled (boolean) - Enable/disable file logging
• level ("debug" | "info" | "warn" | "error") - Minimum log level to record
• logDir (string) - Directory for log files (defaults to .codemesh/logs)

Log Format:

Logs are saved as markdown files (.codemesh/logs/YYYY-MM-DD.md) with syntax highlighting:

## 14:52:45 - execute-code

**Duration:** 2.1s
**Status:** ✅ Success

### Request

` ``typescript
const alerts = await weatherServer.getAlerts({ state: 'CA' })
return alerts ` ``

### Console Output

` ``
Found 3 alerts ` ``

### Response

` ``json
{ "count": 3, "alerts": [...] } ` ``

Perfect for debugging, demo preparation, and understanding what CodeMesh is doing! 🎯

How It Works

CodeMesh uses an intelligent three-step workflow that happens automatically when you give it a prompt:

Example: Real-World Usage

You ask Claude:

"Use CodeMesh to give me the top 3 weather alerts for Moyock, NC"

Behind the scenes, CodeMesh automatically:

1. Discovers Tools (discover-tools)

   • Sees geocode tool (to convert "Moyock, NC" to coordinates)
   • Sees getAlerts tool from weather server
   • Context-efficient: only shows tool names and descriptions

2. Loads APIs (get-tool-apis)

   • Requests TypeScript function signatures for geocode and getAlerts
   • Generates type-safe APIs: geocodeServer.geocode({ location }) and weatherServer.getAlerts({ state })
   • Includes any existing augmentation documentation from previous runs

3. Writes & Executes Code (execute-code)

   • CodeMesh writes TypeScript code that:
     • Calls geocodeServer.geocode to get coordinates
     • Calls weatherServer.getAlerts with the state
     • Parses results and filters to top 3 by severity
   • Executes in secure VM2 sandbox (30s timeout)
   • Returns formatted results

Self-Improving Intelligence (Auto-Augmentation)

The Problem: Most MCP servers don't document their output formats. Is it JSON? Plain text? Key-value pairs? Arrays?

CodeMesh's Solution: When the agent struggles to parse output, it automatically:

1. Enters EXPLORATION Mode

   • Adds // EXPLORING comment to the code
   • Calls the tool to examine actual output structure
   • Figures out: Is it JSON? What fields exist? What's the structure?

2. Gets Blocked by Design

   • CodeMesh returns an ERROR (not success) for exploration mode
   • Forces the agent to document before proceeding
   • "You cannot parse until you create augmentation!"

3. Creates Augmentation (add-augmentation)

   • Agent writes markdown documentation with:
     • Output format description
     • Field definitions
     • Example output (actual data from exploration)
     • Working parsing code (TypeScript examples)
   • Saves to .codemesh/[server-id].md

4. Enhanced for Next Time

   • Next get-tool-apis call includes augmentation in JSDoc
   • Future agents see the parsing examples and data structure
   • One-shot success - no trial-and-error needed!

Result: Agent A struggles and documents. Agent B one-shots it. Agent C one-shots it. Compound intelligence!

Example: What CodeMesh Writes For You

Your prompt:

"Find the 3 most severe weather alerts in North Carolina"

CodeMesh automatically writes:

// Step 1: Fetch weather alerts
const alerts = await weatherServer.getAlerts({ state: 'NC' })
const alertsData = JSON.parse(alerts.content[0].text)

// Step 2: Define severity hierarchy
const severityHierarchy = ['Extreme', 'Severe', 'Moderate', 'Minor']
const highestSeverity = severityHierarchy.find((severity) =>
  alertsData.features.some((alert) => alert.properties.severity === severity),
)

// Step 3: Filter and return top 3
const topAlerts = alertsData.features.filter((alert) => alert.properties.severity === highestSeverity).slice(0, 3)

return {
  count: topAlerts.length,
  severity: highestSeverity,
  alerts: topAlerts,
}

You get intelligent results - no manual tool calls, no trial-and-error, just results!

Why CodeMesh?

❌ The Problem

• Traditional MCP: Expose 50+ tools, flood agent context
• Agents can't coordinate tools from different servers
• Trial-and-error on unclear tool outputs wastes tokens
• Every agent repeats the same mistakes

✨ The CodeMesh Way

• Just 3 tools: discover, get APIs, execute code
• Agents write TypeScript calling multiple servers at once
• Auto-augmentation forces documentation of outputs
• Knowledge compounds: Agent A helps Agent B

🏆 Key Features

• 🧠 Self-Improving - Agents document unclear outputs, future agents benefit
• 🔗 Multi-Server Orchestration - Coordinate tools from different MCP servers in single code block (HTTP + stdio + websocket)
• 🎯 Context Efficient - Load only the tools you need, 3 tools vs 50+
• 🚀 Zero Configuration - Point to your MCP servers and go, works with ANY compliant MCP server
• ⚡ Production Ready - Type-safe TypeScript execution in VM2 sandbox, authentication, error handling
• 🔒 Secure by Default - Environment variable substitution, principle of least privilege

Best Practices

Use Subagents for Maximum Context Efficiency

While CodeMesh is context-efficient internally (tiered discovery prevents tool pollution), we strongly recommend spawning a subagent to execute CodeMesh operations. This keeps your main agent's context clean while CodeMesh does the heavy lifting.

Example with Claude Code:

User: "Analyze the weather data and file structure for my project"
Main Agent: Let me spawn a subagent to handle this task...

Main agent uses the Task tool to spawn a codemesh subagent with the prompt: "Use CodeMesh to analyze weather alerts for NC and correlate with local file timestamps"

Benefits:

• 🧹 Main context stays clean
• ⚡ Subagent can iterate on CodeMesh without polluting parent
• 🎯 Specialized subagent focused solely on orchestration
• 📦 Results summarized back to main agent when complete

When NOT to use subagents:

• Simple single-tool calls (just use the tool directly)
• When you need tight integration with main conversation flow

See for a ready-to-use Claude Code agent configuration.

Contributing

Want to contribute to CodeMesh development? See for developer setup, architecture details, and development workflows.