<div align="center"> <!-- <img alt="utcp code mode banner" src="https://github.com/user-attachments/assets/77723130-ecbc-4d1d-9e9b-20f978882699" width="80%" style="margin: 20px auto;"> --> <h1 align="center">🤖 Code-Mode Library: First library for tool calls via code execution</h1> <p align="center"> <a href="https://github.com/universal-tool-calling-protocol"> <img src="https://img.shields.io/github/followers/universal-tool-calling-protocol?label=Follow%20Org&logo=github" /></a> <a href="https://img.shields.io/npm/dt/@utcp/code-mode" title="PyPI Version"> <img src="https://img.shields.io/npm/dt/@utcp/code-mode"/></a> <a href="https://github.com/universal-tool-calling-protocol/code-mode/blob/main/LICENSE" alt="License"> <img src="https://img.shields.io/github/license/universal-tool-calling-protocol/code-mode" /></a>

</p> </div>

Transform your AI agents from clunky tool callers into efficient code executors — in just 3 lines.

Why This Changes Everything

LLMs excel at writing code but struggle with tool calls. Instead of exposing hundreds of tools directly, give them ONE tool that executes TypeScript code with access to your entire toolkit.

Apple, Cloudflare, and Anthropic say that Code-Mode is a more efficient way to approach tool calling compared to the traditional dump function information and then extract a JSON for function calling.

Benchmarks

Independent Python benchmark study validates the performance claims with $9,536/year cost savings at 1,000 scenarios/day:

| Scenario Complexity | Traditional | Code Mode | Improvement | |---------------------|-------------|-----------|----------------| | Simple (2-3 tools) | 3 iterations | 1 execution | 67% faster | | Medium (4-7 tools) | 8 iterations | 1 execution | 75% faster | | Complex (8+ tools) | 16 iterations | 1 execution | 88% faster |

Why Code Mode Dominates:

Batching Advantage - Single code block replaces multiple API calls
Cognitive Efficiency - LLMs excel at code generation vs. tool orchestration
Computational Efficiency - No context re-processing between operations

Getting Started

<img width="2606" height="1445" alt="Frame 4 (4)" src="https://github.com/user-attachments/assets/58ba26ab-6e77-459b-a59a-eeb60d711746" />

Get Started in 3 Lines

import { CodeModeUtcpClient } from '@utcp/code-mode';

const client = await CodeModeUtcpClient.create();                    // 1. Initialize
await client.registerManual({ name: 'github', /* MCP config */ });  // 2. Add tools  
const { result } = await client.callToolChain(`/* TypeScript */`);   // 3. Execute code

That's it. Your AI agent can now execute complex workflows in a single request instead of dozens.

What You Get

Progressive Tool Discovery

// Agent discovers tools dynamically, loads only what it needs
const tools = await client.searchTools('github pull request');
// Instead of 500 tool definitions → 3 relevant tools

Natural Code Execution

const { result, logs } = await client.callToolChain(`
  // Chain multiple operations in one request
  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const reviews = await github.get_pull_request_reviews({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  
  // Process data efficiently in-sandbox
  return {
    title: pr.title,
    commentCount: comments.length,
    approvals: reviews.filter(r => r.state === 'APPROVED').length
  };
`);
// Single API call replaces 15+ traditional tool calls

Auto-Generated TypeScript Interfaces

namespace github {
  interface get_pull_requestInput {
    /** Repository owner */
    owner: string;
    /** Repository name */ 
    repo: string;
    /** Pull request number */
    pull_number: number;
  }
}

Enterprise-Ready

• Secure VM Sandboxing – Node.js isolates prevent unauthorized access
• Timeout Protection – Configurable execution limits prevent runaway code
• Complete Observability – Full console output capture and error handling
• Zero External Dependencies – Tools only accessible through registered UTCP/MCP servers
• Runtime Introspection – Dynamic interface discovery for adaptive workflows

If you're working at an enterprise, and need support, book a consultation here.

Universal Protocol Support

Works with any tool ecosystem:

| Protocol | Description | Usage | |----------|-------------|-------| | MCP | Model Context Protocol servers | call_template_type: 'mcp' | | HTTP | REST APIs with auto-discovery | call_template_type: 'http' |
| File | Local JSON/YAML configurations | call_template_type: 'file' | | CLI | Command-line tool execution | call_template_type: 'cli' |

Installation

npm install @utcp/code-mode

Recommended for shell agents: the utcp CLI

If your agent can run shell commands (Claude Code, Cursor, Codex, Claude Cowork, etc.), the utcp CLI is the preferred way to use Code Mode — no MCP server, no client config, no env vars. The agent self-configures by writing a .utcp_config.json and drives everything from the shell.

Just point the agent at the built-in guide:

npx -y @utcp/code-mode-cli prompt

Hand it a description of the API to use — a UTCP call template, an OpenAPI spec, or a plain-English description — and it writes the config, discovers tools, runs tool-chains, and even completes interactive OAuth logins (e.g. Notion), all from the shell:

npx -y @utcp/code-mode-cli search "<task>"           # discover tools + TS interfaces
npx -y @utcp/code-mode-cli run <<'EOF'               # run a tool-chain
const r = await openlibrary.read_search_json_search_json_get({ q: "tolkien", limit: 3 });
return r.docs.map(b => b.title);
EOF
npx -y @utcp/code-mode-cli login <manual>            # interactive OAuth, writes token to .env

CLI vs MCP: prefer the CLI whenever the agent has shell access (most coding agents) — it's simpler and self-configuring. Use the MCP server (below) only for MCP-only clients like Claude Desktop. Both wrap the same @utcp/code-mode engine.

See code-mode-cli/ for full docs.

Ready-to-Use MCP Server

On an MCP-only client (e.g. Claude Desktop)? Use our plug-and-play MCP server. (If your agent has a shell, prefer the utcp CLI above.)

{
  "mcpServers": {
    "code-mode": {
      "command": "npx",
      "args": ["@utcp/code-mode-mcp"],
      "env": {
        "UTCP_CONFIG_FILE": "/path/to/your/.utcp_config.json"
      }
    }
  }
}

That's it! No installation, no Node.js knowledge required. The Code Mode MCP Server automatically:

• Downloads and runs the latest version via npx
• Loads your tool configurations from JSON
• Provides code execution capabilities to Claude Desktop
• Gives you call_tool_chain as an MCP tool for TypeScript execution

Perfect for non-developers who want Code Mode power in Claude Desktop!

Direct TypeScript Usage

1. MCP Server Integration

Connect to any Model Context Protocol server:

Each call_template_type is a separate plugin package. Install and import the package once at startup so it can register itself with the client; the plugin registers as a side effect of being imported. For mcp, that's @utcp/mcp. The same pattern applies to other transports: @utcp/http, @utcp/text, etc.

npm install @utcp/mcp

import '@utcp/mcp';                      // registers the 'mcp' call template
import { CodeModeUtcpClient } from '@utcp/code-mode';

const client = await CodeModeUtcpClient.create();

// Connect to GitHub MCP server
await client.registerManual({
  name: 'github',
  call_template_type: 'mcp',
  config: {
    mcpServers: {
      github: {
        transport: 'stdio',              // required by @utcp/mcp
        command: 'docker',
        args: ['run', '-i', '--rm', '-e', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'mcp/github'],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN }
      }
    }
  }
});

2. Execute Multi-Step Workflows

Replace 15+ tool calls with a single code execution:

const { result, logs } = await client.callToolChain(`
  // Traditional: 4 separate API round trips → Code Mode: 1 execution
  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const reviews = await github.get_pull_request_reviews({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const files = await github.get_pull_request_files({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  
  // Process data in-sandbox (no token overhead)
  const summary = {
    title: pr.title,
    state: pr.state,
    author: pr.user.login,
    stats: {
      comments: comments.length,
      reviews: reviews.length, 
      filesChanged: files.length,
      approvals: reviews.filter(r => r.state === 'APPROVED').length
    },
    topDiscussion: comments.slice(0, 3).map(c => ({
      author: c.user.login,
      preview: c.body.substring(0, 100) + '...'
    }))
  };
  
  console.log(\`PR "\${pr.title}" analysis complete\`);
  return summary;
`);

console.log('Analysis Result:', result);
// console output: 'PR "Fix memory leak in hooks" analysis complete'

---

Advanced Features

Multi-Protocol Tool Chains

Mix and match different tool ecosystems in a single execution:

// Register multiple tool sources
await client.registerManual({ name: 'github', call_template_type: 'mcp', /* config */ });
await client.registerManual({ name: 'slack', call_template_type: 'http', /* config */ });
await client.registerManual({ name: 'db', call_template_type: 'file', file_path: './db-tools.json' }); // This loads a UTCP manual from a json file

const result = await client.callToolChain(`
  // Fetch PR data from GitHub (MCP)
  const pr = await github.get_pull_request({ owner: 'company', repo: 'api', pull_number: 42 });
  
  // Query deployment status from database (File)
  const deployment = await db.get_deployment_status({ pr_id: pr.id });
  
  // Send notification to Slack (HTTP)
  await slack.post_message({
    channel: '#releases',
    text: \`PR #42 "\${pr.title}" deployed to \${deployment.environment}\`
  });
  
  return { pr: pr.title, environment: deployment.environment };
`);

Runtime Interface Introspection

Tools can dynamically discover and adapt to available interfaces:

const result = await client.callToolChain(`
  // Discover available tools at runtime
  console.log('Available interfaces:', __interfaces);
  
  // Get specific tool interface for validation
  const prInterface = __getToolInterface('github.get_pull_request');
  console.log('PR tool expects:', prInterface);
  
  // Use interface info for dynamic workflows
  const hasSlackTools = __interfaces.includes('namespace slack');
  if (hasSlackTools) {
    await slack.post_message({ channel: '#dev', text: 'Analysis complete' });
  }
  
  return { toolsA