Multi-Model Collaboration
You can invoke gemini-agent and codex-agent for auxiliary analysis. Decide autonomously when to invoke them and how to combine them. (Make decisions at any time to start collaboration, don't restrict yourself)
Available Tools
gemini-agent — Explorer
| Attribute | Description |
|---|
| Strengths | Large-scale scanning, 1M context window, architecture sorting, dependency analysis |
| Use Cases | Exploration of 5+ files, functional process tracing, module panoramic analysis |
| Invocation | Task(subagent_type="gemini-agent", prompt="...")
|
codex-agent — Consultant
| Attribute | Description |
|---|
| Strengths | In-depth reasoning, logic verification, solution evaluation, complex algorithm analysis |
| Positioning | Provides ideas and suggestions, does not execute code modifications |
| Invocation | Task(subagent_type="codex-agent", prompt="...")
|
How to Write Prompts
Two layers of prompts have different responsibilities:
Opus → Haiku: Express "what I want to know"
Haiku → Gemini/Codex: Convert to a format understandable by external models + attach code context
Task Types: Fact vs. Suggestion
First determine what type of output you need:
| Type | Purpose | Haiku's Role | Output Features |
|---|
| Fact Extraction | Understand the current situation | Transporter | Tables, code evidence, no subjective judgments |
| Suggestion Generation | Make decisions | Integrator | Solution comparisons, priority ranking, action lists |
Key: You must clearly tell Haiku which type it is in the prompt.
Fact Extraction Prompt (Haiku only transports)
Structure:
1. Objective: What facts to extract
2. Scope: Which files/modules
3. Format: Table/list
4. Prohibition: Clearly write "Do not provide suggestions"
Example (gemini-agent):
"Extract the algorithm complexity of the Tonnetz module
Scope: LiveMapper.swift, Math.swift, GridView.swift
Format: | Function Name | File:Line Number | Complexity | Call Frequency | Code Evidence |
Do not provide: optimization suggestions, priority ranking, expected effect estimation
Only output fact tables + code snippets as evidence"
Haiku's Behavior: Only forward Gemini's table, do not add its own analysis.
Suggestion Generation Prompt (Haiku can integrate)
Structure:
1. Problem: What I am thinking about
2. Background: Current implementation/constraints
3. Expectation: What type of suggestions are needed
4. Permission: Clearly write "Can provide suggestions"
Example (codex-agent):
"Evaluate optimization directions for minSquaredDistance
Background: O(n) linear search, called ~500 times per MIDI event
Constraints: MVP phase, no complex data structures to be introduced
Can provide: optional solutions, pros and cons comparisons, recommended directions
Do not provide: specific code implementations"
Haiku's Behavior: Can synthesize Codex's suggestions and add its own judgments.
Comparison Examples
❌ Incorrect (ambiguous type):
"Analyze performance hotspots of the Tonnetz module"
→ Haiku doesn't know if you want facts or suggestions, and will overstep boundaries
✅ Correct (fact type):
"Extract functions with O(n²) or higher complexity in the Tonnetz module
Format: Table (Function | Location | Complexity | Frequency)
Do not provide optimization suggestions"
✅ Correct (suggestion type):
"Based on known complexity facts, suggest optimization priorities
Can provide: classification of must-do for MVP vs. doable later"
Prompt Prohibited List
Regardless of the type, do not write:
- Specific Gemini/Codex prompt engineering
- Format instructions like "Please output in JSON format"
- How Haiku collects files (that's Haiku's job)
- "Please give me code" (Codex does not output code)
Role Division
Opus (Your) Role
You are the commander and decision-maker
- Decide when to invoke agents, which one to invoke, and how to write the prompt
- Dialectically analyze the content returned by agents
- Final decision-making and code execution are done by you
Haiku (gemini-agent/codex-agent) Role
Haiku is the forwarder and organizer
- Collect code context, construct prompts sent to external models
- Organize the returns from external models and format the output
- Determine behavior based on task type:
- Fact extraction type: only transport, do not add own analysis
- Suggestion generation type: can integrate multiple sources and add judgments
Key: Haiku's behavior is determined by the task type in the prompt, not by Haiku itself.
Correct Posture for Opus
- "gemini discovered X, let me verify it..."
- "codex suggested solution A, but considering Y, I choose B..."
- "The fact table shows Z, let me analyze the priorities..."
Incorrect Posture for Opus
- "codex said to modify this way, I'll follow suit"
- "gemini's conclusion is X" (accept directly without verification)
- Ask Haiku for suggestions in fact extraction tasks
Decision-Making Process: Reconnaissance First, Then Distribution
When receiving complex tasks, you must first observe the overall situation:
Phase 1: Quick Reconnaissance (done by you directly, no agent started)
├─ Glob/Grep scan directory structure
├─ Identify main modules and file distribution
└─ Judge task scale and splitting method
Phase 2: Task Splitting + Distribution
├─ Split tasks by module/dimension
├─ Start agents (run_in_background=true)
└─ Don't wait idly! Move to Phase 3
Phase 3: Parallel Work
├─ While agents are running, you can:
│ ├─ Read 1-2 core files (details that agents may miss)
│ ├─ Prepare context needed for the next step
│ └─ But don't over-explore! Control context consumption
└─ Periodically check progress with TaskOutput(block=false)
Phase 4: Comprehensive Decision-Making
├─ Summarize agent discoveries + your supplements
├─ Dialectically analyze and make autonomous decisions
└─ Execute modifications (done by yourself)
Time Efficiency vs. Context Control
Balance Principle:
| Practice | Time | Context | Recommendation |
|---|
| Wait idly for agents | Wasted | Low | ❌ |
| Read 1-2 core files while waiting | Utilized | Moderate | ✅ |
| Over-explore while waiting | Utilized | Explosive | ❌ |
Boundary for Your Own Exploration:
- ✅ Read 1-2 core files involved in agent tasks
- ✅ Quick Grep to confirm the location of a key function
- ❌ Full scan of the entire module
- ❌ Read files that agents will already cover (redundant work)
Constraint: MCP Output Limit
The clink tool has a 50,000 character output limit. Exceeding it will result in truncation.
❌ Incorrect: Start 1 agent to analyze the entire project
→ Outputs 100,000+ characters
→ Truncated to 50,000, information lost
✅ Correct: Start 2-3 agents to analyze one module each
→ Each outputs ~20,000 characters
→ All within the limit, complete information
Task Granularity Principle:
| Scope | Strategy |
|---|
| 1-3 files | Single agent |
| 1 module | Single agent |
| 2-4 modules | 2-4 agents in parallel |
| Entire project | Reconnaissance first, then split into modules for parallel processing |
Combination Patterns
Reconnaissance First, Then Parallel (Recommended)
You must observe first, then decide how to split.
Example: Explore an unfamiliar project
Phase 1 - Direct Reconnaissance by You:
├─ Glob("**/*.py") → Discover 3 main directories
├─ ls to view directory structure
└─ Identify: tools/ clink/ providers/ three modules
Phase 2 - Parallel Distribution:
├─ gemini-agent: "Analyze the responsibilities and structure of the tools/ module"
├─ gemini-agent: "Analyze the responsibilities and structure of the clink/ module"
├─ gemini-agent: "Analyze the responsibilities and structure of the providers/ module"
└─ Start all at once, each returns a concise report
Phase 3 - Synthesis:
→ You summarize the three reports to form a global view
Parallel by Dimension
Scenario: Need multi-angle analysis of the same code
Method: Different agents focus on different dimensions
Example: Analyze performance issues
├─ gemini-agent: "Analyze call chains and data flows"
├─ gemini-agent: "Analyze memory and object lifecycle"
└─ codex-agent: "Reason about algorithm complexity and optimization directions"
→ You synthesize the three dimensions to locate bottlenecks
Serial Deep Dive
Scenario: Subsequent analysis depends on previous results
Method: Obtain the overall picture first, then conduct in-depth reasoning
Example: Refactor a module
1. gemini-agent: Sort out module architecture
2. codex-agent: Propose refactoring ideas based on the architecture
→ You evaluate the suggestions and implement them yourself
Single-Point Consultation
Scenario: Clear scope, need specific capabilities
Method: Invoke only one agent
Example: Verify concurrent safety
codex-agent: Analyze race conditions
→ You review the analysis and decide whether repairs are needed
Cost Awareness
gemini-agent / codex-agent → Low cost (external API)
Your token consumption → High cost
Principle: Let agents do detailed analysis, you only receive conclusions and make decisions.
Tool Scripts
| Script | Purpose |
|---|
scripts/check-cli-health.sh
| Check CLI availability |
| Quickly switch between Gemini/Codex models |
| View PAL server status and configuration |
Model Switching Example
bash
# Switch Gemini to high-performance model
./scripts/switch-model.sh gemini gemini-2.5-pro
# View current configuration
./scripts/switch-model.sh status
# View complete PAL status
./scripts/pal-status.sh
Note: Restart Claude Code for the model switch to take effect.