torbjorn/my-pal-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improved docs

Browse Source
This commit is contained in:
Fahad
2025-06-17 12:20:52 +04:00
parent aec218a5ef
commit 863abf1a9f
15 changed files with 2151 additions and 391 deletions
Download Patch File Download Diff File Expand all files Collapse all files

467
README.md
View File

@@ -286,387 +286,133 @@ Just ask Claude naturally:
**Pro Tip:** Thinking modes (for Gemini models) control depth vs token cost. Use "minimal" or "low" for quick tasks, "high" or "max" for complex problems. [Learn more](docs/advanced-usage.md#thinking-modes)
**Tools Overview:**
1. [`chat`](#1-chat---general-development-chat--collaborative-thinking) - Collaborative thinking and development conversations
2. [`thinkdeep`](#2-thinkdeep---extended-reasoning-partner) - Extended reasoning and problem-solving
3. [`consensus`](#3-consensus---multi-model-perspective-gathering) - Multi-model consensus analysis with stance steering
4. [`codereview`](#4-codereview---professional-code-review) - Professional code review with severity levels
5. [`precommit`](#5-precommit---pre-commit-validation) - Validate git changes before committing
6. [`debug`](#6-debug---expert-debugging-assistant) - Root cause analysis and debugging
7. [`analyze`](#7-analyze---smart-file-analysis) - General-purpose file and code analysis
8. [`refactor`](#8-refactor---intelligent-code-refactoring) - Code refactoring with decomposition focus
9. [`tracer`](#9-tracer---static-code-analysis-prompt-generator) - Static code analysis prompt generator for call-flow mapping
10. [`testgen`](#10-testgen---comprehensive-test-generation) - Comprehensive test generation with edge case coverage
11. [`listmodels`](#11-listmodels---list-available-models) - Display all available AI models organized by provider
12. [`version`](#12-version---server-information) - Get server version and configuration
1. [`chat`](docs/tools/chat.md) - Collaborative thinking and development conversations
2. [`thinkdeep`](docs/tools/thinkdeep.md) - Extended reasoning and problem-solving
3. [`consensus`](docs/tools/consensus.md) - Multi-model consensus analysis with stance steering
4. [`codereview`](docs/tools/codereview.md) - Professional code review with severity levels
5. [`precommit`](docs/tools/precommit.md) - Validate git changes before committing
6. [`debug`](docs/tools/debug.md) - Root cause analysis and debugging
7. [`analyze`](docs/tools/analyze.md) - General-purpose file and code analysis
8. [`refactor`](docs/tools/refactor.md) - Code refactoring with decomposition focus
9. [`tracer`](docs/tools/tracer.md) - Static code analysis prompt generator for call-flow mapping
10. [`testgen`](docs/tools/testgen.md) - Comprehensive test generation with edge case coverage
11. [`listmodels`](docs/tools/listmodels.md) - Display all available AI models organized by provider
12. [`version`](docs/tools/version.md) - Get server version and configuration
### 1. `chat` - General Development Chat & Collaborative Thinking
**Your thinking partner - bounce ideas, get second opinions, brainstorm collaboratively**
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `low` for quick questions to save tokens, or `high` for complex discussions when thoroughness matters.
#### Example Prompt:
Your thinking partner for brainstorming, getting second opinions, and validating approaches. Perfect for technology comparisons, architecture discussions, and collaborative problem-solving.
```
Chat with zen and pick the best model for this job. I need to pick between Redis and Memcached for session storage
and I need an expert opinion for the project I'm working on. Get a good idea of what the project does, pick one of the two options
and then debate with the other models to give me a final verdict
Chat with zen about the best approach for user authentication in my React app
```
**Key Features:**
- Collaborative thinking partner for your analysis and planning
- Get second opinions on your designs and approaches
- Brainstorm solutions and explore alternatives together
- Validate your checklists and implementation plans
- General development questions and explanations
- Technology comparisons and best practices
- Architecture and design discussions
- Can reference files for context: `"Use gemini to explain this algorithm with context from algorithm.py"`
- **Image support**: Include screenshots, diagrams, UI mockups for visual analysis: `"Chat with gemini about this error dialog screenshot to understand the user experience issue"`
- **Dynamic collaboration**: Gemini can request additional files or context during the conversation if needed for a more thorough response
- **Web search capability**: Analyzes when web searches would be helpful and recommends specific searches for Claude to perform, ensuring access to current documentation and best practices
**[📖 Read More](docs/tools/chat.md)** - Detailed features, examples, and best practices
### 2. `thinkdeep` - Extended Reasoning Partner
**Get a second opinion to augment Claude's own extended thinking**
**Thinking Mode:** Default is `high` (16,384 tokens) for deep analysis. Claude will automatically choose the best mode based on complexity - use `low` for quick validations, `medium` for standard problems, `high` for complex issues (default), or `max` for extremely complex challenges requiring deepest analysis.
#### Example Prompt:
Get a second opinion to augment Claude's own extended thinking. Uses specialized thinking models to challenge assumptions, identify edge cases, and provide alternative perspectives.
```
Think deeper about my authentication design with pro using max thinking mode and brainstorm to come up
with the best architecture for my project
The button won't animate when clicked, it seems something else is intercepting the clicks. Use thinkdeep with gemini pro after gathering related code and handing it the files
and find out what the root cause is
```
**Key Features:**
- **Uses Gemini's specialized thinking models** for enhanced reasoning capabilities
- Provides a second opinion on Claude's analysis
- Challenges assumptions and identifies edge cases Claude might miss
- Offers alternative perspectives and approaches
- Validates architectural decisions and design patterns
- Can reference specific files for context: `"Use gemini to think deeper about my API design with reference to api/routes.py"`
- **Image support**: Analyze architectural diagrams, flowcharts, design mockups: `"Think deeper about this system architecture diagram with gemini pro using max thinking mode"`
- **Enhanced Critical Evaluation (v2.10.0)**: After Gemini's analysis, Claude is prompted to critically evaluate the suggestions, consider context and constraints, identify risks, and synthesize a final recommendation - ensuring a balanced, well-considered solution
- **Web search capability**: When enabled (default: true), identifies areas where current documentation or community solutions would strengthen the analysis and suggests specific searches for Claude
**[📖 Read More](docs/tools/thinkdeep.md)** - Enhanced analysis capabilities and critical evaluation process
### 3. `consensus` - Multi-Model Perspective Gathering
**Get diverse expert opinions from multiple AI models on technical proposals and decisions**
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `high` for complex architectural decisions or `max` for critical strategic choices requiring comprehensive analysis.
**Model Recommendation:** Consensus tool uses extended reasoning models by default, making it ideal for complex decision-making scenarios that benefit from multiple perspectives and deep analysis.
#### How It Works:
The consensus tool orchestrates multiple AI models to provide diverse perspectives on your proposals:
1. **Assign stances**: Each model can take a specific viewpoint (supportive, critical, or neutral)
2. **Gather opinions**: Models analyze your proposal from their assigned perspective with built-in common-sense guardrails
3. **Synthesize results**: Claude combines all perspectives into a balanced recommendation
4. **Natural language**: Use simple descriptions like "supportive", "critical", or "against" - the tool handles synonyms automatically
#### Example Prompts:
**For/Against Analysis:**
```
Use zen consensus with flash taking a supportive stance and pro being critical to evaluate whether
we should migrate from REST to GraphQL for our API
```
**Multi-Model Technical Decision:**
```
Get consensus from o3, flash, and pro on our new authentication architecture. Have o3 focus on
security implications, flash on implementation speed, and pro stay neutral for overall assessment
```
**Natural Language Stance Assignment:**
```
Use consensus tool with gemini being "for" the proposal and grok being "against" to debate
whether we should adopt microservices architecture
```
```
I want to work on module X and Y, unsure which is going to be more popular with users of my app.
Get a consensus from gemini supporting the idea for implementing X, grok opposing it, and flash staying neutral
```
**Key Features:**
- **Stance steering**: Assign specific perspectives (for/against/neutral) to each model with intelligent synonym handling
- **Custom stance prompts**: Provide specific instructions for how each model should approach the analysis
- **Ethical guardrails**: Models will refuse to support truly bad ideas regardless of assigned stance
- **Unknown stance handling**: Invalid stances automatically default to neutral with warning
- **Natural language support**: Use terms like "supportive", "critical", "oppose", "favor" - all handled intelligently
- **Sequential processing**: Reliable execution avoiding MCP protocol issues
- **Focus areas**: Specify particular aspects to emphasize (e.g., 'security', 'performance', 'user experience')
- **File context support**: Include relevant files for informed decision-making
- **Image support**: Analyze architectural diagrams, UI mockups, or design documents
- **Conversation continuation**: Build on previous consensus analysis with additional rounds
- **Web search capability**: Enhanced analysis with current best practices and documentation
**Parameters:**
- `prompt`: Detailed description of the proposal or decision to analyze
- `models`: List of model configurations with optional stance and custom instructions
- `files`: Context files for informed analysis (absolute paths)
- `images`: Visual references like diagrams or mockups
- `focus_areas`: Specific aspects to emphasize
- `temperature`: Control consistency (default: 0.2 for stable consensus)
- `thinking_mode`: Analysis depth (minimal/low/medium/high/max)
- `use_websearch`: Enable research for enhanced analysis (default: true)
- `continuation_id`: Continue previous consensus discussions
### 4. `codereview` - Professional Code Review
**Comprehensive code analysis with prioritized feedback**
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `high` for security-critical code (worth the extra tokens) or `low` for quick style checks (saves ~6k tokens).
**Model Recommendation:** This tool particularly benefits from Gemini Pro or Flash models due to their 1M context window,
which allows comprehensive analysis of large codebases. Claude's context limitations make it challenging to see the
"big picture" in complex projects - this is a concrete example where utilizing a secondary model with larger context
provides significant value beyond just experimenting with different AI capabilities.
#### Example Prompts:
Get diverse expert opinions from multiple AI models on technical proposals and decisions. Supports stance steering (for/against/neutral) and structured decision-making.
```
Perform a codereview with gemini pro and review auth.py for security issues and potential vulnerabilities.
I need an actionable plan but break it down into smaller quick-wins that we can implement and test rapidly
Get a consensus with flash taking a supportive stance and gemini pro being critical to evaluate whether we should
migrate from REST to GraphQL for our API. I need a definitive answer.
```
### Pro Tip
**[📖 Read More](docs/tools/consensus.md)** - Multi-model orchestration and decision analysis
**You can start more than _one_ codereview sessions with Claude**:
### 4. `codereview` - Professional Code Review
Comprehensive code analysis with prioritized feedback and severity levels. Supports security reviews, performance analysis, and coding standards enforcement.
```
Start separate sub-tasks for codereview one with o3 finding critical issues and one with flash finding low priority issues
and quick-wins and give me the final single combined review highlighting only the critical issues
Perform a codereview with gemini pro especially the auth.py as I feel some of the code is bypassing security checks
and there may be more potential vulnerabilities. Find and share related code."
```
The above prompt will simultaneously run two separate `codereview` tools with two separate models and combine the output
into a single summary for you to consume.
**Key Features:**
- Issues prioritized by severity (🔴 CRITICAL → 🟢 LOW)
- Supports specialized reviews: security, performance, quick
- Can enforce coding standards: `"Use gemini to review src/ against PEP8 standards"`
- Filters by severity: `"Get gemini to review auth/ - only report critical vulnerabilities"`
- **Image support**: Review code from screenshots, error dialogs, or visual bug reports: `"Review this error screenshot and the related auth.py file for potential security issues"`
**[📖 Read More](docs/tools/codereview.md)** - Professional review capabilities and parallel analysis
### 5. `precommit` - Pre-Commit Validation
**Comprehensive review of staged/unstaged git changes across multiple repositories**
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `high` or `max` for critical releases when thorough validation justifies the token cost.
**Model Recommendation:** Pre-commit validation benefits significantly from models with
extended context windows like Gemini Pro, which can analyze extensive changesets across
multiple files and repositories simultaneously. This comprehensive view enables detection of
cross-file dependencies, architectural inconsistencies, and integration issues that might be
missed when reviewing changes in isolation due to context constraints.
<div align="center">
<img src="https://github.com/user-attachments/assets/584adfa6-d252-49b4-b5b0-0cd6e97fb2c6" width="950">
</div>
**Prompt Used:**
```
Now use gemini and perform a review and precommit and ensure original requirements are met, no duplication of code or
logic, everything should work as expected
```
How beautiful is that? Claude used `precommit` twice and `codereview` once and actually found and fixed two critical errors before commit!
#### Example Prompts:
Comprehensive review of staged/unstaged git changes across multiple repositories. Validates changes against requirements and detects potential regressions.
```
Use zen and perform a thorough precommit ensuring there aren't any new regressions or bugs introduced
Perform a thorough precommit with o3, we want to only highlight critical issues, no blockers, no regressions. I need
100% confidence this covers all the edge cases listed in FIX_ISSUE_ABC.md
```
**Key Features:**
- **Recursive repository discovery** - finds all git repos including nested ones
- **Validates changes against requirements** - ensures implementation matches intent
- **Detects incomplete changes** - finds added functions never called, missing tests, etc.
- **Multi-repo support** - reviews changes across multiple repositories in one go
- **Configurable scope** - review staged, unstaged, or compare against branches
- **Security focused** - catches exposed secrets, vulnerabilities in new code
- **Smart truncation** - handles large diffs without exceeding context limits
**[📖 Read More](docs/tools/precommit.md)** - Multi-repository validation and change analysis
**Parameters:**
- `path`: Starting directory to search for repos (default: current directory)
- `original_request`: The requirements for context
- `compare_to`: Compare against a branch/tag instead of local changes
- `review_type`: full|security|performance|quick
- `severity_filter`: Filter by issue severity
- `max_depth`: How deep to search for nested repos
- `images`: Screenshots of requirements, design mockups, or error states for validation context
### 6. `debug` - Expert Debugging Assistant
**Root cause analysis for complex problems**
Root cause analysis for complex problems with systematic hypothesis generation. Supports error context, stack traces, and structured debugging approaches.
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `high` for tricky bugs (investment in finding root cause) or `low` for simple errors (save tokens).
#### Example Prompts:
**Basic Usage:**
```
"Use gemini to debug this TypeError: 'NoneType' object has no attribute 'split'"
"Get gemini to debug why my API returns 500 errors with the full stack trace: [paste traceback]"
See logs under /Users/me/project/diagnostics.log and related code under the sync folder. Logs show that sync
works but sometimes it gets stuck and there are no errors displayed to the user. Using zen's debug tool with gemini pro, find out
why this is happening and what the root cause is and its fix
```
**Key Features:**
- Generates multiple ranked hypotheses for systematic debugging
- Accepts error context, stack traces, and logs
- Can reference relevant files for investigation
- Supports runtime info and previous attempts
- Provides structured root cause analysis with validation steps
- Can request additional context when needed for thorough analysis
- **Image support**: Include error screenshots, stack traces, console output: `"Debug this error using gemini with the stack trace screenshot and the failing test.py"`
- **Web search capability**: When enabled (default: true), identifies when searching for error messages, known issues, or documentation would help solve the problem and recommends specific searches for Claude
**[📖 Read More](docs/tools/debug.md)** - Advanced debugging methodologies and troubleshooting
### 7. `analyze` - Smart File Analysis
**General-purpose code understanding and exploration**
General-purpose code understanding and exploration. Supports architecture analysis, pattern detection, and comprehensive codebase exploration.
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `high` for architecture analysis (comprehensive insights worth the cost) or `low` for quick file overviews (save ~6k tokens).
#### Example Prompts:
**Basic Usage:**
```
"Use gemini to analyze main.py to understand how it works"
"Get gemini to do an architecture analysis of the src/ directory"
Use gemini to analyze main.py to understand how it works
```
**Key Features:**
- Analyzes single files or entire directories
- Supports specialized analysis types: architecture, performance, security, quality
- Uses file paths (not content) for clean terminal output
- Can identify patterns, anti-patterns, and refactoring opportunities
- **Image support**: Analyze architecture diagrams, UML charts, flowcharts: `"Analyze this system diagram with gemini to understand the data flow and identify bottlenecks"`
- **Web search capability**: When enabled with `use_websearch` (default: true), the model can request Claude to perform web searches and share results back to enhance analysis with current documentation, design patterns, and best practices
**[📖 Read More](docs/tools/analyze.md)** - Code analysis types and exploration capabilities
### 8. `refactor` - Intelligent Code Refactoring
**Comprehensive refactoring analysis with top-down decomposition strategy**
**Thinking Mode:** Default is `medium` (8,192 tokens). Use `high` for complex legacy systems (worth the investment for thorough refactoring plans) or `max` for extremely complex codebases requiring deep analysis.
**Model Recommendation:** The refactor tool excels with models that have large context windows like Gemini
Pro (1M tokens), which can analyze entire files and complex codebases simultaneously.
This comprehensive view enables detection of cross-file dependencies, architectural patterns,
and refactoring opportunities that might be missed when reviewing code in smaller chunks due to context
constraints.
#### Example Prompts:
Comprehensive refactoring analysis with top-down decomposition strategy. Prioritizes structural improvements and provides precise implementation guidance.
```
"Use gemini pro to decompose my_crazy_big_class.m into smaller extensions"
"Using zen's refactor decompose the all_in_one_sync_code.swift into maintainable extensions"
Use gemini pro to decompose my_crazy_big_class.m into smaller extensions
```
💡Example of a **powerful prompt** to get the best out of both Claude + Flash's 1M Context:
```
"First, think about how the authentication module works, find related classes and find
any code smells, then using zen's refactor ask flash to confirm your findings but ask
it to find additional code smells and any other quick-wins and then fix these issues"
```
This results in Claude first performing its own expert analysis, encouraging it to think critically
and identify links within the project code. It then prompts `flash` to review the same code with a
hint—preventing it from duplicating Claude's findings and encouraging it to explore other areas that Claude
did *not* discover.
**Key Features:**
- **Intelligent prioritization** - Will refuse to work on low priority issues if code is unwieldy large and requires decomposition first, helps identify poorly managed classes and files that need structural improvements before detail work
- **Top-down decomposition strategy** - Analyzes file → class → function levels systematically
- **Four refactor types**: `codesmells` (detect anti-patterns), `decompose` (break down large components), `modernize` (update language features), `organization` (improve structure)
- **Precise line-number references** - Provides exact line numbers for Claude to implement changes
- **Language-specific guidance** - Tailored suggestions for Python, JavaScript, Java, C#, Swift, and more
- **Style guide integration** - Uses existing project files as pattern references
- **Conservative approach** - Careful dependency analysis to prevent breaking changes
- **Multi-file analysis** - Understands cross-file relationships and dependencies
- **Priority sequencing** - Recommends implementation order for refactoring changes
- **Image support**: Analyze code architecture diagrams, legacy system charts: `"Refactor this legacy module using gemini pro with the current architecture diagram"`
**Refactor Types (Progressive Priority System):**
**1. `decompose` (CRITICAL PRIORITY)** - Context-aware decomposition with adaptive thresholds:
- **AUTOMATIC decomposition** (CRITICAL severity - blocks all other refactoring):
- Files >15,000 LOC, Classes >3,000 LOC, Functions >500 LOC
- **EVALUATE decomposition** (contextual severity - intelligent assessment):
- Files >5,000 LOC, Classes >1,000 LOC, Functions >150 LOC
- Only recommends if genuinely improves maintainability
- Respects legacy stability, domain complexity, performance constraints
- Considers legitimate cases where size is justified (algorithms, state machines, generated code)
**2. `codesmells`** - Applied only after decomposition is complete:
- Detect long methods, complex conditionals, duplicate code, magic numbers, poor naming
**3. `modernize`** - Applied only after decomposition is complete:
- Update to modern language features (f-strings, async/await, etc.)
**4. `organization`** - Applied only after decomposition is complete:
- Improve logical grouping, separation of concerns, module structure
**Progressive Analysis:** The tool performs a top-down check (worse → bad → better) and refuses to work on lower-priority issues if critical decomposition is needed first. It understands that massive files and classes create cognitive overload that must be addressed before detail work can be effective. Legacy code that cannot be safely decomposed is handled with higher tolerance thresholds and context-sensitive exemptions.
**[📖 Read More](docs/tools/refactor.md)** - Refactoring strategy and progressive analysis approach
### 9. `tracer` - Static Code Analysis Prompt Generator
**Creates detailed analysis prompts for call-flow mapping and dependency tracing**
Creates detailed analysis prompts for call-flow mapping and dependency tracing. Generates structured analysis requests for precision execution flow or dependency mapping.
This is a specialized prompt-generation tool that creates structured analysis requests for Claude to perform comprehensive static code analysis.
Rather than passing entire projects to another model, this tool generates focused prompts that
Claude can use to efficiently trace execution flows and map dependencies within the codebase.
**Two Analysis Modes:**
- **`precision`**: For methods/functions - traces execution flow, call chains, and usage patterns with detailed branching analysis and side effects
- **`dependencies`**: For classes/modules/protocols - maps bidirectional dependencies and structural relationships
**Key Features:**
- Generates comprehensive analysis prompts instead of performing analysis directly
- Faster and more efficient than full project analysis by external models
- Creates structured instructions for call-flow graph generation
- Provides detailed formatting requirements for consistent output
- Supports any programming language with automatic convention detection
- Output can be used as an input into another tool, such as `chat` along with related code files to perform a logical call-flow analysis
- **Image support**: Analyze visual call flow diagrams, sequence diagrams: `"Generate tracer analysis for this payment flow using the sequence diagram"`
#### Example Prompts:
```
"Use zen tracer to analyze how UserAuthManager.authenticate is used and why" -> uses `precision` mode
"Use zen to generate a dependency trace for the PaymentProcessor class to understand its relationships" -> uses `dependencies` mode
Use zen tracer to analyze how UserAuthManager.authenticate is used and why
```
**[📖 Read More](docs/tools/tracer.md)** - Prompt generation and analysis modes
### 10. `testgen` - Comprehensive Test Generation
**Generates thorough test suites with edge case coverage** based on existing code and test framework used.
Generates thorough test suites with edge case coverage based on existing code and test framework. Uses multi-agent workflow for realistic failure mode analysis.
**Thinking Mode (Extended thinking models):** Default is `medium` (8,192 tokens). Use `high` for complex systems with many interactions or `max` for critical systems requiring exhaustive test coverage.
**Model Recommendation:** Test generation excels with extended reasoning models like Gemini Pro or O3,
which can analyze complex code paths, understand intricate dependencies, and identify comprehensive edge
cases. The combination of large context windows and advanced reasoning enables generation of thorough test
suites that cover realistic failure scenarios and integration points that shorter-context models might overlook.
#### Example Prompts:
**Basic Usage:**
```
"Use zen to generate tests for User.login() method"
"Generate comprehensive tests for the sorting method in src/new_sort.py using o3"
"Create tests for edge cases not already covered in our tests using gemini pro"
Use zen to generate tests for User.login() method
```
**Key Features:**
- Multi-agent workflow analyzing code paths and identifying realistic failure modes
- Generates framework-specific tests following project conventions
- Supports test pattern following when examples are provided
- Dynamic token allocation (25% for test examples, 75% for main code)
- Prioritizes smallest test files for pattern detection
- Can reference existing test files: `"Generate tests following patterns from tests/unit/"`
- Specific code coverage - target specific functions/classes rather than testing everything
- **Image support**: Test UI components, analyze visual requirements: `"Generate tests for this login form using the UI mockup screenshot"`
**[📖 Read More](docs/tools/testgen.md)** - Test generation strategy and framework support
### 11. `listmodels` - List Available Models
Display all available AI models organized by provider, showing capabilities, context windows, and configuration status.
```
"Use zen to list available models"
Use zen to list available models
```
Shows all configured providers, available models with aliases, and context windows.
**[📖 Read More](docs/tools/listmodels.md)** - Model capabilities and configuration details
### 12. `version` - Server Information
Get server version, configuration details, and system status for debugging and troubleshooting.
```
"Get zen to show its version"
What version of zen do I have
```
**[📖 Read More](docs/tools/version.md)** - Server diagnostics and configuration verification
For detailed tool parameters and configuration options, see the [Advanced Usage Guide](docs/advanced-usage.md).
### Prompt Support
@@ -715,92 +461,31 @@ Your custom tools get the same benefits as built-in tools: multi-model support,
### AI-to-AI Conversation Threading
This server enables **true AI collaboration** between Claude and multiple AI models (Gemini, O3), where they can coordinate and question each other's approaches:
This server enables **true AI collaboration** between Claude and multiple AI models, where they can coordinate and build on each other's insights across tools and conversations.
**How it works:**
- **Gemini can ask Claude follow-up questions** to clarify requirements or gather more context
- **Claude can respond** with additional information, files, or refined instructions
- **Claude can work independently** between exchanges - implementing solutions, gathering data, or performing analysis
- **Claude can return to Gemini** with progress updates and new context for further collaboration
- **Cross-tool continuation** - Start with one tool (e.g., `analyze`) and continue with another (e.g., `codereview`) using the same conversation thread
- **Both AIs coordinate their approaches** - questioning assumptions, validating solutions, and building on each other's insights
- Each conversation maintains full context while only sending incremental updates
- Conversations are automatically managed with Redis for persistence
**Example of Multi-Model AI Coordination:**
1. You: "Debate SwiftUI vs UIKit - which is better for iOS development?"
2. Claude (auto mode): "I'll orchestrate a debate between different models for diverse perspectives."
3. Gemini Pro: "From an architectural standpoint, SwiftUI's declarative paradigm and state management make it superior for maintainable, modern apps."
4. O3: "Logically analyzing the trade-offs: UIKit offers 15+ years of stability, complete control, and proven scalability. SwiftUI has <5 years maturity with ongoing breaking changes."
5. Claude: "Let me get Flash's quick take on developer experience..."
6. Gemini Flash: "SwiftUI = faster development, less code, better previews. UIKit = more control, better debugging, stable APIs."
7. **Claude's synthesis**: "Based on the multi-model analysis: Use SwiftUI for new projects prioritizing development speed, UIKit for apps requiring fine control or supporting older iOS versions."
**Asynchronous workflow example:**
- Claude can work independently between exchanges (analyzing code, implementing fixes, gathering data)
- Return to Gemini with progress updates and additional context
- Each exchange shares only incremental information while maintaining full conversation history
- Automatically bypasses MCP's 25K token limits through incremental updates
**Enhanced collaboration features:**
- **Cross-questioning**: AIs can challenge each other's assumptions and approaches
- **Coordinated problem-solving**: Each AI contributes their strengths to complex problems
- **Context building**: Claude gathers information while Gemini provides deep analysis
- **Approach validation**: AIs can verify and improve each other's solutions
- **Cross-tool continuation**: Seamlessly continue conversations across different tools while preserving all context
- **Asynchronous workflow**: Conversations don't need to be sequential - Claude can work on tasks between exchanges, then return to Gemini with additional context and progress updates
- **Incremental updates**: Share only new information in each exchange while maintaining full conversation history
- **Automatic 25K limit bypass**: Each exchange sends only incremental context, allowing unlimited total conversation size
- Up to 10 exchanges per conversation (configurable via `MAX_CONVERSATION_TURNS`) with 3-hour expiry (configurable via `CONVERSATION_TIMEOUT_HOURS`)
- Thread-safe with Redis persistence across all tools
- **Image context preservation** - Images and visual references are maintained across conversation turns and tool switches
**Cross-tool & Cross-Model Continuation Example:**
```
1. Claude: "Analyze /src/auth.py for security issues"
→ Auto mode: Claude picks Gemini Pro for deep security analysis
→ Pro analyzes and finds vulnerabilities, provides continuation_id
2. Claude: "Review the authentication logic thoroughly"
→ Uses same continuation_id, but Claude picks O3 for logical analysis
→ O3 sees previous Pro analysis and provides logic-focused review
3. Claude: "Debug the auth test failures"
→ Same continuation_id, Claude keeps O3 for debugging
→ O3 provides targeted debugging with full context from both previous analyses
4. Claude: "Quick style check before committing"
→ Same thread, but Claude switches to Flash for speed
→ Flash quickly validates formatting with awareness of all previous fixes
```
For more advanced features like working with large prompts and dynamic context requests, see the [Advanced Usage Guide](docs/advanced-usage.md).
**[📖 Read More](docs/ai-collaboration.md)** - Multi-model coordination, conversation threading, and collaborative workflows
## Configuration
**Auto Mode (Recommended):** Set `DEFAULT_MODEL=auto` in your .env file and Claude will intelligently select the best model for each task.
Configure the Zen MCP Server through environment variables in your `.env` file. Supports multiple AI providers, model restrictions, conversation settings, and advanced options.
```env
# .env file
DEFAULT_MODEL=auto # Claude picks the best model automatically
# API Keys (at least one required)
GEMINI_API_KEY=your-gemini-key # Enables Gemini Pro & Flash
OPENAI_API_KEY=your-openai-key # Enables O3, O3mini, O4-mini, O4-mini-high, GPT-4.1
# Quick start - Auto mode (recommended)
DEFAULT_MODEL=auto
GEMINI_API_KEY=your-gemini-key
OPENAI_API_KEY=your-openai-key
```
**Available Models:**
- **`pro`** (Gemini 2.5 Pro): Extended thinking, deep analysis
- **`flash`** (Gemini 2.0 Flash): Ultra-fast responses
- **`o3`**: Strong logical reasoning
- **`o3mini`**: Balanced speed/quality
- **`o4-mini`**: Latest reasoning model, optimized for shorter contexts
- **`o4-mini-high`**: Enhanced O4 with higher reasoning effort
- **`gpt4.1`**: GPT-4.1 with 1M context window
- **Custom models**: via OpenRouter or local APIs (Ollama, vLLM, etc.)
**Key Configuration Options:**
- **API Keys**: Native APIs (Gemini, OpenAI, X.AI), OpenRouter, or Custom endpoints (Ollama, vLLM)
- **Model Selection**: Auto mode or specific model defaults
- **Usage Restrictions**: Control which models can be used for cost control
- **Conversation Settings**: Timeout, turn limits, Redis configuration
- **Thinking Modes**: Token allocation for extended reasoning
- **Logging**: Debug levels and operational visibility
For detailed configuration options, see the [Advanced Usage Guide](docs/advanced-usage.md).
**[📖 Read More](docs/configuration.md)** - Complete configuration reference with examples
## Testing