name: proxy-mode-reference version: 1.0.0 description: Reference guide for using PROXY_MODE with external AI models. Use when running multi-model reviews, understanding which agents support PROXY_MODE, or debugging external model integration issues.

PROXY_MODE Reference Guide

What is PROXY_MODE?

PROXY_MODE is a directive that tells an agent to delegate its task to an external AI model via Claudish.

How It Works

1. Orchestrator launches Task with PROXY_MODE-enabled agent
2. Agent detects PROXY_MODE: {model} at start of prompt
3. Agent extracts model ID and actual task
4. Agent runs claudish --model {model} with the task
5. Agent returns external model's response

Multi-Backend Routing

Claudish routes to different backends based on model ID prefix:

⚠️ Prefix Collision Warning

OpenRouter model IDs may collide with routing prefixes. Check the prefix table above.

Collision-free models (safe for OpenRouter):

• x-ai/grok-* ✅
• deepseek/* ✅
• minimax/* ✅
• qwen/* ✅
• mistralai/* ✅
• moonshotai/* ✅
• anthropic/* ✅
• z-ai/* ✅
• google/* ✅ (only g/ and gemini/ route to Gemini Direct)

Models with prefix collisions:

• openai/gpt-* ❌ → Routes to OpenAI Direct (use oai/ or set OPENAI_API_KEY)

Workaround for collisions:

1. Use collision-free models (recommended)
2. Set up direct API key (GEMINI_API_KEY, OPENAI_API_KEY)
3. Use the short prefix form (g/, oai/) for direct API access

The PROXY_MODE Directive

Format:

PROXY_MODE: {model_id}

{actual task}

Example:

PROXY_MODE: x-ai/grok-code-fast-1

Review the architecture plan at ai-docs/plan.md

Supported Agents

Total: 18 PROXY_MODE-enabled agents across 3 plugins

agentdev plugin (3 agents)

frontend plugin (8 agents)

seo plugin (5 agents)

Common Mistakes

Mistake 1: Using general-purpose

// ❌ WRONG
Task({
  subagent_type: "general-purpose",
  prompt: "PROXY_MODE: grok..."
})

general-purpose doesn't have <proxy_mode_support> so it won't recognize the directive.

Mistake 2: Instructing agent to run claudish

// ❌ WRONG
Task({
  subagent_type: "general-purpose",
  prompt: "Run claudish with model X to review..."
})

The agent doesn't know the claudish pattern. Use PROXY_MODE instead.

Mistake 3: Wrong prompt format

// ❌ WRONG - PROXY_MODE must be first line
Task({
  subagent_type: "agentdev:reviewer",
  prompt: "Please review this plan.
PROXY_MODE: grok..."
})

The directive must be at the START of the prompt.

Correct Usage Pattern

// ✅ CORRECT
Task({
  subagent_type: "agentdev:reviewer",
  description: "Grok review",
  run_in_background: true,
  prompt: `PROXY_MODE: x-ai/grok-code-fast-1

Review the implementation at path/to/file.ts

Focus on:
1. Code quality
2. Error handling
3. Performance
4. Security`
})

Checking Agent Support

To verify if an agent supports PROXY_MODE:

# Find agents with PROXY_MODE support
grep -l "proxy_mode_support" plugins/*/agents/*.md

# Check specific agent
grep "proxy_mode_support" plugins/agentdev/agents/reviewer.md

Troubleshooting

"Agent didn't use external model"

Cause: Agent doesn't support PROXY_MODE Fix: Use a PROXY_MODE-enabled agent (see table above)

"Got Claude response instead of Grok response"

Cause: general-purpose or other non-PROXY_MODE agent was used Fix: Switch to agentdev:reviewer or similar

"PROXY_MODE directive in output"

Cause: Agent treated directive as content, not instruction Fix: Use correct agent; ensure directive is first line