Improved docs
This commit is contained in:
Fahad
165
docs/tools/analyze.md
Normal file
165
docs/tools/analyze.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Analyze Tool - Smart File Analysis
|
||||
|
||||
**General-purpose code understanding and exploration**
|
||||
|
||||
The `analyze` tool provides comprehensive code analysis and understanding capabilities, helping you explore codebases, understand architecture, and identify patterns across files and directories.
|
||||
|
||||
## 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"
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Analyzes single files or entire directories** with intelligent file filtering
|
||||
- **Supports specialized analysis types**: architecture, performance, security, quality, general
|
||||
- **Uses file paths (not content) for clean terminal output** while processing full content
|
||||
- **Can identify patterns, anti-patterns, and refactoring opportunities**
|
||||
- **Large codebase support**: Handle massive codebases with 1M token context models
|
||||
- **Cross-file relationship mapping**: Understand dependencies and interactions
|
||||
- **Architecture visualization**: Describe system structure and component relationships
|
||||
- **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
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `files`: Files or directories to analyze (required, absolute paths)
|
||||
- `prompt`: What to analyze or look for (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `analysis_type`: architecture|performance|security|quality|general (default: general)
|
||||
- `output_format`: summary|detailed|actionable (default: detailed)
|
||||
- `temperature`: Temperature for analysis (0-1, default 0.2)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
- `use_websearch`: Enable web search for documentation and best practices (default: true)
|
||||
- `continuation_id`: Continue previous analysis sessions
|
||||
|
||||
## Analysis Types
|
||||
|
||||
**General Analysis (default):**
|
||||
- Overall code structure and organization
|
||||
- Key components and their responsibilities
|
||||
- Data flow and control flow
|
||||
- Design patterns and architectural decisions
|
||||
|
||||
**Architecture Analysis:**
|
||||
- System-level design and component relationships
|
||||
- Module dependencies and coupling
|
||||
- Separation of concerns and layering
|
||||
- Scalability and maintainability considerations
|
||||
|
||||
**Performance Analysis:**
|
||||
- Potential bottlenecks and optimization opportunities
|
||||
- Algorithmic complexity assessment
|
||||
- Memory usage patterns
|
||||
- I/O and database interaction efficiency
|
||||
|
||||
**Security Analysis:**
|
||||
- Security patterns and potential vulnerabilities
|
||||
- Input validation and sanitization
|
||||
- Authentication and authorization mechanisms
|
||||
- Data protection and privacy considerations
|
||||
|
||||
**Quality Analysis:**
|
||||
- Code quality metrics and maintainability
|
||||
- Testing coverage and patterns
|
||||
- Documentation completeness
|
||||
- Best practices adherence
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Single File Analysis:**
|
||||
```
|
||||
"Analyze user_controller.py to understand the authentication flow with gemini"
|
||||
```
|
||||
|
||||
**Directory Architecture Analysis:**
|
||||
```
|
||||
"Use pro to analyze the src/ directory architecture and identify the main components"
|
||||
```
|
||||
|
||||
**Performance-Focused Analysis:**
|
||||
```
|
||||
"Analyze backend/api/ for performance bottlenecks with o3, focus on database queries"
|
||||
```
|
||||
|
||||
**Security Assessment:**
|
||||
```
|
||||
"Use gemini pro to analyze the authentication module for security patterns and potential issues"
|
||||
```
|
||||
|
||||
**Visual + Code Analysis:**
|
||||
```
|
||||
"Analyze this system architecture diagram along with the src/core/ implementation to understand the data flow"
|
||||
```
|
||||
|
||||
**Large Codebase Analysis:**
|
||||
```
|
||||
"Analyze the entire project structure with gemini pro to understand how all components work together"
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
**Summary Format:**
|
||||
- High-level overview with key findings
|
||||
- Main components and their purposes
|
||||
- Critical insights and recommendations
|
||||
|
||||
**Detailed Format (default):**
|
||||
- Comprehensive analysis with specific examples
|
||||
- Code snippets and file references
|
||||
- Detailed explanations of patterns and structures
|
||||
|
||||
**Actionable Format:**
|
||||
- Specific recommendations and next steps
|
||||
- Prioritized list of improvements
|
||||
- Implementation guidance and examples
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Be specific about goals**: Clearly state what you want to understand or discover
|
||||
- **Use appropriate analysis types**: Choose the type that matches your needs
|
||||
- **Include related files**: Analyze modules together for better context understanding
|
||||
- **Leverage large context models**: Use Gemini Pro for comprehensive codebase analysis
|
||||
- **Combine with visual context**: Include architecture diagrams or documentation
|
||||
- **Use continuation**: Build on previous analysis for deeper understanding
|
||||
|
||||
## Advanced Features
|
||||
|
||||
**Large Codebase Support:**
|
||||
With models like Gemini Pro (1M context), you can analyze extensive codebases:
|
||||
```
|
||||
"Analyze the entire microservices architecture across all service directories"
|
||||
```
|
||||
|
||||
**Cross-File Relationship Mapping:**
|
||||
Understand how components interact across multiple files:
|
||||
```
|
||||
"Analyze the data processing pipeline across input/, processing/, and output/ directories"
|
||||
```
|
||||
|
||||
**Pattern Recognition:**
|
||||
Identify design patterns, anti-patterns, and architectural decisions:
|
||||
```
|
||||
"Analyze src/ to identify all design patterns used and assess their implementation quality"
|
||||
```
|
||||
|
||||
**Web Search Enhancement:**
|
||||
The tool can recommend searches for current best practices and documentation:
|
||||
```
|
||||
After analysis: "Recommended searches for Claude: 'FastAPI async best practices 2024', 'SQLAlchemy ORM performance optimization patterns'"
|
||||
```
|
||||
|
||||
## When to Use Analyze vs Other Tools
|
||||
|
||||
- **Use `analyze`** for: Understanding code structure, exploring unfamiliar codebases, architecture assessment
|
||||
- **Use `codereview`** for: Finding bugs and security issues with actionable fixes
|
||||
- **Use `debug`** for: Diagnosing specific runtime errors or performance problems
|
||||
- **Use `refactor`** for: Getting specific refactoring recommendations and implementation plans
|
||||
- **Use `chat`** for: Open-ended discussions about code without structured analysis
|
||||
84
docs/tools/chat.md
Normal file
84
docs/tools/chat.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Chat Tool - General Development Chat & Collaborative Thinking
|
||||
|
||||
**Your thinking partner - bounce ideas, get second opinions, brainstorm collaboratively**
|
||||
|
||||
The `chat` tool is your collaborative thinking partner for development conversations. It's designed to help you brainstorm, validate ideas, get second opinions, and explore alternatives in a conversational format.
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## 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**
|
||||
- **File reference support**: `"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
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `prompt`: Your question or discussion topic (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `files`: Optional files for context (absolute paths)
|
||||
- `images`: Optional images for visual context (absolute paths)
|
||||
- `temperature`: Response creativity (0-1, default 0.5)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
- `use_websearch`: Enable web search for documentation and insights (default: true)
|
||||
- `continuation_id`: Continue previous conversations
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Basic Development Chat:**
|
||||
```
|
||||
"Chat with zen about the best approach for user authentication in my React app"
|
||||
```
|
||||
|
||||
**Technology Comparison:**
|
||||
```
|
||||
"Use flash to discuss whether PostgreSQL or MongoDB would be better for my e-commerce platform"
|
||||
```
|
||||
|
||||
**Architecture Discussion:**
|
||||
```
|
||||
"Chat with pro about microservices vs monolith architecture for my project, consider scalability and team size"
|
||||
```
|
||||
|
||||
**File Context Analysis:**
|
||||
```
|
||||
"Use gemini to chat about the current authentication implementation in auth.py and suggest improvements"
|
||||
```
|
||||
|
||||
**Visual Analysis:**
|
||||
```
|
||||
"Chat with gemini about this UI mockup screenshot - is the user flow intuitive?"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Be specific about context**: Include relevant files or describe your project scope
|
||||
- **Ask for trade-offs**: Request pros/cons for better decision-making
|
||||
- **Use conversation continuation**: Build on previous discussions with `continuation_id`
|
||||
- **Leverage visual context**: Include diagrams, mockups, or screenshots when discussing UI/UX
|
||||
- **Request web searches**: Ask for current best practices or recent developments in technologies
|
||||
|
||||
## When to Use Chat vs Other Tools
|
||||
|
||||
- **Use `chat`** for: Open-ended discussions, brainstorming, getting second opinions, technology comparisons
|
||||
- **Use `thinkdeep`** for: Extending specific analysis, challenging assumptions, deeper reasoning
|
||||
- **Use `analyze`** for: Understanding existing code structure and patterns
|
||||
- **Use `debug`** for: Specific error diagnosis and troubleshooting
|
||||
140
docs/tools/codereview.md
Normal file
140
docs/tools/codereview.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# CodeReview Tool - Professional Code Review
|
||||
|
||||
**Comprehensive code analysis with prioritized feedback**
|
||||
|
||||
The `codereview` tool provides professional code review capabilities with actionable feedback, severity-based issue prioritization, and support for various review types from quick style checks to comprehensive security audits.
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Pro Tip: Multiple Parallel Reviews
|
||||
|
||||
**You can start more than one codereview session with Claude:**
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
- **Coding standards enforcement**: `"Use gemini to review src/ against PEP8 standards"`
|
||||
- **Severity filtering**: `"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"`
|
||||
- **Multi-file analysis**: Comprehensive review of entire directories or codebases
|
||||
- **Actionable feedback**: Specific recommendations with line numbers and code examples
|
||||
- **Language-specific expertise**: Tailored analysis for Python, JavaScript, Java, C#, Swift, and more
|
||||
- **Integration issue detection**: Identifies cross-file dependencies and architectural problems
|
||||
- **Security vulnerability scanning**: Focused on common security patterns and anti-patterns
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `files`: List of file paths or directories to review (required)
|
||||
- `prompt`: User's summary of what the code does, expected behavior, constraints, and review objectives (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `review_type`: full|security|performance|quick (default: full)
|
||||
- `focus_on`: Specific aspects to focus on (e.g., "security vulnerabilities", "performance bottlenecks")
|
||||
- `standards`: Coding standards to enforce (e.g., "PEP8", "ESLint", "Google Style Guide")
|
||||
- `severity_filter`: critical|high|medium|low|all (default: all)
|
||||
- `temperature`: Temperature for consistency (0-1, default 0.2)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
- `use_websearch`: Enable web search for best practices and documentation (default: true)
|
||||
- `continuation_id`: Continue previous review discussions
|
||||
|
||||
## Review Types
|
||||
|
||||
**Full Review (default):**
|
||||
- Comprehensive analysis including bugs, security, performance, maintainability
|
||||
- Best for new features or significant code changes
|
||||
|
||||
**Security Review:**
|
||||
- Focused on security vulnerabilities and attack vectors
|
||||
- Checks for common security anti-patterns
|
||||
- Best for authentication, authorization, data handling code
|
||||
|
||||
**Performance Review:**
|
||||
- Analyzes performance bottlenecks and optimization opportunities
|
||||
- Memory usage, algorithmic complexity, resource management
|
||||
- Best for performance-critical code paths
|
||||
|
||||
**Quick Review:**
|
||||
- Fast style and basic issue check
|
||||
- Lower token usage for rapid feedback
|
||||
- Best for code formatting and simple validation
|
||||
|
||||
## Severity Levels
|
||||
|
||||
Issues are categorized and prioritized:
|
||||
|
||||
- **🔴 CRITICAL**: Security vulnerabilities, crashes, data corruption
|
||||
- **🟠 HIGH**: Logic errors, performance issues, reliability problems
|
||||
- **🟡 MEDIUM**: Code smells, maintainability issues, minor bugs
|
||||
- **🟢 LOW**: Style issues, documentation, minor improvements
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Basic Security Review:**
|
||||
```
|
||||
"Review the authentication module in auth/ for security vulnerabilities with gemini pro"
|
||||
```
|
||||
|
||||
**Performance-Focused Review:**
|
||||
```
|
||||
"Use o3 to review backend/api.py for performance issues, focus on database queries and caching"
|
||||
```
|
||||
|
||||
**Quick Style Check:**
|
||||
```
|
||||
"Quick review of utils.py with flash, only report critical and high severity issues"
|
||||
```
|
||||
|
||||
**Standards Enforcement:**
|
||||
```
|
||||
"Review src/ directory against PEP8 standards with gemini, focus on code formatting and structure"
|
||||
```
|
||||
|
||||
**Visual Context Review:**
|
||||
```
|
||||
"Review this authentication code along with the error dialog screenshot to understand the security implications"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Provide context**: Describe what the code is supposed to do and any constraints
|
||||
- **Use appropriate review types**: Security for auth code, performance for critical paths
|
||||
- **Set severity filters**: Focus on critical issues for quick wins
|
||||
- **Include relevant files**: Review related modules together for better context
|
||||
- **Use parallel reviews**: Run multiple reviews with different models for comprehensive coverage
|
||||
- **Follow up on findings**: Use the continuation feature to discuss specific issues in detail
|
||||
|
||||
## Output Format
|
||||
|
||||
Reviews include:
|
||||
- **Executive Summary**: Overview of code quality and main concerns
|
||||
- **Detailed Findings**: Specific issues with severity levels, line numbers, and recommendations
|
||||
- **Quick Wins**: Easy-to-implement improvements with high impact
|
||||
- **Long-term Improvements**: Structural changes for better maintainability
|
||||
- **Security Considerations**: Specific security recommendations when relevant
|
||||
|
||||
## When to Use CodeReview vs Other Tools
|
||||
|
||||
- **Use `codereview`** for: Finding bugs, security issues, performance problems, code quality assessment
|
||||
- **Use `analyze`** for: Understanding code structure without finding issues
|
||||
- **Use `debug`** for: Diagnosing specific runtime errors or exceptions
|
||||
- **Use `refactor`** for: Identifying structural improvements and modernization opportunities
|
||||
145
docs/tools/consensus.md
Normal file
145
docs/tools/consensus.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Consensus Tool - Multi-Model Perspective Gathering
|
||||
|
||||
**Get diverse expert opinions from multiple AI models on technical proposals and decisions**
|
||||
|
||||
The `consensus` tool orchestrates multiple AI models to provide diverse perspectives on your proposals, enabling structured decision-making through for/against analysis and multi-model expert opinions.
|
||||
|
||||
## 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
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `prompt`: Detailed description of the proposal or decision to analyze (required)
|
||||
- `models`: List of model configurations with optional stance and custom instructions (required)
|
||||
- `files`: Context files for informed analysis (absolute paths)
|
||||
- `images`: Visual references like diagrams or mockups (absolute paths)
|
||||
- `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
|
||||
|
||||
## Model Configuration Examples
|
||||
|
||||
**Basic For/Against:**
|
||||
```json
|
||||
[
|
||||
{"model": "flash", "stance": "for"},
|
||||
{"model": "pro", "stance": "against"}
|
||||
]
|
||||
```
|
||||
|
||||
**Custom Stance Instructions:**
|
||||
```json
|
||||
[
|
||||
{"model": "o3", "stance": "for", "stance_prompt": "Focus on implementation benefits and user value"},
|
||||
{"model": "flash", "stance": "against", "stance_prompt": "Identify potential risks and technical challenges"}
|
||||
]
|
||||
```
|
||||
|
||||
**Neutral Analysis:**
|
||||
```json
|
||||
[
|
||||
{"model": "pro", "stance": "neutral"},
|
||||
{"model": "o3", "stance": "neutral"}
|
||||
]
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Architecture Decision:**
|
||||
```
|
||||
"Get consensus from pro and o3 on whether to use microservices vs monolith for our e-commerce platform"
|
||||
```
|
||||
|
||||
**Technology Migration:**
|
||||
```
|
||||
"Use consensus with flash supporting and pro opposing to evaluate migrating from MySQL to PostgreSQL"
|
||||
```
|
||||
|
||||
**Feature Priority:**
|
||||
```
|
||||
"Get consensus from multiple models on whether to prioritize mobile app vs web dashboard development first"
|
||||
```
|
||||
|
||||
**With Visual Context:**
|
||||
```
|
||||
"Use consensus to evaluate this new UI design mockup - have flash support it and pro be critical"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Provide detailed context**: Include project constraints, requirements, and background
|
||||
- **Use balanced stances**: Mix supportive and critical perspectives for thorough analysis
|
||||
- **Specify focus areas**: Guide models to emphasize relevant aspects (security, performance, etc.)
|
||||
- **Include relevant files**: Provide code, documentation, or specifications for context
|
||||
- **Build on discussions**: Use continuation for follow-up analysis and refinement
|
||||
- **Leverage visual context**: Include diagrams, mockups, or design documents when relevant
|
||||
|
||||
## Ethical Guardrails
|
||||
|
||||
The consensus tool includes built-in ethical safeguards:
|
||||
- Models won't support genuinely harmful proposals regardless of assigned stance
|
||||
- Unknown or invalid stances automatically default to neutral
|
||||
- Warning messages for potentially problematic requests
|
||||
- Focus on constructive technical decision-making
|
||||
|
||||
## When to Use Consensus vs Other Tools
|
||||
|
||||
- **Use `consensus`** for: Multi-perspective analysis, structured debates, major technical decisions
|
||||
- **Use `chat`** for: Open-ended discussions and brainstorming
|
||||
- **Use `thinkdeep`** for: Extending specific analysis with deeper reasoning
|
||||
- **Use `analyze`** for: Understanding existing systems without debate
|
||||
168
docs/tools/debug.md
Normal file
168
docs/tools/debug.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Debug Tool - Expert Debugging Assistant
|
||||
|
||||
**Root cause analysis for complex problems**
|
||||
|
||||
The `debug` tool provides systematic debugging assistance with root cause analysis, hypothesis generation, and structured problem-solving approaches for complex technical issues.
|
||||
|
||||
## 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]"
|
||||
```
|
||||
|
||||
## 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
|
||||
- **Large context analysis**: Can analyze extensive log files and multiple related code files simultaneously
|
||||
- **Multi-language support**: Debug issues across Python, JavaScript, Java, C#, Swift, and more
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `prompt`: Error message, symptoms, or issue description (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `error_context`: Stack trace, logs, or additional error context
|
||||
- `files`: Files or directories that might be related to the issue (absolute paths)
|
||||
- `images`: Error screenshots, stack traces, console output (absolute paths)
|
||||
- `runtime_info`: Environment, versions, or runtime information
|
||||
- `previous_attempts`: What has been tried already
|
||||
- `temperature`: Temperature for accuracy (0-1, default 0.2)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
- `use_websearch`: Enable web search for error messages and solutions (default: true)
|
||||
- `continuation_id`: Continue previous debugging sessions
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Basic Error Debugging:**
|
||||
```
|
||||
"Debug this TypeError: 'NoneType' object has no attribute 'split' in my parser.py"
|
||||
```
|
||||
|
||||
**With Stack Trace:**
|
||||
```
|
||||
"Use gemini to debug why my API returns 500 errors with this stack trace: [paste full traceback]"
|
||||
```
|
||||
|
||||
**With File Context:**
|
||||
```
|
||||
"Debug the authentication failure in auth.py and user_model.py with o3"
|
||||
```
|
||||
|
||||
**Performance Debugging:**
|
||||
```
|
||||
"Use pro to debug why my application is consuming excessive memory during bulk operations"
|
||||
```
|
||||
|
||||
**With Visual Context:**
|
||||
```
|
||||
"Debug this crash using the error screenshot and the related crash_report.log"
|
||||
```
|
||||
|
||||
**Runtime Environment Issues:**
|
||||
```
|
||||
"Debug deployment issues with Docker container startup failures, here's the runtime info: [environment details]"
|
||||
```
|
||||
|
||||
## Debugging Methodology
|
||||
|
||||
The debug tool follows a systematic approach:
|
||||
|
||||
**1. Problem Analysis:**
|
||||
- Parse error messages and symptoms
|
||||
- Identify affected components and subsystems
|
||||
- Understand the expected vs actual behavior
|
||||
|
||||
**2. Hypothesis Generation:**
|
||||
- Generate multiple potential root causes
|
||||
- Rank hypotheses by likelihood and impact
|
||||
- Consider both obvious and subtle possibilities
|
||||
|
||||
**3. Investigation Strategy:**
|
||||
- Recommend specific files to examine
|
||||
- Suggest logging or debugging steps
|
||||
- Identify missing information needed
|
||||
|
||||
**4. Root Cause Analysis:**
|
||||
- Analyze evidence from code, logs, and context
|
||||
- Trace execution flow to identify failure points
|
||||
- Consider environmental and configuration factors
|
||||
|
||||
**5. Solution Recommendations:**
|
||||
- Provide specific fixes with code examples
|
||||
- Suggest preventive measures
|
||||
- Recommend testing strategies
|
||||
|
||||
## Debugging Categories
|
||||
|
||||
**Runtime Errors:**
|
||||
- Exceptions and crashes
|
||||
- Null pointer/reference errors
|
||||
- Type errors and casting issues
|
||||
- Memory leaks and resource exhaustion
|
||||
|
||||
**Logic Errors:**
|
||||
- Incorrect algorithm implementation
|
||||
- Off-by-one errors and boundary conditions
|
||||
- State management issues
|
||||
- Race conditions and concurrency bugs
|
||||
|
||||
**Integration Issues:**
|
||||
- API communication failures
|
||||
- Database connection problems
|
||||
- Third-party service integration
|
||||
- Configuration and environment issues
|
||||
|
||||
**Performance Problems:**
|
||||
- Slow response times
|
||||
- Memory usage spikes
|
||||
- CPU-intensive operations
|
||||
- I/O bottlenecks
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Provide complete error context**: Include full stack traces, error messages, and relevant logs
|
||||
- **Share relevant code**: Include files mentioned in stack traces or related to the issue
|
||||
- **Describe expected behavior**: Explain what should happen vs what's actually happening
|
||||
- **Include environment details**: Runtime versions, configuration, deployment context
|
||||
- **Mention previous attempts**: What debugging steps have already been tried
|
||||
- **Use visual context**: Screenshots of error dialogs, console output, or debugging tools
|
||||
- **Be specific about symptoms**: Describe when, where, and how the issue occurs
|
||||
|
||||
## Advanced Features
|
||||
|
||||
**Large Log Analysis:**
|
||||
With models like Gemini Pro (1M context), you can include extensive log files for comprehensive analysis:
|
||||
```
|
||||
"Debug application crashes using these large log files: app.log, error.log, system.log"
|
||||
```
|
||||
|
||||
**Multi-File Investigation:**
|
||||
Analyze multiple related files simultaneously to understand complex issues:
|
||||
```
|
||||
"Debug the data processing pipeline issues across processor.py, validator.py, and output_handler.py"
|
||||
```
|
||||
|
||||
**Web Search Integration:**
|
||||
The tool can recommend specific searches for error messages, known issues, or documentation:
|
||||
```
|
||||
After analysis: "Recommended searches for Claude: 'Django 4.2 migration error specific_error_code', 'PostgreSQL connection pool exhaustion solutions'"
|
||||
```
|
||||
|
||||
## When to Use Debug vs Other Tools
|
||||
|
||||
- **Use `debug`** for: Specific runtime errors, exceptions, crashes, performance issues
|
||||
- **Use `codereview`** for: Finding potential bugs in code without specific errors
|
||||
- **Use `analyze`** for: Understanding code structure and flow without troubleshooting
|
||||
- **Use `precommit`** for: Validating changes before commit to prevent introducing bugs
|
||||
105
docs/tools/listmodels.md
Normal file
105
docs/tools/listmodels.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# ListModels Tool - List Available Models
|
||||
|
||||
**Display all available AI models organized by provider**
|
||||
|
||||
The `listmodels` tool shows which providers are configured, available models, their aliases, context windows, and capabilities. This is useful for understanding what models can be used and their characteristics.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
"Use zen to list available models"
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Provider organization**: Shows all configured providers and their status
|
||||
- **Model capabilities**: Context windows, thinking mode support, and special features
|
||||
- **Alias mapping**: Shows shorthand names and their full model mappings
|
||||
- **Configuration status**: Indicates which providers are available based on API keys
|
||||
- **Context window information**: Helps you choose models based on your content size needs
|
||||
- **Capability overview**: Understanding which models support extended thinking, vision, etc.
|
||||
|
||||
## Output Information
|
||||
|
||||
The tool displays:
|
||||
|
||||
**Provider Status:**
|
||||
- Which providers are configured and available
|
||||
- API key status (without revealing the actual keys)
|
||||
- Provider priority order
|
||||
|
||||
**Model Details:**
|
||||
- Full model names and their aliases
|
||||
- Context window sizes (tokens)
|
||||
- Special capabilities (thinking modes, vision support, etc.)
|
||||
- Provider-specific features
|
||||
|
||||
**Capability Summary:**
|
||||
- Which models support extended thinking
|
||||
- Vision-capable models for image analysis
|
||||
- Models with largest context windows
|
||||
- Fastest models for quick tasks
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
📋 Available Models by Provider
|
||||
|
||||
🔹 Google (Gemini) - ✅ Configured
|
||||
• pro (gemini-2.5-pro-preview-06-05) - 1M context, thinking modes
|
||||
• flash (gemini-2.0-flash-experimental) - 1M context, ultra-fast
|
||||
|
||||
🔹 OpenAI - ✅ Configured
|
||||
• o3 (o3) - 200K context, strong reasoning
|
||||
• o3-mini (o3-mini) - 200K context, balanced
|
||||
• o4-mini (o4-mini) - 200K context, latest reasoning
|
||||
|
||||
🔹 Custom/Local - ✅ Configured
|
||||
• local-llama (llama3.2) - 128K context, local inference
|
||||
• Available at: http://host.docker.internal:11434/v1
|
||||
|
||||
🔹 OpenRouter - ❌ Not configured
|
||||
Set OPENROUTER_API_KEY to enable access to Claude, GPT-4, and more models
|
||||
```
|
||||
|
||||
## When to Use ListModels
|
||||
|
||||
- **Model selection**: When you're unsure which models are available
|
||||
- **Capability checking**: To verify what features each model supports
|
||||
- **Configuration validation**: To confirm your API keys are working
|
||||
- **Context planning**: To choose models based on content size requirements
|
||||
- **Performance optimization**: To select the right model for speed vs quality trade-offs
|
||||
|
||||
## Configuration Dependencies
|
||||
|
||||
The available models depend on your configuration:
|
||||
|
||||
**API Keys Required:**
|
||||
- `GEMINI_API_KEY` - Enables Gemini Pro and Flash models
|
||||
- `OPENAI_API_KEY` - Enables OpenAI O3, O4-mini, and GPT models
|
||||
- `OPENROUTER_API_KEY` - Enables access to multiple providers through OpenRouter
|
||||
- `CUSTOM_API_URL` - Enables local/custom models (Ollama, vLLM, etc.)
|
||||
|
||||
**Model Restrictions:**
|
||||
If you've set model usage restrictions via environment variables, the tool will show:
|
||||
- Which models are allowed vs restricted
|
||||
- Active restriction policies
|
||||
- How to modify restrictions
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
This tool requires no parameters - it simply queries the server configuration and displays all available information.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Check before planning**: Use this tool to understand your options before starting complex tasks
|
||||
- **Verify configuration**: Confirm your API keys are working as expected
|
||||
- **Choose appropriate models**: Match model capabilities to your specific needs
|
||||
- **Understand limits**: Be aware of context windows when working with large files
|
||||
|
||||
## When to Use ListModels vs Other Tools
|
||||
|
||||
- **Use `listmodels`** for: Understanding available options and model capabilities
|
||||
- **Use `chat`** for: General discussions about which model to use for specific tasks
|
||||
- **Use `version`** for: Server configuration and version information
|
||||
- **Use other tools** for: Actual analysis, debugging, or development work
|
||||
164
docs/tools/precommit.md
Normal file
164
docs/tools/precommit.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# PreCommit Tool - Pre-Commit Validation
|
||||
|
||||
**Comprehensive review of staged/unstaged git changes across multiple repositories**
|
||||
|
||||
The `precommit` tool provides thorough validation of git changes before committing, ensuring code quality, requirement compliance, and preventing regressions 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.
|
||||
|
||||
## Visual Example
|
||||
|
||||
<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
|
||||
|
||||
```
|
||||
Use zen and perform a thorough precommit ensuring there aren't any new regressions or bugs introduced
|
||||
```
|
||||
|
||||
## 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
|
||||
- **Cross-file dependency analysis** - identifies breaking changes across modules
|
||||
- **Test coverage validation** - ensures new code has appropriate test coverage
|
||||
- **Regression detection** - compares against requirements to prevent scope creep
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `path`: Starting directory to search for repos (default: current directory, absolute path required)
|
||||
- `prompt`: The original user request description for the changes (required for context)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `compare_to`: Compare against a branch/tag instead of local changes (optional)
|
||||
- `review_type`: full|security|performance|quick (default: full)
|
||||
- `severity_filter`: critical|high|medium|low|all (default: all)
|
||||
- `max_depth`: How deep to search for nested repos (default: 5)
|
||||
- `include_staged`: Include staged changes in the review (default: true)
|
||||
- `include_unstaged`: Include uncommitted changes in the review (default: true)
|
||||
- `images`: Screenshots of requirements, design mockups, or error states for validation context
|
||||
- `files`: Optional files for additional context (not part of changes but provide context)
|
||||
- `focus_on`: Specific aspects to focus on
|
||||
- `temperature`: Temperature for response (default: 0.2)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
- `use_websearch`: Enable web search for best practices (default: true)
|
||||
- `continuation_id`: Continue previous validation discussions
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Basic Pre-commit Validation:**
|
||||
```
|
||||
"Use zen precommit to validate my changes before committing"
|
||||
```
|
||||
|
||||
**Security-Focused Validation:**
|
||||
```
|
||||
"Perform precommit security review with gemini pro on the authentication changes"
|
||||
```
|
||||
|
||||
**Multi-Repository Validation:**
|
||||
```
|
||||
"Validate changes across all repositories in this workspace with o3"
|
||||
```
|
||||
|
||||
**Against Specific Branch:**
|
||||
```
|
||||
"Compare current changes against main branch with precommit using gemini pro"
|
||||
```
|
||||
|
||||
**With Requirements Context:**
|
||||
```
|
||||
"Precommit validation ensuring the new payment feature meets requirements in FEATURE_SPEC.md"
|
||||
```
|
||||
|
||||
## Validation Scope
|
||||
|
||||
The tool automatically discovers and validates:
|
||||
|
||||
**Repository Discovery:**
|
||||
- Searches recursively for all `.git` directories
|
||||
- Handles nested repositories and submodules
|
||||
- Configurable search depth to prevent excessive recursion
|
||||
|
||||
**Change Analysis:**
|
||||
- Staged changes (`git diff --cached`)
|
||||
- Unstaged changes (`git diff`)
|
||||
- Untracked files that should be added
|
||||
- Deleted files and their impact
|
||||
|
||||
**Cross-Repository Impact:**
|
||||
- Shared dependencies between repositories
|
||||
- API contract changes that affect other repos
|
||||
- Configuration changes with system-wide impact
|
||||
|
||||
## Validation Categories
|
||||
|
||||
**Completeness Checks:**
|
||||
- New functions/classes have corresponding tests
|
||||
- Documentation updated for API changes
|
||||
- Configuration files updated as needed
|
||||
- Migration scripts for database changes
|
||||
|
||||
**Quality Assurance:**
|
||||
- Code follows project standards
|
||||
- No obvious bugs or logical errors
|
||||
- Performance implications considered
|
||||
- Security vulnerabilities addressed
|
||||
|
||||
**Requirement Compliance:**
|
||||
- Implementation matches original requirements
|
||||
- No scope creep or unauthorized changes
|
||||
- All acceptance criteria met
|
||||
- Edge cases properly handled
|
||||
|
||||
**Integration Safety:**
|
||||
- Breaking changes properly documented
|
||||
- Backward compatibility maintained where required
|
||||
- Dependencies correctly updated
|
||||
- Environment-specific changes validated
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Provide clear context**: Include the original requirements or feature description
|
||||
- **Use for significant changes**: Most valuable for features, refactoring, or security updates
|
||||
- **Review before final commit**: Catch issues before they enter the main branch
|
||||
- **Include visual context**: Screenshots of requirements or expected behavior
|
||||
- **Focus validation scope**: Use `focus_on` parameter for specific concerns
|
||||
- **Multi-stage validation**: Use continuation for iterative improvement
|
||||
|
||||
## Output Format
|
||||
|
||||
Validation results include:
|
||||
- **Change Summary**: Overview of what was modified across repositories
|
||||
- **Requirement Compliance**: How well changes match original intent
|
||||
- **Completeness Assessment**: Missing tests, documentation, or related changes
|
||||
- **Security Review**: Potential vulnerabilities or exposed secrets
|
||||
- **Integration Impact**: Cross-repository and cross-module effects
|
||||
- **Recommendations**: Specific actions before committing
|
||||
|
||||
## When to Use PreCommit vs Other Tools
|
||||
|
||||
- **Use `precommit`** for: Validating changes before git commit, ensuring requirement compliance
|
||||
- **Use `codereview`** for: General code quality assessment without git context
|
||||
- **Use `debug`** for: Diagnosing specific runtime issues
|
||||
- **Use `analyze`** for: Understanding existing code without validation context
|
||||
167
docs/tools/refactor.md
Normal file
167
docs/tools/refactor.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Refactor Tool - Intelligent Code Refactoring
|
||||
|
||||
**Comprehensive refactoring analysis with top-down decomposition strategy**
|
||||
|
||||
The `refactor` tool provides intelligent code refactoring recommendations with a focus on top-down decomposition and systematic code improvement. It prioritizes structural improvements over cosmetic changes.
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
"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"
|
||||
```
|
||||
|
||||
💡**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.
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `files`: Code files or directories to analyze for refactoring opportunities (required, absolute paths)
|
||||
- `prompt`: Description of refactoring goals, context, and specific areas of focus (required)
|
||||
- `refactor_type`: codesmells|decompose|modernize|organization (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `focus_areas`: Specific areas to focus on (e.g., 'performance', 'readability', 'maintainability', 'security')
|
||||
- `style_guide_examples`: Optional existing code files to use as style/pattern reference (absolute paths)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
- `continuation_id`: Thread continuation ID for multi-turn conversations
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Decomposition Analysis:**
|
||||
```
|
||||
"Analyze UserController.java for decomposition opportunities - it's becoming unwieldy"
|
||||
```
|
||||
|
||||
**Code Smell Detection:**
|
||||
```
|
||||
"Use gemini to identify code smells in the authentication module with high thinking mode"
|
||||
```
|
||||
|
||||
**Modernization:**
|
||||
```
|
||||
"Modernize legacy_parser.py to use modern Python features following examples/modern_patterns.py"
|
||||
```
|
||||
|
||||
**Organization Improvement:**
|
||||
```
|
||||
"Refactor src/utils/ for better organization, focus on maintainability and readability"
|
||||
```
|
||||
|
||||
**Legacy System Refactoring:**
|
||||
```
|
||||
"Use pro with max thinking to analyze this 10,000-line legacy file for decomposition strategy"
|
||||
```
|
||||
|
||||
## Refactoring Strategy
|
||||
|
||||
**Top-Down Analysis:**
|
||||
1. **File Level**: Identify oversized files that need splitting
|
||||
2. **Class Level**: Find classes with too many responsibilities
|
||||
3. **Function Level**: Locate functions that are too complex or long
|
||||
4. **Code Quality**: Address smells, modernization, and organization
|
||||
|
||||
**Context-Aware Decisions:**
|
||||
- **Domain Complexity**: Some domains legitimately require larger classes
|
||||
- **Performance Constraints**: Critical path code may resist decomposition
|
||||
- **Legacy Stability**: Old, working code may need gentler refactoring
|
||||
- **Test Coverage**: Refactoring recommendations consider testability
|
||||
|
||||
**Breaking Change Prevention:**
|
||||
- Analyzes dependencies before suggesting splits
|
||||
- Recommends gradual migration strategies
|
||||
- Identifies public API impact
|
||||
- Suggests backward compatibility approaches
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start with decomposition**: Address structural issues before cosmetic improvements
|
||||
- **Provide clear context**: Explain the codebase purpose and constraints
|
||||
- **Use appropriate refactor types**: Match the type to your primary concern
|
||||
- **Include style examples**: Reference existing well-structured code in your project
|
||||
- **Focus on high-impact areas**: Target the most problematic or frequently modified code
|
||||
- **Plan implementation order**: Follow the tool's sequencing recommendations
|
||||
- **Consider test coverage**: Ensure adequate tests before major structural changes
|
||||
|
||||
## Output Format
|
||||
|
||||
Refactoring analysis includes:
|
||||
- **Priority Assessment**: What needs attention first and why
|
||||
- **Decomposition Strategy**: Specific file/class/function splitting recommendations
|
||||
- **Implementation Plan**: Step-by-step refactoring sequence
|
||||
- **Line-Number References**: Exact locations for changes
|
||||
- **Dependency Analysis**: Impact assessment and migration strategies
|
||||
- **Risk Assessment**: Potential breaking changes and mitigation strategies
|
||||
|
||||
## Advanced Features
|
||||
|
||||
**Adaptive Thresholds:**
|
||||
The tool adjusts size thresholds based on context:
|
||||
- **Generated Code**: Higher tolerance for large files
|
||||
- **Algorithm Implementation**: Recognizes when size is justified
|
||||
- **Legacy Systems**: More conservative recommendations
|
||||
- **Test Files**: Different standards for test vs production code
|
||||
|
||||
**Cross-File Refactoring:**
|
||||
Analyzes multiple files together to understand:
|
||||
- Shared responsibilities that could be extracted
|
||||
- Dependencies that complicate refactoring
|
||||
- Opportunities for new abstractions
|
||||
- Impact of changes across the codebase
|
||||
|
||||
## When to Use Refactor vs Other Tools
|
||||
|
||||
- **Use `refactor`** for: Structural improvements, decomposition, modernization, code organization
|
||||
- **Use `codereview`** for: Finding bugs and security issues with immediate fixes
|
||||
- **Use `analyze`** for: Understanding code without making change recommendations
|
||||
- **Use `debug`** for: Solving specific runtime issues rather than structural problems
|
||||
188
docs/tools/testgen.md
Normal file
188
docs/tools/testgen.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# TestGen Tool - Comprehensive Test Generation
|
||||
|
||||
**Generates thorough test suites with edge case coverage based on existing code and test framework used**
|
||||
|
||||
The `testgen` tool creates comprehensive test suites by analyzing your code paths, understanding intricate dependencies, and identifying realistic edge cases and failure scenarios that need test coverage.
|
||||
|
||||
## Thinking Mode
|
||||
|
||||
**Default is `medium` (8,192 tokens) for extended thinking models.** 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"
|
||||
```
|
||||
|
||||
## 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"`
|
||||
- **Edge case identification**: Systematic discovery of boundary conditions and error states
|
||||
- **Realistic failure mode analysis**: Understanding what can actually go wrong in production
|
||||
- **Integration test support**: Tests that cover component interactions and system boundaries
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `files`: Code files or directories to generate tests for (required, absolute paths)
|
||||
- `prompt`: Description of what to test, testing objectives, and specific scope/focus areas (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `test_examples`: Optional existing test files or directories to use as style/pattern reference (absolute paths)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Method-Specific Tests:**
|
||||
```
|
||||
"Generate tests for User.login() method covering authentication success, failure, and edge cases"
|
||||
```
|
||||
|
||||
**Class Testing:**
|
||||
```
|
||||
"Use pro to generate comprehensive tests for PaymentProcessor class with max thinking mode"
|
||||
```
|
||||
|
||||
**Following Existing Patterns:**
|
||||
```
|
||||
"Generate tests for new authentication module following patterns from tests/unit/auth/"
|
||||
```
|
||||
|
||||
**UI Component Testing:**
|
||||
```
|
||||
"Generate tests for this login form component using the UI mockup screenshot"
|
||||
```
|
||||
|
||||
**Algorithm Testing:**
|
||||
```
|
||||
"Create thorough tests for the sorting algorithm in utils/sort.py, focus on edge cases and performance"
|
||||
```
|
||||
|
||||
**Integration Testing:**
|
||||
```
|
||||
"Generate integration tests for the payment processing pipeline from order creation to completion"
|
||||
```
|
||||
|
||||
## Test Generation Strategy
|
||||
|
||||
**Code Path Analysis:**
|
||||
- Identifies all execution paths through the code
|
||||
- Maps conditional branches and loops
|
||||
- Discovers error handling paths
|
||||
- Analyzes state transitions
|
||||
|
||||
**Edge Case Discovery:**
|
||||
- Boundary value analysis (empty, null, max values)
|
||||
- Invalid input scenarios
|
||||
- Race conditions and timing issues
|
||||
- Resource exhaustion cases
|
||||
|
||||
**Failure Mode Analysis:**
|
||||
- External dependency failures
|
||||
- Network and I/O errors
|
||||
- Authentication and authorization failures
|
||||
- Data corruption scenarios
|
||||
|
||||
**Framework Detection:**
|
||||
The tool automatically detects and generates tests for:
|
||||
- **Python**: pytest, unittest, nose2
|
||||
- **JavaScript**: Jest, Mocha, Jasmine, Vitest
|
||||
- **Java**: JUnit 4/5, TestNG, Mockito
|
||||
- **C#**: NUnit, MSTest, xUnit
|
||||
- **Swift**: XCTest
|
||||
- **Go**: testing package
|
||||
- **And more**: Adapts to project conventions
|
||||
|
||||
## Test Categories Generated
|
||||
|
||||
**Unit Tests:**
|
||||
- Function/method behavior validation
|
||||
- Input/output verification
|
||||
- Error condition handling
|
||||
- State change verification
|
||||
|
||||
**Integration Tests:**
|
||||
- Component interaction testing
|
||||
- API endpoint validation
|
||||
- Database integration
|
||||
- External service mocking
|
||||
|
||||
**Edge Case Tests:**
|
||||
- Boundary conditions
|
||||
- Invalid inputs
|
||||
- Resource limits
|
||||
- Concurrent access
|
||||
|
||||
**Performance Tests:**
|
||||
- Response time validation
|
||||
- Memory usage checks
|
||||
- Load handling
|
||||
- Scalability verification
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Be specific about scope**: Target specific functions/classes rather than requesting tests for everything
|
||||
- **Provide test examples**: Include existing test files for pattern consistency
|
||||
- **Focus on critical paths**: Prioritize testing of business-critical functionality
|
||||
- **Include visual context**: Screenshots or mockups for UI component testing
|
||||
- **Describe testing objectives**: Explain what aspects are most important to test
|
||||
- **Consider test maintenance**: Request readable, maintainable test code
|
||||
|
||||
## Test Quality Features
|
||||
|
||||
**Realistic Test Data:**
|
||||
- Generates meaningful test data that represents real-world scenarios
|
||||
- Avoids trivial test cases that don't add value
|
||||
- Creates data that exercises actual business logic
|
||||
|
||||
**Comprehensive Coverage:**
|
||||
- Happy path scenarios
|
||||
- Error conditions and exceptions
|
||||
- Edge cases and boundary conditions
|
||||
- Integration points and dependencies
|
||||
|
||||
**Maintainable Code:**
|
||||
- Clear test names that describe what's being tested
|
||||
- Well-organized test structure
|
||||
- Appropriate use of setup/teardown
|
||||
- Minimal test data and mocking
|
||||
|
||||
## Advanced Features
|
||||
|
||||
**Pattern Following:**
|
||||
When test examples are provided, the tool analyzes:
|
||||
- Naming conventions and structure
|
||||
- Assertion patterns and style
|
||||
- Mocking and setup approaches
|
||||
- Test data organization
|
||||
|
||||
**Large Context Analysis:**
|
||||
With models like Gemini Pro, the tool can:
|
||||
- Analyze extensive codebases for comprehensive test coverage
|
||||
- Understand complex interactions across multiple modules
|
||||
- Generate integration tests that span multiple components
|
||||
|
||||
**Visual Testing:**
|
||||
For UI components and visual elements:
|
||||
- Generate tests based on visual requirements
|
||||
- Create accessibility testing scenarios
|
||||
- Test responsive design behaviors
|
||||
|
||||
## When to Use TestGen vs Other Tools
|
||||
|
||||
- **Use `testgen`** for: Creating comprehensive test suites, filling test coverage gaps, testing new features
|
||||
- **Use `debug`** for: Diagnosing specific test failures or runtime issues
|
||||
- **Use `codereview`** for: Reviewing existing test quality and coverage
|
||||
- **Use `analyze`** for: Understanding existing test structure without generating new tests
|
||||
97
docs/tools/thinkdeep.md
Normal file
97
docs/tools/thinkdeep.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# ThinkDeep Tool - Extended Reasoning Partner
|
||||
|
||||
**Get a second opinion to augment Claude's own extended thinking**
|
||||
|
||||
The `thinkdeep` tool provides extended reasoning capabilities, offering a second perspective to augment Claude's analysis. It's designed to challenge assumptions, find edge cases, and provide alternative approaches to complex problems.
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
Think deeper about my authentication design with pro using max thinking mode and brainstorm to come up
|
||||
with the best architecture for my project
|
||||
```
|
||||
|
||||
## 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
|
||||
- **File reference support**: `"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
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `prompt`: Your current thinking/analysis to extend and validate (required)
|
||||
- `model`: auto|pro|flash|o3|o3-mini|o4-mini|o4-mini-high|gpt4.1 (default: server default)
|
||||
- `problem_context`: Additional context about the problem or goal
|
||||
- `focus_areas`: Specific aspects to focus on (architecture, performance, security, etc.)
|
||||
- `files`: Optional file paths or directories for additional context (absolute paths)
|
||||
- `images`: Optional images for visual analysis (absolute paths)
|
||||
- `temperature`: Temperature for creative thinking (0-1, default 0.7)
|
||||
- `thinking_mode`: minimal|low|medium|high|max (default: high, Gemini only)
|
||||
- `use_websearch`: Enable web search for documentation and insights (default: true)
|
||||
- `continuation_id`: Continue previous conversations
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Architecture Design:**
|
||||
```
|
||||
"Think deeper about my microservices authentication strategy with pro using max thinking mode"
|
||||
```
|
||||
|
||||
**With File Context:**
|
||||
```
|
||||
"Use gemini to think deeper about my API design with reference to api/routes.py and models/user.py"
|
||||
```
|
||||
|
||||
**Visual Analysis:**
|
||||
```
|
||||
"Think deeper about this system architecture diagram with gemini pro - identify potential bottlenecks"
|
||||
```
|
||||
|
||||
**Problem Solving:**
|
||||
```
|
||||
"I'm considering using GraphQL vs REST for my API. Think deeper about the trade-offs with o3 using high thinking mode"
|
||||
```
|
||||
|
||||
**Code Review Enhancement:**
|
||||
```
|
||||
"Think deeper about the security implications of this authentication code with pro"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Provide detailed context**: Share your current thinking, constraints, and objectives
|
||||
- **Be specific about focus areas**: Mention what aspects need deeper analysis
|
||||
- **Include relevant files**: Reference code, documentation, or configuration files
|
||||
- **Use appropriate thinking modes**: Higher modes for complex problems, lower for quick validations
|
||||
- **Leverage visual context**: Include diagrams or mockups for architectural discussions
|
||||
- **Build on discussions**: Use continuation to extend previous analyses
|
||||
|
||||
## Enhanced Critical Evaluation Process
|
||||
|
||||
The `thinkdeep` tool includes a unique two-stage process:
|
||||
|
||||
1. **Gemini's Analysis**: Extended reasoning with specialized thinking capabilities
|
||||
2. **Claude's Critical Evaluation**: Claude reviews Gemini's suggestions, considers:
|
||||
- Context and constraints of your specific situation
|
||||
- Potential risks and implementation challenges
|
||||
- Trade-offs and alternatives
|
||||
- Final synthesized recommendation
|
||||
|
||||
This ensures you get both deep reasoning and practical, context-aware advice.
|
||||
|
||||
## When to Use ThinkDeep vs Other Tools
|
||||
|
||||
- **Use `thinkdeep`** for: Extending specific analysis, challenging assumptions, architectural decisions
|
||||
- **Use `chat`** for: Open-ended brainstorming and general discussions
|
||||
- **Use `analyze`** for: Understanding existing code without extending analysis
|
||||
- **Use `codereview`** for: Finding specific bugs and security issues
|
||||
170
docs/tools/tracer.md
Normal file
170
docs/tools/tracer.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Tracer Tool - Static Code Analysis Prompt Generator
|
||||
|
||||
**Creates detailed analysis prompts for call-flow mapping and dependency tracing**
|
||||
|
||||
The `tracer` tool 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` Mode**: For methods/functions
|
||||
- Traces execution flow, call chains, and usage patterns
|
||||
- Detailed branching analysis and side effects
|
||||
- Shows when and how functions are called throughout the system
|
||||
|
||||
**`dependencies` Mode**: For classes/modules/protocols
|
||||
- Maps bidirectional dependencies and structural relationships
|
||||
- Identifies coupling and architectural dependencies
|
||||
- Shows how components interact and depend on each other
|
||||
|
||||
## 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 input** into another tool, such as `chat` along with related code files to perform logical call-flow analysis
|
||||
- **Image support**: Analyze visual call flow diagrams, sequence diagrams: `"Generate tracer analysis for this payment flow using the sequence diagram"`
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
- `prompt`: Detailed description of what to trace and WHY you need this analysis (required)
|
||||
- `trace_mode`: precision|dependencies (required)
|
||||
- `images`: Optional images of system architecture diagrams, flow charts, or visual references (absolute paths)
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Method Execution Tracing:**
|
||||
```
|
||||
"Use zen tracer to analyze how UserAuthManager.authenticate is used and why"
|
||||
```
|
||||
→ Uses `precision` mode to trace the method's execution flow
|
||||
|
||||
**Class Dependency Mapping:**
|
||||
```
|
||||
"Use zen to generate a dependency trace for the PaymentProcessor class to understand its relationships"
|
||||
```
|
||||
→ Uses `dependencies` mode to map structural relationships
|
||||
|
||||
**With Visual Context:**
|
||||
```
|
||||
"Generate tracer analysis for the authentication flow using this sequence diagram"
|
||||
```
|
||||
|
||||
**Complex System Analysis:**
|
||||
```
|
||||
"Create a tracer prompt to understand how the OrderProcessor.processPayment method flows through the entire system"
|
||||
```
|
||||
|
||||
## Precision Mode Output
|
||||
|
||||
When using `precision` mode for methods/functions, the tool generates prompts that will help Claude create:
|
||||
|
||||
**Call Chain Analysis:**
|
||||
- Where the method is defined
|
||||
- All locations where it's called
|
||||
- Direct and indirect callers
|
||||
- Call hierarchy and depth
|
||||
|
||||
**Execution Flow Mapping:**
|
||||
- Step-by-step execution path
|
||||
- Branching conditions and logic
|
||||
- Side effects and state changes
|
||||
- Return value usage
|
||||
|
||||
**Usage Pattern Analysis:**
|
||||
- Frequency and context of calls
|
||||
- Parameter passing patterns
|
||||
- Error handling approaches
|
||||
- Performance implications
|
||||
|
||||
## Dependencies Mode Output
|
||||
|
||||
When using `dependencies` mode for classes/modules, the tool generates prompts that will help Claude create:
|
||||
|
||||
**Structural Relationships:**
|
||||
- Inheritance hierarchies
|
||||
- Composition and aggregation
|
||||
- Interface implementations
|
||||
- Module imports and exports
|
||||
|
||||
**Bidirectional Dependencies:**
|
||||
- What the component depends on
|
||||
- What depends on the component
|
||||
- Circular dependencies
|
||||
- Coupling strength analysis
|
||||
|
||||
**Architectural Impact:**
|
||||
- Layer violations
|
||||
- Dependency inversion opportunities
|
||||
- Refactoring impact assessment
|
||||
- Testability implications
|
||||
|
||||
## Example Generated Prompts
|
||||
|
||||
**For Precision Mode:**
|
||||
```
|
||||
Analyze the execution flow and usage of the `authenticate` method in UserAuthManager:
|
||||
|
||||
1. **Method Location**: Find where UserAuthManager.authenticate is defined
|
||||
2. **Call Sites**: Identify all locations where this method is called
|
||||
3. **Execution Flow**: Trace the step-by-step execution path
|
||||
4. **Side Effects**: Document state changes and external interactions
|
||||
5. **Return Handling**: Show how return values are used by callers
|
||||
|
||||
Format the analysis as:
|
||||
- Method signature and location
|
||||
- Call hierarchy (direct and indirect callers)
|
||||
- Execution flow diagram
|
||||
- Side effects and dependencies
|
||||
- Usage patterns and frequency
|
||||
```
|
||||
|
||||
**For Dependencies Mode:**
|
||||
```
|
||||
Map the structural dependencies for PaymentProcessor class:
|
||||
|
||||
1. **Direct Dependencies**: What PaymentProcessor directly imports/uses
|
||||
2. **Reverse Dependencies**: What classes/modules depend on PaymentProcessor
|
||||
3. **Inheritance Relationships**: Parent classes and implemented interfaces
|
||||
4. **Composition**: Objects that PaymentProcessor contains or creates
|
||||
|
||||
Format the analysis as:
|
||||
- Dependency graph (incoming and outgoing)
|
||||
- Architectural layer analysis
|
||||
- Coupling assessment
|
||||
- Refactoring impact evaluation
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Be specific about goals**: Clearly state what you need to understand and why
|
||||
- **Describe context**: Mention if you're debugging, refactoring, or learning the codebase
|
||||
- **Choose appropriate mode**: Use `precision` for method flows, `dependencies` for architecture
|
||||
- **Include visual context**: Reference diagrams or documentation when available
|
||||
- **Follow up with analysis**: Use the generated prompt with `chat` or `analyze` tools
|
||||
|
||||
## Integration with Other Tools
|
||||
|
||||
The `tracer` tool works best when combined with other analysis tools:
|
||||
|
||||
**Tracer + Chat:**
|
||||
```
|
||||
1. Generate analysis prompt with tracer
|
||||
2. Use the prompt with chat tool and relevant code files
|
||||
3. Get detailed call-flow or dependency analysis
|
||||
```
|
||||
|
||||
**Tracer + Analyze:**
|
||||
```
|
||||
1. Use tracer to create structured analysis prompt
|
||||
2. Apply the prompt using analyze tool for systematic code exploration
|
||||
3. Get architectural insights and dependency mapping
|
||||
```
|
||||
|
||||
## When to Use Tracer vs Other Tools
|
||||
|
||||
- **Use `tracer`** for: Creating structured analysis prompts, systematic code exploration planning
|
||||
- **Use `analyze`** for: Direct code analysis without prompt generation
|
||||
- **Use `debug`** for: Specific runtime error investigation
|
||||
- **Use `chat`** for: Open-ended code discussions and exploration
|
||||
127
docs/tools/version.md
Normal file
127
docs/tools/version.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Version Tool - Server Information
|
||||
|
||||
**Get server version, configuration details, and list of available tools**
|
||||
|
||||
The `version` tool provides information about the Zen MCP Server version, configuration details, and system capabilities. This is useful for debugging, understanding server capabilities, and verifying your installation.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
"Get zen to show its version"
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Server version information**: Current version and build details
|
||||
- **Configuration overview**: Active settings and capabilities
|
||||
- **Tool inventory**: Complete list of available tools and their status
|
||||
- **System health**: Basic server status and connectivity verification
|
||||
- **Debug information**: Helpful details for troubleshooting
|
||||
|
||||
## Output Information
|
||||
|
||||
The tool provides:
|
||||
|
||||
**Version Details:**
|
||||
- Server version number
|
||||
- Build timestamp and commit information
|
||||
- MCP protocol version compatibility
|
||||
- Python runtime version
|
||||
|
||||
**Configuration Summary:**
|
||||
- Active providers and their status
|
||||
- Default model configuration
|
||||
- Feature flags and settings
|
||||
- Environment configuration overview
|
||||
|
||||
**Tool Availability:**
|
||||
- Complete list of available tools
|
||||
- Tool version information
|
||||
- Capability status for each tool
|
||||
|
||||
**System Information:**
|
||||
- Server uptime and status
|
||||
- Memory and resource usage (if available)
|
||||
- Connection status with Redis (for conversation memory)
|
||||
- Docker container information
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
🔧 Zen MCP Server Information
|
||||
|
||||
📋 Version: 2.15.0
|
||||
🏗️ Build: 2024-01-15T10:30:00Z (commit: abc123f)
|
||||
🔌 MCP Protocol: 1.0.0
|
||||
🐍 Python Runtime: 3.11.7
|
||||
|
||||
⚙️ Configuration:
|
||||
• Default Model: auto
|
||||
• Providers: Google ✅, OpenAI ✅, Custom ✅
|
||||
• Conversation Memory: Redis ✅
|
||||
• Web Search: Enabled
|
||||
|
||||
🛠️ Available Tools (12):
|
||||
• chat - General development chat & collaborative thinking
|
||||
• thinkdeep - Extended reasoning partner
|
||||
• consensus - Multi-model perspective gathering
|
||||
• codereview - Professional code review
|
||||
• precommit - Pre-commit validation
|
||||
• debug - Expert debugging assistant
|
||||
• analyze - Smart file analysis
|
||||
• refactor - Intelligent code refactoring
|
||||
• tracer - Static code analysis prompt generator
|
||||
• testgen - Comprehensive test generation
|
||||
• listmodels - List available models
|
||||
• version - Server information
|
||||
|
||||
🔍 System Status:
|
||||
• Server Uptime: 2h 35m
|
||||
• Redis Connection: Active
|
||||
• Docker Container: zen-mcp-server (running)
|
||||
```
|
||||
|
||||
## When to Use Version Tool
|
||||
|
||||
- **Troubleshooting**: When experiencing issues with the server or tools
|
||||
- **Configuration verification**: To confirm your setup is correct
|
||||
- **Support requests**: To provide system information when asking for help
|
||||
- **Update checking**: To verify you're running the latest version
|
||||
- **Capability discovery**: To understand what features are available
|
||||
|
||||
## Debug Information
|
||||
|
||||
The version tool can help diagnose common issues:
|
||||
|
||||
**Connection Problems:**
|
||||
- Verify server is running and responsive
|
||||
- Check MCP protocol compatibility
|
||||
- Confirm tool availability
|
||||
|
||||
**Configuration Issues:**
|
||||
- Validate provider setup
|
||||
- Check API key configuration status
|
||||
- Verify feature enablement
|
||||
|
||||
**Performance Troubleshooting:**
|
||||
- Server uptime and stability
|
||||
- Resource usage patterns
|
||||
- Redis connection health
|
||||
|
||||
## Tool Parameters
|
||||
|
||||
This tool requires no parameters - it provides comprehensive server information automatically.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Include in bug reports**: Always include version output when reporting issues
|
||||
- **Check after updates**: Verify version information after server updates
|
||||
- **Monitor system health**: Use periodically to check server status
|
||||
- **Validate configuration**: Confirm settings match your expectations
|
||||
|
||||
## When to Use Version vs Other Tools
|
||||
|
||||
- **Use `version`** for: Server diagnostics, configuration verification, troubleshooting
|
||||
- **Use `listmodels`** for: Model availability and capability information
|
||||
- **Use other tools** for: Actual development and analysis tasks
|
||||
- **Use with support**: Essential information for getting help with issues
|
||||
Reference in New Issue
Block a user