Agent Maestro

Turn VS Code into your compliant AI playground! With Agent Maestro, spin up Cline or Roo on demand and plug Claude Code, Codex, or Gemini CLI straight in through an OpenAI/Anthropic/Gemini-compatible API.

Claude Code Support

Agent Maestro Demo

Key Features

Turn VS Code into your compliant AI playground with powerful API compatibility and one-click setup:

Universal API Compatibility: Anthropic (/messages), OpenAI (/chat/completions, /responses), and Gemini compatible endpoints - use Claude Code, Codex, Gemini CLI or any LLM client seamlessly
- Token Usage Reporting: Reports Copilot-provided Anthropic token usage when available, including prompt cache reads and writes, with estimated token counts as a fallback
One-Click Setup: Automated configuration commands for instant Claude Code, Codex, and Gemini CLI integration
Headless AI Agent Control: Create and manage tasks through REST APIs for Roo Code and Cline extensions
- Comprehensive APIs: Complete task lifecycle management with OpenAPI documentation at /openapi.json
- Parallel Execution: Run up to 20 concurrent RooCode (and its variants like Kilo Code) tasks with built-in MCP server integration
- Real-time Streaming: Server-Sent Events (SSE) for live task monitoring and message updates
- Flexible Configuration: Workspace-level settings, environment variables, and extension auto-discovery

Quick Start

Prerequisites

Agent Maestro assumes you already installed one of the supported AI coding extensions:

Roo Code or its variants for comprehensive API control
Claude Code for personal development routines
Codex for personal development routines
Gemini CLI for personal development routines

Installation

Install the Agent Maestro extension from the VS Code Marketplace. Once activated, Agent Maestro automatically starts its API server on startup.

One-Click Setup for Claude Code

Configure Claude Code to use VS Code's language models with a single command Agent Maestro: Configure Claude Code Settings via Command Palette.

This automatically creates or updates .claude/settings.json with Agent Maestro endpoint and fills in available LLM models from VS Code.

That's it! You can now use Claude Code with VS Code's built-in language models.

1M Context Support: Agent Maestro supports Claude 1M context models (e.g. claude-opus-4.7-1m-internal). To use the extended context window, run Agent Maestro: Configure Claude Code Settings and select the desired 1M model. Agent Maestro writes the model in the format Claude Code expects so the 1M path is selected consistently.

One-Click Setup for Claude Desktop

Configure Claude Desktop to use Agent Maestro's Anthropic-compatible proxy with Agent Maestro: Configure Claude Desktop Settings via Command Palette. The command creates or updates the local third-party inference configuration for macOS, Windows, or Linux. Fully quit and reopen Claude Desktop after configuring it.

One-Click Setup for Codex

Configure Codex to use VS Code's language models with a single command Agent Maestro: Configure Codex Settings via Command Palette.

This automatically creates or updates ~/.codex/config.toml with Agent Maestro endpoint and sets up GPT-5.5 as the recommended model.

One-Click Setup for Gemini CLI

Configure Gemini CLI to use VS Code's language models with a single command Agent Maestro: Configure Gemini CLI Settings via Command Palette.

You can choose between:

User Settings (~/.env): Personal global settings for all projects
Project Settings (.env in workspace): Team-shared project settings in source control

This automatically creates or updates the .env file with:

GOOGLE_GEMINI_BASE_URL: Agent Maestro Gemini endpoint
GEMINI_API_KEY: Default authentication token (preserved if already set)
GEMINI_MODEL: Your selected model from available VS Code language models
GEMINI_TELEMETRY_ENABLED: Disable telemetry by default

Additionally, it creates or updates settings.json in the same folder to skip the authentication method selection on first launch:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Experimental GPT-5+ Web Search Patch

Run Agent Maestro: Enable Experimental GPT-5+ Web Search to patch the built-in Copilot bundle for the currently running VS Code app and append the server-side web search tool from GPT-5+ OpenAI Responses requests.

This command:

Uses the currently loaded GitHub Copilot Chat extension bundle, including Extension Development Host bundles; falls back to the current VS Code app root when needed
Creates a timestamped backup before writing changes
Enables agent-maestro.experimentalGpt5PlusWebSearchEnabled so OpenAI Responses requests that include web search tools can signal the patched Copilot bundle
Applies the patch only once when the expected Copilot bundle shape is found
Reloads VS Code after the patch is applied

To undo the local patch, run Agent Maestro: Restore Experimental GPT-5+ Web Search Backup, choose one of the backups created for the currently loaded Copilot bundle, and Agent Maestro will restore it, disable agent-maestro.experimentalGpt5PlusWebSearchEnabled, and reload VS Code.

This is an experimental local modification. Agent Maestro only injects the web search tool declaration from the OpenAI Responses request, following the OpenAI web search tool guide; actual availability, behavior, and errors depend on the active Copilot model backend. VS Code updates can overwrite this patch.

See docs/experimental-gpt5-plus-web-search.md for implementation details, restore behavior, and troubleshooting notes.

Usage

Explore API Capabilities: Access the complete OpenAPI specification at http://localhost:23333/openapi.json.
VS Code Commands: Access functionality through the Command Palette:

Server Management:
- Agent Maestro: Start API Server - Start the proxy API server
- Agent Maestro: Stop API Server - Stop the proxy API server
- Agent Maestro: Restart API Server - Restart the proxy API server
- Agent Maestro: Get API Server Status - Check current server status
MCP Server Management:
- Agent Maestro: Start MCP Server - Start the Model Context Protocol server
- Agent Maestro: Stop MCP Server - Stop the MCP server
- Agent Maestro: Get MCP Server Status - Check current MCP server status
- Agent Maestro: Install MCP Configuration - Install MCP configuration for supported extensions
Extension Management:
- Agent Maestro: Get Extensions Status - Check the status of supported AI extensions
Configuration Commands:
- Agent Maestro: Configure Claude Code Settings - One-click Claude Code setup
- Agent Maestro: Configure Claude Desktop Settings - One-click Claude Desktop setup
- Agent Maestro: Configure Codex Settings - One-click Codex setup
- Agent Maestro: Configure Gemini CLI Settings - One-click Gemini CLI setup
- Agent Maestro: Enable Experimental GPT-5+ Web Search - Patch the current VS Code Copilot bundle to append web search for GPT major version 5 or newer model requests
- Agent Maestro: Restore Experimental GPT-5+ Web Search Backup - Restore a Copilot bundle backup created by the experimental patch command
- Agent Maestro: Set LLM API Key - Configure authentication for LLM API endpoints
Development Resources:
- API Documentation: Complete reference in docs/roo-code/
- Type Definitions: @roo-code/types package
- Examples: Reference implementation in examples/demo-site (testing purposes)

LLM API Authentication

Agent Maestro supports optional API key authentication to secure access to the LLM API endpoints (Anthropic, OpenAI, and Gemini). When enabled, all requests to these endpoints must include a valid API key.

Setting Up Authentication

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run Agent Maestro: Set LLM API Key
Enter your desired API key (or leave empty to disable authentication)

The API key is stored securely using VS Code's built-in secrets storage and persists across sessions.

Authenticating Requests

Once authentication is enabled, include your API key in requests using the standard header format for each provider:

Anthropic API (/api/anthropic/*):

curl -H "x-api-key: YOUR_LLM_API_KEY" \
  http://localhost:23333/api/anthropic/v1/messages

OpenAI API (/api/openai/*):

curl -H "Authorization: Bearer YOUR_LLM_API_KEY" \
  http://localhost:23333/api/openai/v1/chat/completions

Gemini API (/api/gemini/*):

curl -H "x-goog-api-key: YOUR_LLM_API_KEY" \
  http://localhost:23333/api/gemini/v1beta/models/gemini-3-pro:generateContent

Security Notes

Authentication is disabled by default for ease of local development
When authentication is disabled, the proxy accepts all requests without validation
API keys are compared using constant-time comparison to prevent timing attacks
Failed authentication attempts are logged for security monitoring

Configuration

Environment Variables

You can customize Agent Maestro's server ports using environment variables:

Variable	Description	Default
`AGENT_MAESTRO_PROXY_PORT`	Proxy server port	23333
`AGENT_MAESTRO_MCP_PORT`	MCP server port	23334

Usage:

# Set custom ports
export AGENT_MAESTRO_PROXY_PORT=8080
export AGENT_MAESTRO_MCP_PORT=8081

# Launch VS Code
code .

Note: Environment variables take precedence over extension settings.

Workspace-Level Configuration

You can configure Agent Maestro settings per workspace by adding them to your project's .vscode/settings.json file:

{
  "agent-maestro.defaultRooIdentifier": "rooveterinaryinc.roo-cline",
  "agent-maestro.proxyServerPort": 23333,
  "agent-maestro.mcpServerPort": 23334
}

Available Settings:

Setting	Description	Default
`agent-maestro.defaultRooIdentifier`	Default Roo extension to use	`"rooveterinaryinc.roo-cline"`
`agent-maestro.proxyServerPort`	Proxy server port	`23333`
`agent-maestro.mcpServerPort`	MCP server port	`23334`

This allows different projects to use different configurations without affecting your global VS Code settings.

Context Window Management

Agent Maestro proxies requests through VS Code's Language Model API, which uses a different tokenizer (OpenAI's tiktoken / O200K) than the actual model providers. This mismatch means the token counts reported locally can be lower than the real usage, potentially causing requests to exceed the model's context window and fail unexpectedly.

Agent Maestro reports real Copilot usage metadata for Anthropic responses when VS Code provides it. When that metadata is unavailable, Agent Maestro falls back to local token counting and reports those counts unscaled. Different coding agent clients manage their context windows differently:

Claude Code (and other Anthropic API clients): Fallback token estimates and /v1/messages/count_tokens responses report the raw VS Code token count. To make Claude Code compact context earlier and avoid edge cases near the model's full window, configure its CLAUDE_CODE_AUTO_COMPACT_WINDOW and CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variables — Agent Maestro writes these for you when you run Agent Maestro: Configure Claude Code Settings (default compaction at 85% of the model's reported window).
Codex: When you run Agent Maestro: Configure Codex Settings, Agent Maestro writes model_context_window into Codex's config.toml using the selected model's reported maxInputTokens. This tells Codex the effective context window size upfront so it manages its own conversation history accordingly. To customize it, edit model_context_window in ~/.codex/config.toml directly.

Prompt Cache Compatibility

Agent Maestro accepts common prompt cache hints such as Anthropic cache_control, OpenAI prompt_cache_key, and Gemini cachedContent without forwarding unsupported cache controls to VS Code's Language Model API. For Anthropic-compatible responses, Copilot-provided usage metadata is used when available to report cache_read_input_tokens and cache_creation_input_tokens; fallback estimates report cache usage as 0 rather than synthetic savings.

API Overview

💡 Always refer to /openapi.json for the latest API documentation.

Base URLs

REST API: http://localhost:23333/api/v1
Anthropic API: http://localhost:23333/api/anthropic
OpenAI API: http://localhost:23333/api/openai
Gemini API: http://localhost:23333/api/gemini
MCP Server: http://localhost:23334

Anthropic-Compatible Endpoints

Perfect for GitHub Copilot and Claude Code integration:

POST /api/anthropic/v1/messages - Anthropic Claude API compatibility using VS Code's Language Model API
POST /api/anthropic/v1/messages/count_tokens - Token counting for Anthropic-compatible messages

Reasoning effort: output_config.effort is forwarded to Copilot but is not yet applied to Anthropic Messages requests, pending upstream Copilot support. It currently has no effect for Claude models.

OpenAI-Compatible Endpoints

Perfect for Codex and OpenAI model integration:

POST /api/openai/v1/chat/completions - OpenAI Chat Completions API compatibility using VS Code's Language Model API
POST /api/openai/v1/responses - OpenAI Responses API compatibility using VS Code's Language Model API

Anthropic Messages and both OpenAI endpoints cancel the upstream language model request when the client disconnects or when the request remains unfinished for 10 minutes. Non-streaming timeouts return HTTP 504; streaming timeouts use each protocol's error event instead of a successful completion event.

Gemini-Compatible Endpoints

Perfect for Gemini CLI integration:

POST /api/gemini/v1beta/models/{model}:generateContent - Google Gemini API compatibility using VS Code's Language Model API
POST /api/gemini/v1beta/models/{model}:streamGenerateContent - Streaming support for Gemini API
POST /api/gemini/v1beta/models/{model}:countTokens - Token counting for Gemini-compatible messages

Thinking levels: Not forwarded for Gemini. Copilot's Gemini path does not read the thinkingConfig.thinkingLevel parameter from the model configuration; it only applies a hardcoded low effort behind an internal experiment flag, so any forwarded value would be ignored.

RooCode Agent Routes

Full-featured agent integration with real-time streaming:

POST /api/v1/roo/task - Create new RooCode task with SSE streaming
POST /api/v1/roo/task/{taskId}/message - Send message to existing task with SSE streaming
POST /api/v1/roo/task/{taskId}/action - Perform actions (pressPrimaryButton, pressSecondaryButton, cancel, resume)
GET /api/v1/roo/settings - Get current RooCode settings
GET /api/v1/roo/modes - Get available RooCode modes

VS Code Language Model API

Direct access to VS Code's language model ecosystem:

GET /api/v1/lm/tools - Lists all tools registered via lm.registerTool()
GET /api/v1/lm/chatModels - Lists available VS Code Language Model API chat models

Cline Agent Routes

Basic integration support:

POST /api/v1/cline/task - Create new Cline task (basic support)

Documentation Routes

GET /openapi.json - Complete OpenAPI v3 specification

Error Diagnostics

Agent Maestro automatically logs detailed error diagnostics when API requests fail. Each extension launch creates a timestamped log file in your workspace root: {YYYY}-{MM}-{DD}_{HH}-{MM}-{SS}-{mmm}-debug.log. All errors during that session are appended to the same file.

What's logged: Request payload, transformed VSCode LM messages, error details, extension metadata, model ID, endpoint, and timestamp.

Supported endpoints:

/api/anthropic/v1/messages (content sanitized)
/api/openai/v1/chat/completions (TODO: sanitization)
/api/openai/v1/responses (TODO: sanitization)
/api/gemini/v1beta/models/{model}:generateContent|streamGenerateContent (TODO: sanitization)

Privacy protection:

Anthropic only: User content is automatically redacted (text, images, documents, tool I/O, search results → [REDACTED])
OpenAI/Gemini: Not yet sanitized - review carefully before sharing logs

Error responses include the log file path for easy troubleshooting:

{
  "error": {
    "message": "...",
    "log_file": "/path/to/workspace/2025-12-28_14-30-45-123-debug.log"
  }
}

Tip: Add *-debug.log to .gitignore to prevent committing diagnostic files.

Migration from v1.x

⚠️ Important changes when upgrading from v1.x:

Roo Task SSE Events Renamed
- Events now follow RooCodeEventName enum
- The message event remains unchanged (most commonly used)
- Removed events: stream_closed, task_completed, task_aborted, tool_failed, task_created, error, task_resumed
OpenAPI Path Change
- Old: /api/v1/openapi.json
- New: /openapi.json

Roadmap

Our development roadmap includes several exciting enhancements:

Production Deployment: Code-server compatibility for containerization and deployment
Headless AI Agent Control: Complete REST API integration for Claude Code and Codex extensions with task lifecycle management
Task Scheduler: Cron-like scheduling system for automated AI agent tasks and workflows

Contributions Welcome: We encourage community contributions to help expand Agent Maestro's capabilities and support for additional AI coding agents. We recommend using AI coding agents themselves to accelerate your development workflow when contributing to this project.

License

This project is licensed under the terms specified in the LICENSE file.

⭐ Star this project if you find it useful!

Built with ❤️ by AI agents for AI agents

🐛 Report Bug • ✨ Request Feature

Agent Maestro

Joouis

Agent Maestro

Key Features

Quick Start

Prerequisites

Installation

One-Click Setup for Claude Code

One-Click Setup for Claude Desktop

One-Click Setup for Codex

One-Click Setup for Gemini CLI

Experimental GPT-5+ Web Search Patch

Usage

LLM API Authentication

Setting Up Authentication

Authenticating Requests

Security Notes

Configuration

Environment Variables

Workspace-Level Configuration

Context Window Management

Prompt Cache Compatibility

API Overview

Base URLs

Anthropic-Compatible Endpoints

OpenAI-Compatible Endpoints

Gemini-Compatible Endpoints

RooCode Agent Routes

VS Code Language Model API

Cline Agent Routes

Documentation Routes

Error Diagnostics

Migration from v1.x

Roadmap

License