🤖 Code-Mode Library: First library for tool calls via code execution

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

Get Started in 3 Lines

import{CodeModeUtcpClient}from'@utcp/code-mode';constclient=awaitCodeModeUtcpClient.create();// 1. Initializeawaitclient.registerManual({name: 'github',/* MCP config */});// 2. Add tools const{ result }=awaitclient.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 needsconsttools=awaitclient.searchTools('github pull request');// Instead of 500 tool definitions → 3 relevant tools

Natural Code Execution

const{ result, logs }=awaitclient.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

namespacegithub{interfaceget_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-chainconst 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 templateimport{CodeModeUtcpClient}from'@utcp/code-mode';constclient=awaitCodeModeUtcpClient.create();// Connect to GitHub MCP serverawaitclient.registerManual({name: 'github',call_template_type: 'mcp',config: {mcpServers: {github: {transport: 'stdio',// required by @utcp/mcpcommand: '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 }=awaitclient.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 sourcesawaitclient.registerManual({name: 'github',call_template_type: 'mcp',/* config */});awaitclient.registerManual({name: 'slack',call_template_type: 'http',/* config */});awaitclient.registerManual({name: 'db',call_template_type: 'file',file_path: './db-tools.json'});// This loads a UTCP manual from a json fileconstresult=awaitclient.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:

constresult=awaitclient.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 { toolsAvailable: hasSlackTools };`);

Context-Efficient Data Processing

Process large datasets without bloating the model's context:

constresult=awaitclient.callToolChain(` // Fetch large dataset const allIssues = await github.list_repository_issues({ owner: 'facebook', repo: 'react' }); console.log('Fetched', allIssues.length, 'total issues'); // Process efficiently in-sandbox const criticalBugs = allIssues .filter(issue => issue.labels.some(l => l.name === 'bug')) .filter(issue => issue.labels.some(l => l.name === 'high priority')) .map(issue => ({ number: issue.number, title: issue.title, author: issue.user.login, daysOld: Math.floor((Date.now() - new Date(issue.created_at)) / (1000 * 60 * 60 * 24)) })) .sort((a, b) => b.daysOld - a.daysOld); // Only return processed summary (not 10,000 raw issues) return { totalIssues: allIssues.length, criticalBugs: criticalBugs.slice(0, 10), // Top 10 oldest critical bugs summary: \`Found \${criticalBugs.length} critical bugs, oldest is \${criticalBugs[0]?.daysOld} days old\` };`);

Error Handling & Observability

Built-in error handling with complete execution transparency:

const{ result, logs }=awaitclient.callToolChain(` try { console.log('Starting multi-step workflow...'); const data = await external_api.fetch_data({ id: 'user-123' }); console.log('Data fetched successfully'); const processed = await data_processor.transform(data); console.warn('Processing completed with', processed.warnings.length, 'warnings'); return processed; } catch (error) { console.error('Workflow failed:', error.message); throw error; // Propagates to outer error handling }`,30000);// 30-second timeout// Complete observabilityconsole.log('Result:',result);console.log('Execution logs:',logs);// ['Starting multi-step workflow...', 'Data fetched successfully', '[WARN] Processing completed with 2 warnings']

Custom Timeouts

Configure execution limits for different workload types:

// Quick operations (5 seconds)constquickResult=awaitclient.callToolChain(`return await ping.check();`,5000);// Heavy data processing (2 minutes) constheavyResult=awaitclient.callToolChain(` const bigData = await database.export_full_dataset(); return await analytics.process_dataset(bigData);`,120000);

AI Agent Integration

Plug-and-play with any AI framework. The built-in prompt template handles all the complexity:

import{CodeModeUtcpClient}from'@utcp/code-mode';constsystemPrompt=`You are an AI assistant with access to tools via UTCP CodeMode.${CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE}Additional instructions...`;// Works with any AI libraryconstresponse=awaitopenai.chat.completions.create({model: 'gpt-4',messages: [{role: 'system',content: systemPrompt},{role: 'user',content: 'Analyze the latest PR in microsoft/vscode'}]});

The template provides comprehensive guidance on:

Tool discovery workflow (searchTools → __interfaces → callToolChain)
Hierarchical access patterns (manual.tool() syntax)
Interface introspection (__getToolInterface())
Error handling and best practices

API Reference

Core Methods

`callToolChain(code: string, timeout?: number)`

Execute TypeScript code with full tool access and observability.

Returns: {result: any, logs: string[]} with execution result and captured console output
Default timeout: 30 seconds

`getAllToolsTypeScriptInterfaces()`

Generate complete TypeScript interfaces for IDE integration.

Returns: String containing all interface definitions with namespaces

`searchTools(query: string)`(from UtcpClient)

Discover tools using natural language queries.

Returns: Array of relevant tools with descriptions and interfaces

Static Methods

`CodeModeUtcpClient.create(root_dir?, config?)`

Create a new client instance with optional configuration.

`CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE`

Production-ready prompt template for AI agents.

Security & Performance

Secure by Design

Node.js VM sandboxing – Isolated execution context
No filesystem access – Tools only through registered servers
Timeout protection – Configurable execution limits
Zero network access – No external dependencies or API keys exposed

Performance Optimized

Minimal memory footprint – VM contexts are lightweight
Efficient tool caching – TypeScript interfaces cached automatically
Streaming console output – Real-time log capture without buffering
Identifier sanitization – Handles invalid TypeScript identifiers gracefully

Development Experience

IDE Integration

Generate TypeScript definitions for full IntelliSense support:

# Generate tool interfaces 
const interfaces = await client.getAllToolsTypeScriptInterfaces();
await fs.writeFile('generated-tools.d.ts', interfaces);# Add to tsconfig.json
{
"compilerOptions": {
"typeRoots": ["./generated-tools.d.ts"]
}
}

Debug & Monitor

Built-in observability for production deployments:

const{ result, logs }=awaitclient.callToolChain(userCode);// Ship logs to your monitoring systemlogs.forEach(log=>{if(log.startsWith('[ERROR]'))monitoring.error(log);if(log.startsWith('[WARN]'))monitoring.warn(log);});

Benchmark Methodology

The comprehensive Python study tested 16 realistic scenarios across:

Financial workflows (invoicing, expense tracking)
DevOps operations (deployments, monitoring)
Data processing (analysis, reporting)
Business automation (CRM, notifications)

Models tested: Claude Haiku, Gemini Flash
Pricing basis: $0.25/1M input, $1.25/1M output tokens
Scale: 1,000 scenarios/day = $9,536/year savings with Code Mode

Learn More

Cloudflare Research – Original code mode whitepaper
Anthropic Study – MCP code execution benefits
Python Benchmark Study – Comprehensive performance analysis
UTCP Specification – Official TypeScript implementation
Report Issues – Bug reports and feature requests

License

MPL-2.0 – Open source with commercial-friendly terms.

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
code-mode-cli		code-mode-cli
code-mode-mcp		code-mode-mcp
python-library		python-library
typescript-library		typescript-library
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Uh oh!

Folders and files

Latest commit

History

Repository files navigation