Code-Mode Library

code-mode-library · universal-tool-calling-protocol/code-mode · ★ 1.5k · last commit 2026-05-03

Primitive shape 1 total

MCP tools 1

Summary

Code-Mode Library — Summary

A TypeScript/Python library (and companion MCP server) that replaces traditional tool-calling with code execution as the primary agent interaction pattern. Instead of exposing hundreds of individual MCP tools, Code-Mode gives the LLM ONE tool — a TypeScript/Python sandbox — and makes all registered tools available as typed namespace functions within that sandbox. The LLM writes code that calls multiple tools in a single execution, rather than making sequential tool-call API roundtrips.

The core claim, backed by benchmarks: complex workflows that require 8+ tools traditionally require 16 API iterations; with Code-Mode they require 1 execution — an 88% reduction. Independent benchmarks validate $9,536/year cost savings at 1,000 scenarios/day. The project cites Apple, Cloudflare, and Anthropic research validating the "code-mode" approach.

Built by the Universal Tool Calling Protocol (UTCP) organization. Supports MCP, HTTP, CLI, and file-based tool registrations. The companion MCP server (@utcp/code-mode-mcp) wraps the library for use with Claude Code and other MCP clients, providing call_tool_chain as the single execution tool. With 1,461 stars, this is the most-starred repository in this batch by a significant margin.

Compared to seeds: no direct seed analog. Closest to claude-flow (Archetype 3 — MCP server providing a unified tool execution surface) but the architectural philosophy is opposite — claude-flow maximizes the number of discrete tools, Code-Mode collapses all tools into a single code execution primitive. This is a fundamental rethinking of the tool-calling paradigm.

Overview

Code-Mode Library — Overview

Origin

Created by the Universal Tool Calling Protocol (UTCP) organization on GitHub. Published November 2025, actively maintained through May 2026. The library is part of a broader UTCP ecosystem that also includes @utcp/sdk, @utcp/mcp, @utcp/http, @utcp/cli, @utcp/text, and @utcp/file packages.

Philosophy

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

The framework cites three primary research validations:

Apple: CodeAct (code-as-actions research)
Cloudflare: "Code Mode" blog post
Anthropic: Code execution with MCP research

Benchmark Results (from README — independent study)

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

Cost savings: $9,536/year at 1,000 scenarios/day (independent Python benchmark study).

Key Innovations

Progressive Tool Discovery: Agent searches for tools dynamically (searchTools('github pull request')) instead of receiving all tool definitions upfront
Auto-generated TypeScript interfaces: Each registered tool gets a TypeScript namespace with typed parameters
Batching advantage: One code block replaces multiple sequential API calls
Cognitive efficiency: LLMs write code better than they orchestrate tool sequences

Ecosystem

Part of UTCP (Universal Tool Calling Protocol) — a proposed alternative/complement to MCP for the tool calling ecosystem.

Architecture

Code-Mode Library — Architecture

Distribution

Three delivery mechanisms:

typescript-library/ — @utcp/code-mode npm package (TypeScript)
python-library/ — Python package
code-mode-mcp/ — @utcp/code-mode-mcp npm package (MCP server wrapping the library)

Install (TypeScript library)

npm install @utcp/code-mode
# Also need transport plugins:
npm install @utcp/mcp  # for MCP servers
npm install @utcp/http  # for HTTP APIs

Install (MCP Server — easiest path)

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

Repository Structure

code-mode/
├── typescript-library/    # @utcp/code-mode (main library)
│   └── ...
├── python-library/        # Python equivalent
│   └── ...
└── code-mode-mcp/         # @utcp/code-mode-mcp (MCP server wrapper)
    ├── index.ts           # MCP server entry point
    ├── .utcp_config.json  # Example UTCP config
    └── package.json

UTCP Config Schema

{
  "load_variables_from": [{"variable_loader_type": "dotenv", "env_file_path": ".env"}],
  "manual_call_templates": [
    {
      "name": "openlibrary",
      "call_template_type": "http",
      "url": "https://openlibrary.org/static/openapi.json"
    }
  ],
  "post_processing": [
    {
      "tool_post_processor_type": "filter_dict",
      "only_include_keys": ["name", "description"]
    }
  ],
  "tool_repository": {"tool_repository_type": "in_memory"},
  "tool_search_strategy": {"tool_search_strategy_type": "tag_and_description_word_match"}
}

Transport Plugins (side-effect imports)

import "@utcp/mcp";    // enables MCP server connections
import "@utcp/http";   // enables REST API connections
import "@utcp/cli";    // enables CLI tool execution
import "@utcp/text";   // enables text-based configs
import "@utcp/file";   // enables file-based configs
import "@utcp/dotenv-loader";  // enables .env variable loading

Execution Sandbox

Node.js VM sandbox (vm module or isolated-vm) executes user TypeScript code with tool namespaces injected.

Components

Code-Mode Library — Components

MCP Server (code-mode-mcp)

The @utcp/code-mode-mcp package exposes ONE MCP tool:

Tool	Description
`call_tool_chain`	Execute TypeScript code with all registered tools available as namespace functions

Additional helper tool (likely):

Tool	Description
`search_tools`	Search registered tools by keyword (progressive discovery)

TypeScript Library APIs (`@utcp/code-mode`)

Class/Function	Purpose
`CodeModeUtcpClient.create()`	Initialize the client with tool repository
`client.registerManual({name, call_template_type, config})`	Register an MCP/HTTP/CLI tool source
`client.callToolChain(typescriptCode: string)`	Execute TypeScript in sandbox with registered tools
`client.searchTools(query: string)`	Search tools dynamically (progressive discovery)

Transport Plugins (6 separate packages)

Package	Protocol
`@utcp/mcp`	MCP servers (stdio transport)
`@utcp/http`	REST APIs with OpenAPI auto-discovery
`@utcp/cli`	Local CLI tools
`@utcp/text`	Text-based tool configs
`@utcp/file`	JSON/YAML file configs
`@utcp/dotenv-loader`	.env variable injection

Auto-generated TypeScript Interfaces

Each registered tool gets an auto-generated TypeScript namespace:

namespace github {
  interface get_pull_requestInput {
    owner: string;   // Repository owner
    repo: string;    // Repository name
    pull_number: number;  // Pull request number
  }
  function get_pull_request(input: get_pull_requestInput): Promise<...>
}

No Skills, Commands, Hooks

Purely library + MCP server. No Claude Code skill files or hooks.

Prompts

Code-Mode Library — Prompts

The Single Tool Approach

Code-Mode's key prompt design is the call_tool_chain tool itself. Instead of an agent receiving 500 tool definitions, it receives ONE tool with a TypeScript execution interface. The agent's "prompt" for using tools is: write TypeScript code.

Auto-Generated TypeScript Interfaces as Prompts

The auto-generated TypeScript namespace interfaces serve as the agent's prompt for each tool. Example (from README):

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

JSDoc comments on parameters serve as inline documentation — the agent reads TypeScript types + JSDoc to understand how to call each tool, rather than reading MCP tool schemas.

Tool Search as Prompt Narrowing

// Agent queries for tools semantically
const tools = await client.searchTools('github pull request');
// Returns: 3 relevant tool names + brief descriptions
// Only THEN are full schemas loaded

This is progressive disclosure via semantic search — the agent decides which tool documentation to load based on its current task.

Prompting Technique Classification

Code-as-instructions: The agent's instructions are TypeScript code, not natural language
Type-driven: TypeScript interfaces provide the "prompt" for correct tool usage
Progressive discovery: searchTools loads only relevant tool schemas on demand
JSDoc as documentation: Parameter descriptions embedded in TypeScript type annotations
Batching by design: The code execution model encourages multi-tool workflows in a single "thought"

Uniqueness

Code-Mode Library — Uniqueness

differs_from_seeds

No direct seed analog. The closest seed in architecture is claude-flow (large MCP server suite), but Code-Mode is the philosophical opposite: claude-flow maximizes discrete tool count (305 tools), Code-Mode collapses all tools into one code execution interface. ccmemory (MCP-anchored toolserver) is also structurally similar (one MCP server doing heavy lifting), but ccmemory stores memory while Code-Mode executes arbitrary code with tool access. None of the 11 seeds explore the "code execution as the tool-calling interface" paradigm.

Positioning

Code-Mode represents the most radical rethinking of the tool-calling model in this entire research corpus. Rather than improving how tools are described or when they load, it eliminates the tool-call paradigm entirely and replaces it with code execution. The agent writes TypeScript instead of making tool calls.

Distinctive Opinion

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

This is a falsifiable, empirically-backed claim. The independent benchmark study linked in the README provides evidence at scale (1,000 scenarios/day).

Observable Failure Modes

VM sandbox is not truly secure: Node.js vm module doesn't prevent system calls — the @utcp/cli plugin "lets a manual run arbitrary local commands" (README warning)
TypeScript code quality dependency: If the LLM writes buggy TypeScript, the execution fails; there's no partial result
No streaming: Code execution blocks until complete; long operations have no intermediate output
Context for type interfaces: Auto-generated TypeScript interfaces still need to be loaded into context for the LLM to use them correctly
Protocol maturity: UTCP is newer and less battle-tested than MCP; tool server compatibility uncertain

What Makes It Novel vs. the 11 Seeds

Only framework replacing tool calls with code execution as the primary agent interaction paradigm
Only framework with auto-generated TypeScript interfaces for all registered tools
Only framework using semantic tool search (not preloading all definitions)
Most stars in this batch (1,461) by a significant margin
Only framework citing Cloudflare and Apple research papers as direct inspiration
Only framework in UTCP ecosystem (alternative to MCP)
Only framework supporting Python + TypeScript + MCP server delivery simultaneously

Workflow

Code-Mode Library — Workflow

Traditional Tool Calling vs Code-Mode

Traditional (4 API roundtrips):

Agent → tools/call(get_pull_request)   → roundtrip 1
Agent → tools/call(get_comments)       → roundtrip 2
Agent → tools/call(get_reviews)        → roundtrip 3
Agent → tools/call(get_files)          → roundtrip 4
Agent now has all data → generates response

Code-Mode (1 execution):

Agent → call_tool_chain(`
  const pr = await github.get_pull_request({...});
  const comments = await github.get_pull_request_comments({...});
  const reviews = await github.get_pull_request_reviews({...});
  const files = await github.get_pull_request_files({...});
  return {title: pr.title, commentCount: comments.length, ...};
`)
→ single API call, all data processed in-sandbox, returns summary

Progressive Tool Discovery

// Instead of loading all 500 tool definitions:
const tools = await client.searchTools('github pull request');
// Returns: 3 relevant tools instead of 500 definitions

Setup Workflow (MCP server approach)

# 1. Create UTCP config
cat > .utcp_config.json << 'EOF'
{"manual_call_templates": [{"name": "github", "call_template_type": "mcp", ...}]}
EOF

# 2. Add to MCP client config
claude mcp add-json utcp-codemode '{"type":"stdio","command":"npx","args":["@utcp/code-mode-mcp"],"env":{"UTCP_CONFIG_FILE":"/path/to/.utcp_config.json"}}'

# 3. Restart Claude Code
# 4. Use: Claude can now call call_tool_chain with TypeScript code

Phase/Artifact Table

Phase	Artifact
register tools	in-memory tool repository
search tools	ranked tool list (subset)
execute code	result object + console logs
post-processing	filtered tool responses

Approval Gates

None. Code executes in sandbox immediately.

Memory Context

Code-Mode Library — Memory & Context

In-Memory Tool Repository

The tool_repository_type: "in_memory" UTCP config stores all registered tool definitions in memory. No persistent database.

Context Window Optimization

Code-Mode's progressive discovery strategy dramatically reduces context window usage:

Scenario	Traditional	Code-Mode
500 tools idle	500 × ~200 tokens = 100k tokens	1 tool definition = ~500 tokens
3 tools active	500 × ~200 tokens = 100k tokens	3 tool definitions = ~1.5k tokens

The searchTools function returns only matching tools, and only their names/descriptions initially. Full schemas loaded on demand.

Execution Sandbox State

The Node.js VM sandbox is fresh per callToolChain invocation. No persistent state between executions.

Config Persistence

.utcp_config.json is the persistent config file defining which tool sources to register. Preserved across sessions.

Post-Processing Filters

{
  "tool_post_processor_type": "filter_dict",
  "only_include_keys": ["name", "description"],
  "only_include_tools": ["openlibrary.*"]
}

Post-processors reduce tool response sizes before they enter the agent's context, providing another layer of context efficiency.

Console Output Capture

The sandbox captures console.log output, allowing the agent to use logging for debugging:

const { result, logs } = await client.callToolChain(`
  console.log('Processing PR...');
  const pr = await github.get_pull_request({...});
  return pr.title;
`);
// result: "PR title"
// logs: ["Processing PR..."]

Orchestration

Code-Mode Library — Orchestration

Multi-Agent Pattern

None. Code-Mode is a single-agent tool-execution library. Multi-agent coordination is not addressed.

Execution Mode

one-shot per callToolChain invocation. Each code execution is discrete.

Isolation Mechanism

Node.js VM sandbox — code executes in an isolated context. The README mentions:

"Secure VM Sandboxing – Node.js isolates prevent unauthorized access" "Timeout Protection – Configurable execution limits prevent runaway code"

Note: Node.js vm module is not a true security sandbox — it prevents access to variables but not to system calls via require. The README's security claim should be taken with caution.

Multi-Model

Not applicable. Code-Mode is model-agnostic.

Tool Execution Model

callToolChain(code) →
  1. Parse TypeScript code
  2. Inject tool namespaces into sandbox
  3. Execute code in VM
  4. Each tool call in code → MCP/HTTP/CLI call
  5. Return {result, logs}

Tool calls within the code execute in order (or in Promise.all for parallel):

// Sequential (default)
const pr = await github.get_pull_request({...});
const reviews = await github.get_pull_request_reviews({...});

// Parallel (via Promise.all)
const [pr, reviews] = await Promise.all([
  github.get_pull_request({...}),
  github.get_pull_request_reviews({...})
]);

Prompt Chaining

Yes — the code itself is the chain. Sequential await calls chain tool outputs as inputs:

const issue = await github.get_issue({number: 123});
const pr = await github.create_pull_request({title: issue.title + " fix"});

Concurrency

Within a single callToolChain, tools can run in parallel via Promise.all. This is the native JavaScript concurrency model.

Ui Cli Surface

Code-Mode Library — UI & CLI Surface

Dedicated CLI Binary

No. The library is used programmatically or via the MCP server (npx @utcp/code-mode-mcp).

Local Web Dashboard

None.

Claude Code Integration

claude mcp add-json --scope user utcp-codemode \
  '{"type":"stdio","command":"npx","args":["@utcp/code-mode-mcp"],
    "env":{"UTCP_CONFIG_FILE":"/absolute/path/to/.utcp_config.json"}}'
# Verify:
claude mcp list
# Remove:
claude mcp remove utcp-codemode --scope user

Developer Tooling

Dev registration script for development against the bridge:

cd code-mode-mcp
npm install
npm run dev:register     # builds lib + bridge, registers as 'utcp-codemode-dev'
# After every edit:
npm run dev:rebuild      # rebuilds and re-registers

Cross-Tool Portability

High — MCP server works with any MCP client. TypeScript library works with any Node.js application. Explicitly documented for Claude Code, Claude Desktop.

Observability

Console output capture in callToolChain result
logs array in return value

Enterprise Support

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

Enterprise consultation link provided — indicates commercial support available.

Related frameworks

same archetype · same primary tool · same memory type

Context Mode ★ 16k

A19 Token-efficient encoding

Keeps raw tool output data out of the context window via sandbox execution and SQLite+FTS5 session indexing, reducing context…

lean-ctx ★ 2.2k

A19 Token-efficient encoding

A full-session context runtime that compresses file reads (10 modes), shell output (60+ patterns), and session memory (CCP) to…

Nemp Memory ★ 101

A19 Token-efficient encoding

Persists AI agent context across sessions as 100%-local plain JSON files with zero dependencies, zero cloud, and agent identity…

CogniLayer v4 ★ 28

A19 Token-efficient encoding

Provides AI coding agents with typed semantic memory, tree-sitter code intelligence, and a multi-agent coordination protocol to…

cursor-coding-agent-os (Mugiwara555343) ★ 3

A19 Token-efficient encoding

Lean/Verbose dual-mode Agent OS fork for solo developers on token budgets.

rtk (Real Token Killer) ★ 55k

A19 Token-efficient encoding

Intercepts Claude Code's Bash tool calls at the PreToolUse hook and compresses verbose CLI output (git status, test runners,…

Distribution

Type: npm-package
License: MPL-2.0
Install: npm-install
Version: latest (active development through 2026-05-03)

Surfaces

CLI binary: No
CLI subcmds: 0
Local UI: No

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 1
MCP tools: 1
Scripts: 0
Templates: 1

Workflow

Phases: 5
Approval gates: 0
Spec format: none
Spec storage: none
Delta or full: none

Orchestration

Multi-agent: No
Pattern: none
Max concurrent: 0
Isolation: sandbox-api
Consensus: none
Prompt chaining: Yes

Multi-model

Multi-model: No
BYOK: Yes
Modal: text

Execution

Mode: one-shot
Crash recovery: No
Compaction: Yes
Session handoff: No
Streaming: No

Memory

Type: none
Persistence: session
Search: full-text
State files: 1 file

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: No
Audit format: none
Replay: No

Tools

Primary: claude-code
Targets: 3
Portability: high

Signals

Stars: 1.5k
Last commit: 2026-05-03
Maintainer: active
Quality score: 1.5/10

Summary

Code-Mode Library — Summary

Overview

Code-Mode Library — Overview

Origin

Philosophy

Benchmark Results (from README — independent study)

Key Innovations

Ecosystem

Architecture

Code-Mode Library — Architecture

Distribution

Install (TypeScript library)

Install (MCP Server — easiest path)

Repository Structure

UTCP Config Schema

Transport Plugins (side-effect imports)

Execution Sandbox

Components

Code-Mode Library — Components

MCP Server (code-mode-mcp)

TypeScript Library APIs (@utcp/code-mode)

Transport Plugins (6 separate packages)

Auto-generated TypeScript Interfaces

No Skills, Commands, Hooks

Prompts

Code-Mode Library — Prompts

The Single Tool Approach

Auto-Generated TypeScript Interfaces as Prompts

Tool Search as Prompt Narrowing

Prompting Technique Classification

Uniqueness

Code-Mode Library — Uniqueness

differs_from_seeds

Positioning

Distinctive Opinion

Observable Failure Modes

What Makes It Novel vs. the 11 Seeds

Workflow

Code-Mode Library — Workflow

Traditional Tool Calling vs Code-Mode

Progressive Tool Discovery

Setup Workflow (MCP server approach)

Phase/Artifact Table

Approval Gates

Memory Context

Code-Mode Library — Memory & Context

In-Memory Tool Repository

Context Window Optimization

Execution Sandbox State

Config Persistence

Post-Processing Filters

Console Output Capture

Orchestration

Code-Mode Library — Orchestration

Multi-Agent Pattern

Execution Mode

Isolation Mechanism

Multi-Model

Tool Execution Model

Prompt Chaining

Concurrency

Ui Cli Surface

Code-Mode Library — UI & CLI Surface

Dedicated CLI Binary

Local Web Dashboard

Claude Code Integration

Developer Tooling

Cross-Tool Portability

Observability

Enterprise Support

Related frameworks

TypeScript Library APIs (`@utcp/code-mode`)