CodeRun AI Agent Documentation

💾 How to Save Providers: Step-by-Step Guide

CodeRun allows you to save credentials and endpoints for multiple providers simultaneously. You do not need to re-enter your API keys or base URLs when switching between local and cloud models.

CodeRun Settings & Saved Providers Live Interactive Simulator

Settings Form Static Screenshot

Provider Ollama OpenAI Anthropic Google Gemini OpenRouter xAI (Grok) Groq OpenAI Compatible

Custom Provider Name

API Type OpenAI Compatible Anthropic Compatible Google Gemini Compatible

Base URL

API Key

Model

Max Iterations

Enable Streaming

Show Thinking

Confirm Dangerous Actions

Save Settings Reset Form

✓ Provider credentials saved successfully to state!

Saved Providers (3) ● Live Multi-Endpoint Store

Figure 1 (Static Capture): The Provider Settings panel inside CodeRun sidebar showing the Custom Compatible provider configured.

🔄 How Saved Providers Reflect in CodeRun

Once saved, CodeRun immediately binds the configuration across the entire extension lifecycle:

🛡️ Google Gemini Schema Sanitization

Google Gemini's Protobuf schema parser rejects complex JSON Schema attributes that standard OpenAI models permit. When using Gemini (via Google's REST API or OpenAI-compatible gateway), CodeRun automatically runs a deep recursive schema filter:

// Recursively strips attributes that cause Gemini HTTP 400 Bad Request
function sanitizeGeminiSchema(schema) {
  // Prunes: additionalProperties, $schema, title, $defs, definitions
  // Normalizes model strings: models/gemini-2.0-flash -> gemini-2.0-flash
}

🎨 Universal Media Generation, Native HTML5 Player & Storage Isolation

Specialized multimodal generative models (such as dall-e-3, imagen-3, flux, sdxl, sora, kling, runway, minimax, or compatible video/image proxies like agnes-image-2.5-flash and agnes-video-2.5-flash) cannot process chat completion payloads sent to /v1/chat/completions.

CodeRun provides an end-to-end, provider-agnostic media pipeline featuring automated modality classification, adaptive parameter self-healing, native zero-dependency HTML5 playback, isolated persistent storage, and differentiated request timeouts:

Active Model: agnes-image-2.5-flash 9.9K tokens

Prompt: "generate a cute image a dog" 📥 Save to Project

// Dynamic timeout: 10 minutes for local LLMs, 30 seconds for remote cloud
var timeoutMs = isLocalEndpoint(config) ? 600000 : 30000;

// Universal video generation with adaptive retry & async polling
var vidResult = await provider.videos(config, prompt);
// Persisted strictly in globalStorage (never pollutes workspace)
var saved = await mediaManager.saveMediaFromDataOrUrl(null, sessionId, vidResult, 'mp4');

🔌 Model Context Protocol (MCP) Integration

The Model Context Protocol (MCP) is an open specification enabling AI models to safely access external data sources and execution runtimes. CodeRun provides a full stdio and SSE/HTTP client, allowing the agent to dynamically discover tools, read schemas, and invoke functions in real-time.

Model Context Protocol (MCP) Dashboard Live Interactive Simulator

Live Dashboard Static Screenshot

MCP (Model Context Protocol)

Manage and configure external tool servers for the AI agent

+ Add MCP

Enable Function Calling / Agent Tools

When disabled, tools parameter is omitted from API requests so models/APIs that block tools will not error.

⚡ Core Agent Built-in Tools Built-in (36 active)

Filesystem, Search, Terminal, Planning, Interaction, Utility, Sandbox, Database, Subagent, Media

Enable All Disable All

Connected MCP Servers (2)

Figure 3 (Static Capture): The CodeRun MCP Panel displaying native function calling toggle, Core Agent Built-in Tools, and Web Fetcher card.

⚙️ How to Add & Save Custom MCP Servers

You can attach any community or custom MCP server directly in the CodeRun interface:

🔍 How MCP Reflects in Execution

Once an MCP server connects, CodeRun dynamically integrates its capabilities:

• Connection Status Indicator: The server card shows a bright green dot (Connected) and a pill badge indicating transport (STDIO or SSE).
• Discovered Tools Accordion: Expand the Tools (X/Y active) dropdown to inspect every tool discovered from the server. Each tool has its own toggle switch so you can enable or disable specific tools individually.
• Namespaced Registration: Tools are registered into the agent loop with namespaced identifiers: mcp__<server>__<tool> (e.g. mcp__puppeteer__navigate, mcp__github__create_pull_request).
• Permission Prompting: When the model requests an MCP tool, CodeRun displays an interactive permission prompt in the chat card with arguments preview, allowing you to Allow Once, Always Allow, or Deny.

🌐 Zero-Config Browser Automation & On-Install Setup

CodeRun features intelligent browser discovery and auto-installation for Puppeteer. It automatically scans your operating system for installed browsers:

On-Install Dedicated Chromium Fallback: If no system browser is found, CodeRun automatically installs a self-contained, dedicated Chromium binary into ~/.coderun/browser/ using @puppeteer/browsers. Puppeteer MCP tools (such as puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_select, puppeteer_hover, and puppeteer_evaluate) work out-of-the-box without requiring manual browser installation or external driver configuration.

📦 Transparent User Sandbox & Terminal CWD Synchronization

In addition to the active project workspace, CodeRun transparently provisions a dedicated user scratch sandbox at ~/.coderun/sandbox/:

🤖 Autonomous Subagent Workers & Multi-Agent Delegation

CodeRun features an autonomous multi-agent orchestration architecture. Main agents can decompose complex objectives and spawn dedicated child AI agents (subagents) running their own independent execution loops:

⚙️ Dedicated Subagent Settings Panel (🤖)

Configure independent provider credentials, model selections, and execution boundaries for subagents directly from the dedicated Subagent Settings panel:

🛠️ Subagent Tools Suite

The agent orchestration engine exposes 8 dedicated subagent tools:

🪵 Hierarchical Execution Traces & Isolation

Subagent runs maintain strict execution and diagnostic isolation:

🧠 Native VS Code LSP & Diagnostic Self-Reflection

CodeRun interacts directly with VS Code's internal language provider commands and diagnostic channels, with automatic local token fallback if running headless or uninitialized:

🧰 The Complete 36-Tool Matrix

CodeRun comes equipped with 36 built-in core tools across 9 operational categories:

💬 Interactive User Questions (ask_question)

When the model encounters architectural ambiguity, design options, or missing configuration details, it invokes ask_question to render an interactive decision banner directly inside the chat interface:

📋 Message Copy Buttons & Clipboard Fidelity

CodeRun provides dedicated one-click copy buttons across all conversational turns and code blocks, ensuring exact text fidelity without UI contamination, markdown corruption, or metadata leakage:

💻 Interactive Terminal REPLs & Dual Terminal Architecture

Unlike basic assistants that fail when a command asks for user input or hide background dev servers in opaque processes, CodeRun features dual visible terminal sessions per chat with full interactive and background lifecycle support:

• Dual Dedicated Terminals: Every chat provisions two visible VS Code terminal sessions:
  • CodeRun(main): Runs direct CLI commands, tests, builds, and interactive REPLs with real-time output streaming.
  • CodeRun(BG): Runs background dev servers (npm run dev, vite, daemons) with continuous output streaming and automatic localhost URL/port sniffing.
• Interactive Flag: When running commands like python -i, node, npm init, or interactive CLI prompts, the agent passes interactive: true.
• Live Keystroke Delivery: Using terminal_input, CodeRun sends stdin keystrokes directly into the active pseudo-terminal.
• Selective Terminal Interrupts: stop_terminal sends clean Ctrl+C signals with granular target selection:
  • foreground (default): Interrupts hanging foreground commands in CodeRun(main) without killing background dev servers.
  • background: Gracefully terminates dev servers in CodeRun(BG) without disturbing the foreground shell.
  • all: Aborts running executions across both terminal sessions.
• UI Transparency & Distinguishable Badging: Terminal cards in the chat view (src/UI/chats/) display real-time output streams badged with emerald CodeRun(main) or indigo CodeRun(BG) indicators.
• ANSI Stripping: All terminal outputs are stripped of ANSI escapes and OSC codes before presentation.

🛡️ Dynamic Error Boundary & Card Containment

In CodeRun, error notifications are encapsulated in responsive, auto-expanding cards:

• Zero Boundary Spill: Long uninterrupted URLs (such as Google Gemini API rate limits or stack traces) break cleanly onto new lines using overflow-wrap: anywhere and word-break: break-word.
• Dynamic Card Height: The red card expands vertically as needed to accommodate the entire diagnostic message without clipping.
• Top-Aligned Status Icons: Status icons are pinned to the top-left of multi-line error blocks rather than floating in the center.
• Deduplication Pipeline: Webview error handling unifies internal agent loop events and terminal stream failures, stripping redundant Error: prefixes and preventing duplicate stacked error cards.

📊 Live Context Window & Monotonic Token Tracking

CodeRun features an intelligent context saturation monitoring system:

• Monotonic Accumulation: Token counts strictly accumulate across turns and tool iterations. Total Consumed never decrements or resets unexpectedly.
• Live Context Window Gauge: Visual progress bar and token ratio (X / Y (Z%)) indicating current occupancy.
• Saturation Alerts: Progress bar shifts from blue to amber (≥70%) and critical red (≥90%) as the context window fills.
• Session Info Modal: Click the token badge anytime to inspect Total Consumed, active Context Window usage, Input / System tokens, Output / Response tokens, and trigger 1-click conversation compaction.

📦 0ms Local Context Compaction & Checkpoint Cards

CodeRun features zero-latency, zero-cost deterministic conversation compaction implemented in compactionManager.js. Rather than making external LLM summarization API calls that eat tokens, CodeRun synthesizes structured chronological checkpoints locally:

⚡ Multi-Turn Context Optimization & Historical Tool Compaction

In multi-turn coding sessions, repeated tool outputs (such as large file reads or verbose build logs from earlier turns) can quickly saturate the LLM's context window. CodeRun solves this with intelligent two-phase context optimization:

Selective Failure & Mutation Protection:

• Failures Preserved: If any tool execution fails, the complete error message, stack trace, and exit codes are preserved in full so the model remembers what went wrong.
• Mutations Preserved: File modification tools (write_file, edit_file, patch_file, delete_file) retain their complete responses so the model remembers what code was written or edited.
• 100% Wire Protocol Integrity: The assistant's tool_calls and the tool's tool_call_id remain strictly matched, ensuring full compatibility with OpenAI, Anthropic, Gemini, and Ollama function-calling schemas.
• Zero UI / Storage Regression: Webview tool cards, execution traces, checkpoints, and SQLite logs retain 100% full-fidelity history.

📜 Global & Workspace Rules Engine

Instruct CodeRun on coding conventions, style rules, and repository architectural patterns:

Rules follow a strict precedence hierarchy: Global Rules → Workspace Rules → Active Chat Instructions.

🧭 Current Engineering Contract

CodeRun keeps its implementation deliberately small and explicit. These conventions apply to source files, scripts, webview code, and tests so changes remain easy to review and safe to run.

npm test
node --check src/extension/agents/agentLoop.js
node --check src/extension/tools/toolExecutor.js

🧪 88 Adversarial Regression Test Suite

Every build of CodeRun is verified against an exhaustive 88-group adversarial test suite with 0 external dependencies:

node test/runAllTests.js

Tests verify multi-session isolation, optimistic concurrency SHA-256 locking, SSRF protection filters, secret token redaction, checkpoint rollbacks, signal cancellation, interactive command detection, MCP dynamic registration, dedicated sandbox tools & terminal CWD synchronization, multi-turn historical tool result optimization, complete response summary preservation, interactive user question lifecycle, subagent identity hierarchy & recursion blocking (Vector 51), subagent lifecycle state machine transitions (Vector 52), subagent manager operations (Vector 53), checkpoint & diff attribution per agentId (Vector 54), execution trace subagent isolation (Vector 55), subagent tools suite execution (Vector 56), subagent UI panel contracts (Vector 57), subagent wait/async execution modes (Vector 58), subagent trace persistence (Vector 59), UI scrollability (Vector 60), parallel non-blocking execution with live dropdown updates (Vector 61), multi-step subagent execution chaining (Vector 62), subagent background polling & wait_for_subagent timeout handling (Vector 63), subagent error boundaries & tool failure containment (Vector 64), model inheritance fallback & dedicated provider resolution (Vector 65), subagent token usage attribution (Vector 66), staged diff isolation across concurrent subagents (Vector 67), multi-agent message bus synchronization (Vector 68), subagent abort signal propagation & process cleanup (Vector 69), subagent UI panel state retention across tab switches (Vector 70), live dropdown synchronization during background agent runs (Vector 71), subagent checkpoint undo reflection across diff cards, tool cards, and chat traces (Vector 72), model modality classification, UI badging, media endpoint routing, and globalStorage persistence (Vector 73), webview media display, dynamic URI rewriting, and chat persistence (Vector 74), Save to Project direct workspace download & stored conversation loading (Vector 75), custom interactive HTML5 video player controls & progress scrubber (Vector 76), universal OpenAI-compatible image & video extraction, polling & adaptive retry (Vector 77), differentiated request timeouts for 10m local LLMs vs 30s cloud endpoints (Vector 78), dual terminal sessions (direct & background) per chat with distinct CodeRun(main) / CodeRun(BG) naming, lifecycle isolation, and selective stopping (Vector 79), pure JavaScript Python MCP Manager, environment isolation, unbuffered stdio, and template assets (Vector 80), calling model API animation & unified reasoning tokens contract (Vector 81), universal provider reasoning deduplication, tool fallback & chronological DOM contract (Vector 82), terminal execution integrity, stream tool buffering & redundant thought prevention (Vector 83), model-driven interactivity & background decision contract (Vector 84), terminal pager hang prevention, git pager suppression & model selection sync (Vector 85), check_terminal_state tool contract, main vs background introspection & exit code zero verification (Vector 86), agent loop active input box animation (Copilot blue border flow) contract & state synchronization (Vector 87), and prompt builder orphan tool call sanitization, executionTrace path binding & stream watchdog message sequence integrity (Vector 88).

❓ Troubleshooting & FAQ