{"id":31908318,"url":"https://github.com/vishapp/multiagent-debugger","last_synced_at":"2025-10-13T15:26:59.020Z","repository":{"id":303992206,"uuid":"1017292119","full_name":"VishApp/multiagent-debugger","owner":"VishApp","description":"Multi-Agent Debugger: An AI-powered debugging system using CrewAI to orchestrate specialized agents that analyze logs, trace code, and uncover root causes across your stack — powered by LLM providers.","archived":false,"fork":false,"pushed_at":"2025-07-22T16:30:49.000Z","size":56668,"stargazers_count":27,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-25T04:54:42.326Z","etag":null,"topics":["ai-tools","autonomous-agents","code-analysis","crewai","debugging","developer-tools","langchain","llm","log-analysis","multi-agent","observability","orchestration","prompt-engineering","python","root-cause-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VishApp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-10T10:04:29.000Z","updated_at":"2025-09-24T06:03:08.000Z","dependencies_parsed_at":"2025-07-18T09:39:33.225Z","dependency_job_id":null,"html_url":"https://github.com/VishApp/multiagent-debugger","commit_stats":null,"previous_names":["vishapp/multiagent-debugger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VishApp/multiagent-debugger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VishApp%2Fmultiagent-debugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VishApp%2Fmultiagent-debugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VishApp%2Fmultiagent-debugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VishApp%2Fmultiagent-debugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VishApp","download_url":"https://codeload.github.com/VishApp/multiagent-debugger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VishApp%2Fmultiagent-debugger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015919,"owners_count":26085778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","autonomous-agents","code-analysis","crewai","debugging","developer-tools","langchain","llm","log-analysis","multi-agent","observability","orchestration","prompt-engineering","python","root-cause-analysis"],"created_at":"2025-10-13T15:26:52.062Z","updated_at":"2025-10-13T15:26:59.008Z","avatar_url":"https://github.com/VishApp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-Agent Debugger\n\nA powerful Python package that uses multiple AI agents to debug API failures by analyzing logs, code, and user questions. Built with CrewAI, it supports LLM providers including OpenAI, Anthropic, Google, Ollama, and more.\n\n## 🎥 Demo Video\n\nWatch the multiagent-debugger in action:\n\n[![Multi-Agent Debugger Demo](https://img.youtube.com/vi/9VTe12iVQ-A/0.jpg)](https://youtu.be/9VTe12iVQ-A?feature=shared)\n\n## 🏗️ Architecture\n\nThe Multi-Agent Debugger uses a sophisticated architecture that combines multiple specialized AI agents working together to analyze and debug API failures.\n\n### Core Agent Flow\n\n![Core Agent Flow](docs/assets/architecture_simple.png)\n\n### Detailed Architecture\n\n![Detailed Architecture](docs/assets/architecture.png)\n\n## ✨ Features\n\n### 🤖 Multi-Agent Architecture\n- **Question Analyzer Agent**: Extracts key entities from natural language questions and classifies error types\n- **Log Analyzer Agent**: Searches and filters logs for relevant information, extracts stack traces\n- **Code Path Analyzer Agent**: Validates and analyzes code paths found in logs\n- **Code Analyzer Agent**: Finds API handlers, dependencies, and error handling code\n- **Root Cause Agent**: Synthesizes findings to determine failure causes and generates visual flowcharts\n\n### 🔧 Comprehensive Analysis Tools\n- **Log Analysis**: Enhanced grep, filtering, stack trace extraction, and error pattern analysis\n- **Code Analysis**: API handler discovery, dependency mapping, error handler identification, multi-language support\n- **Flowchart Generation**: Error flow, system architecture, decision trees, sequence diagrams, and debugging storyboards\n- **Natural Language Processing**: Convert user questions into structured queries\n\n### 🌐 Multi-Provider LLM Support\n- **OpenAI**\n- **Anthropic**\n- **Google**\n- **Ollama**\n- **Azure OpenAI**\n- **AWS Bedrock**\n- **And 50+ more providers**\n\n### Features\n- **Visual Flowcharts**: Mermaid diagrams for error propagation and system architecture\n- **Copyable Output**: Clean, copyable flowchart code for easy sharing\n- **Multi-language Support**: Python, JavaScript, Java, Go, Rust, and more\n\n### 📊 Output Formats\n- **Structured JSON**: Programmatic access to analysis results\n- **Text Documents**: Human-readable reports saved to local files\n- **Visual Flowcharts**: Mermaid diagrams for documentation and sharing\n\n## 🚀 Installation\n\n```bash\n# From PyPI\npip install multiagent-debugger\n\n# From source\ngit clone https://github.com/VishApp/multiagent-debugger.git\ncd multiagent-debugger\npip install -e .\n```\n\n## ⚡ Quick Start\n\n1. **Set up your configuration:**\n```bash\nmultiagent-debugger setup\n```\n\n2. **Debug an API failure:**\n```bash\nmultiagent-debugger debug \"Why did my /api/users endpoint fail yesterday?\"\n```\n\n3. **View generated files:**\n- Analysis results in JSON format\n- Text documents in current directory\n- Visual flowcharts for documentation\n\n## 🖥️ Command-Line Usage\n\n### Debug Command\n\n```\nUsage: multiagent_debugger debug [OPTIONS] QUESTION\n\n  Debug an API failure or error scenario with multi-agent assistance.\n\nArguments:\n  QUESTION    The natural language question or debugging prompt.\n              Example: 'find the common errors and the root-cause'\n\nOptions:\n  -c, --config PATH             Path to config file (YAML)\n  -v, --verbose                 Enable verbose output for detailed logs\n  --mode [frequent|latest|all]  Log analysis mode:\n                                  frequent: Find most common error patterns\n                                  latest:   Focus on most recent errors\n                                  all:      Analyze all available log lines\n  --time-window-hours INT       Time window (hours) for log analysis\n  --max-lines INT               Maximum log lines to analyze\n  --code-path PATH              Path to source code directory/file for analysis\n  -h, --help                    Show this message and exit\n\nExamples:\n  multiagent-debugger debug 'find the common errors and the root-cause' \\\n      --config ~/.config/multiagent-debugger/config.yaml --mode latest\n\n  multiagent-debugger debug 'why did the upload to S3 fail?' \\\n      --mode frequent --time-window-hours 12 \\\n      --code-path /Users/myname/myproject/src\n\n  multiagent-debugger debug 'analyze recent errors' \\\n      --code-path /path/to/specific/file.py\n```\n\nThis command analyzes your logs, extracts error patterns and code paths, and provides root cause analysis with actionable solutions and flowcharts.\n\n## ⚙️ Configuration\n\nCreate a `config.yaml` file (or use the setup command):\n\n```yaml\n# Paths to log files\nlog_paths:\n  - \"/var/log/myapp/app.log\"\n  - \"/var/log/nginx/access.log\"\n\n# Path to source code directory or file for analysis (SECURITY FEATURE)\ncode_path: \"/path/to/your/source/code\"  # Restricts code analysis to this path only\n\n# Log analysis options\nanalysis_mode: \"frequent\"   # frequent, latest, all\ntime_window_hours: 24      # analyze logs from last N hours\nmax_lines: 10000           # maximum log lines to analyze\n\n# LLM configuration\nllm:\n  provider: openai  # or anthropic, google, ollama, etc.\n  model_name: gpt-4\n  temperature: 0.1\n  #api_key: optional, can use environment variable\n\n# Phoenix monitoring configuration (optional)\nphoenix:\n  enabled: true                                    # Enable/disable Phoenix monitoring\n  host: \"localhost\"                               # Phoenix host\n  port: 6006                                      # Phoenix dashboard port\n  endpoint: \"http://localhost:6006/v1/traces\"     # OTLP endpoint for traces\n  launch_phoenix: true                            # Launch Phoenix app locally\n  headers: {}                                     # Additional headers for OTLP\n```\n\n### Code Path Security\n\nThe `code_path` configuration is a **security feature** that restricts code analysis to a specific directory or file:\n\n```yaml\n# Security: Only analyze code within this path\ncode_path: \"/Users/myname/myproject/src\"\n```\n\n**How it works:**\n- When logs contain file paths (from stack traces, errors), the system validates them against `code_path`\n- Files outside the configured path are **rejected** and not analyzed\n- This prevents the system from analyzing sensitive system files or unrelated codebases\n- Can be a directory (analyzes all source files within) or a specific file\n\n**Use cases:**\n- **Multi-project environments**: Restrict analysis to current project only\n- **Security**: Prevent analysis of system files or sensitive directories\n- **Focus**: Analyze only specific parts of large codebases\n\n**CLI override:**\n```bash\n# Override config file code_path for this session\nmultiagent-debugger debug \"question\" --code-path /path/to/specific/project\n```\n\n### Custom Providers\n\nThe system supports various LLM providers including OpenRouter, Anthropic, Google, and others. See [Custom Providers Guide](docs/CUSTOM_PROVIDERS.md) for detailed configuration instructions.\n\n### Environment Variables\n\nSet the appropriate environment variable for your chosen provider:\n\n- **OpenAI**: `OPENAI_API_KEY`\n- **Anthropic**: `ANTHROPIC_API_KEY`\n- **Google**: `GOOGLE_API_KEY`\n- **Azure**: `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`\n- **AWS**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`\n- See documentation for other providers\n\n## 🔍 How It Works\n\n### 1. Question Analysis\n- Extracts key information like API routes, timestamps, and error types\n- Classifies the error type (API, Database, File, Network, etc.)\n- Structures the query for other agents\n\n### 2. Log Analysis\n- Searches through specified log files using enhanced grep\n- Filters relevant log entries by time and pattern\n- Extracts stack traces and error patterns\n- **Dynamically extracts code paths** (file paths, line numbers, function names)\n- Validates code paths found in logs\n\n### 3. Code Analysis\n- **Validates** that extracted file paths are within the configured `code_path` (security)\n- Locates relevant API handlers and endpoints\n- Identifies dependencies and error handlers\n- Maps the code structure and relationships\n- Supports multiple programming languages (Python, JavaScript, Java, Go, Rust, etc.)\n- **Rejects** analysis of files outside the configured code path\n\n### 4. Root Cause Analysis\n- Synthesizes information from all previous agents\n- Determines the most likely cause with confidence levels\n- Generates creative narratives and metaphors\n- Creates visual flowcharts for documentation\n\n### 5. Output Generation\n- Structured JSON for programmatic access\n- Human-readable text documents\n- Visual flowcharts in Mermaid format\n- Copyable flowchart code for easy sharing\n\n## 📊 Phoenix Monitoring\n\nThe debugger includes built-in Phoenix monitoring for tracking agent execution, LLM usage, and performance metrics.\n\n### View Monitoring Status\n```bash\nmultiagent-debugger phoenix\n```\n\nThis shows your Phoenix configuration and provides instructions for accessing the dashboard.\n\n### Remote Server Access\n\nWhen running the debugger on a remote server, use SSH port forwarding to access the Phoenix dashboard:\n\n```bash\n# On your local machine, create SSH tunnel\nssh -L 6006:localhost:6006 user@your-server\n\n# Then visit in your local browser\nhttp://localhost:6006\n```\n\n### Configuration\n\nPhoenix monitoring is configured in your `config.yaml`:\n\n```yaml\nphoenix:\n  enabled: true\n  host: localhost\n  port: 6006\n  launch_phoenix: true\n```\n\n### Features\n\n- **Real-time Monitoring**: Track agent executions as they happen\n- **LLM Usage Tracking**: Monitor token usage and costs across providers\n- **Performance Metrics**: Analyze execution times and success rates\n- **Visual Traces**: See the complete flow of agent interactions\n- **Automatic Launch**: Starts automatically when you run debug commands\n\n## 🛠️ Advanced Usage\n\n### List Available Providers\n```bash\nmultiagent-debugger list-providers\n```\n\n### List Models for a Provider\n```bash\nmultiagent-debugger list-models openai\n```\n\n### Debug with Custom Config\n```bash\nmultiagent-debugger debug \"Question?\" --config path/to/config.yaml\n```\n\n### Analyze Recent Errors Only\n```bash\nmultiagent-debugger debug \"What went wrong?\" --mode latest --time-window-hours 2\n```\n\n### Analyze Large Log Files\n```bash\nmultiagent-debugger debug \"Find patterns\" --max-lines 50000\n```\n\n### Restrict Code Analysis to Specific Path\n```bash\n# Only analyze code within /path/to/project directory\nmultiagent-debugger debug \"What caused the error?\" --code-path /path/to/project\n\n# Analyze only a specific file\nmultiagent-debugger debug \"Debug this file\" --code-path /path/to/file.py\n```\n\n## 🧪 Development\n\n```bash\n# Create virtual environment\npython package_builder.py venv\n\n# Install development dependencies\npython package_builder.py install\n\n# Run tests\npython package_builder.py test\n\n# Build distribution\npython package_builder.py dist\n```\n\n## 📋 Requirements\n\n- **Python**: 3.8+\n- **Dependencies**:\n  - crewai\u003e=0.28.0\n  - pydantic\u003e=2.0.0\n  - And others (see requirements.txt)\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 🆘 Support\n\n- **GitHub Issues**: [Report a bug](https://github.com/VishApp/multiagent-debugger/issues)\n- **Documentation**: [Read more](https://github.com/VishApp/multiagent-debugger#readme)\n\n## 🎯 Use Cases\n\n- **API Debugging**: Quickly identify why API endpoints are failing\n- **Production Issues**: Analyze logs and code to find root causes\n- **Error Investigation**: Understand complex error chains and dependencies\n- **Documentation**: Generate visual flowcharts for error propagation\n- **Team Collaboration**: Share analysis results in multiple formats\n- **Multi-language Projects**: Support for Python, JavaScript, Java, Go, Rust, and more\n- **Time-based Analysis**: Focus on recent errors or specific time periods\n- **Large Log Analysis**: Handle massive log files with configurable limits\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvishapp%2Fmultiagent-debugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvishapp%2Fmultiagent-debugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvishapp%2Fmultiagent-debugger/lists"}