deepdiver-cli 0.2.4

SWEDeepDiver is an automated analysis agent for Software Engineering (SWE) problems.

SWEDeepDiver

SWEDeepDiver is an automated analysis agent for Software Engineering (SWE) problems, designed to perform deep diagnosis and root cause analysis for multi-technology stack issues including Android, iOS, Backend, and Frontend.

It simulates experienced engineers' troubleshooting habits: from whole to part, from symptoms to root causes, comprehensively utilizing logs, exception traces, various issue files, source code, and knowledge bases to build "timeline + evidence chains", ultimately providing structured, verifiable diagnostic conclusions.

✨ Features

Core Capabilities

• 🤖 Automated Problem Diagnosis: Simulates experienced engineers' troubleshooting approach using ReAct (Reasoning + Acting) architecture
• 🔍 Multi-source Evidence Analysis: Correlates logs, exception traces, issue files, source code, and knowledge bases
• 📊 Structured Reasoning: Builds verifiable "timeline + evidence chain" for root cause analysis
• 🎯 Multi-technology Stack: Supports Android, iOS, backend (Java, Python, Node.js, etc.), and frontend
• 💾 Zero-intrusion Design: All state saved in ~/.deepdiver/, no files written to user projects
• 🔑 Session Management: Independent sessions, fully traceable and reproducible
• 🔌 Plugin System: Custom desensitization, decryption, and filtering strategies
• 📚 Knowledge Base Integration: Domain-specific knowledge injection for better accuracy
• 🌐 Multi-LLM Support: DeepSeek, Moonshot, Alibaba Tongyi, OpenRouter, and more

🎉 New in v0.2.0

Modern UI & Real-time Feedback

• 🖥️ Rich Terminal UI: Beautiful, informative terminal interface powered by Rich library
• 📊 Real-time Progress Tracking: Watch the agent think, explore, and analyze in real-time
• 💡 Key Finding Highlights: Important discoveries are highlighted as they happen
• 🎛️ Dual Display Modes:
  • Concise Mode: Clean output with just the essentials
  • Verbose Mode: Detailed thinking process and tool outputs
  • Press v during runtime to toggle between modes
• 🛠️ Smart Tool Display: Tool calls show only key parameters for clarity

Enhanced Reporting

• 📄 Interactive HTML Reports: Professional reports with collapsible sections and mobile-responsive design
• 📑 Structured Output Formats: JSON for machine processing, Markdown for documentation, HTML for presentation
• 📈 Enhanced Metadata: Includes commit counts, review results, and confidence scores

Improved Analysis Tools

• ⏱️ Time-Range Filtering: Filter logs by time windows for focused analysis
• 🔎 Better Grep Results: Shows total/returned line counts with truncation warnings
• 📖 Enhanced Read Tool: File size and line count information for better context
• 🧪 Improved Review Process: Better separation between LLM summaries and user-facing details

Installation

Using uv (Recommended)

uv is a fast Python package installer and resolver written in Rust. It's the recommended way to install SWEDeepDiver:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SWEDeepDiver using uv tool
uv tool install deepdiver-cli

Using pip (Alternative)

pip install deepdiver-cli

Additional Requirements

SWEDeepDiver requires ripgrep for efficient file searching:

# On macOS
brew install ripgrep

# On Ubuntu/Debian
sudo apt-get install ripgrep

# Other platforms: refer to ripgrep installation guide

For code analysis functionality, Claude Code CLI is optional:

npm install -g @anthropic-ai/claude-code

Quick Start

Basic Usage

# Analyze issue with code directory (current directory as code)
cd /path/to/your/code
deepdiver -c --attachment_path /path/to/issue/attachments --issue "Application crashes on startup"

# Analyze issue from attachment directory
cd /path/to/issue/attachments
deepdiver --code_path /path/to/your/code --issue "Performance degradation in payment service"

# Analyze attachments only (no code)
cd /path/to/issue/attachments
deepdiver --issue "Database connection timeout errors"

UI Interaction

During analysis, SWEDeepDiver provides real-time feedback:

Step 1: Thinking...
💡 Key Finding: Exception trace indicates database connection timeout

Step 1: Grep(/var/log/app.log, "Connection timeout")
⎿ Grep found 15 result(s)

Step 2: Inspect(/var/log/app.log)
⎿ Inspected /var/log/app.log

[Press 'v' to toggle verbose/concise mode]

Press v anytime during analysis to toggle between:

• Concise Mode (default): Clean output with tool summaries
• Verbose Mode: Full thinking process and detailed tool outputs

Parameter Reference

• -c, --code: Declare current working directory as code directory
• --code-path <PATH>: Additional code directories (multiple allowed)
• --attachment-path <PATH>: Attachment directories (multiple allowed)
• --issue "<TEXT>": Problem description in natural language
• --verbose: Start in verbose mode (show detailed thinking and tool outputs)
• --list-sessions: List historical diagnosis sessions
• --show-report <session_id>: Show diagnostic report for specific session

Configuration

Agent Configuration

Configuration files are automatically created on first run. The first time you run DeepDiver, it will automatically generate configuration files from templates:

# Configuration files are auto-created in ~/.deepdiver/config/
# - config.toml: Main configuration (LLM providers, API keys, model settings)
# - knowledge_config.toml: Knowledge base configuration (optional)

To manually configure or update settings:

# Edit the main configuration
# Configure LLM providers, API keys, model settings, etc.
vim ~/.deepdiver/config/config.toml

Plugin Development

Implement custom plugins for data processing:

# Example: Custom data masking
from deepdiver_cli.plugins.datamask import DataMasker

class MyDataMasker(DataMasker):
    def mask(self, raw: str) -> str:
        # Implement your data masking logic
        return masked

The plugin system automatically discovers and loads classes implementing Protocol interfaces.

Usage Example

Analyzing an Android ANR issue:

deepdiver -c --attachment_path examples/android/anr --issue "Application experiences ANR, please analyze the cause"

SWEDeepDiver will:

1. Parse problem description and attachments
2. Identify problem type and evidence sources
3. Call analysis tools (Glob, ProcessFile, Grep, Inspect, AnalyzeCode, etc.)
4. Build timeline and evidence chains
5. Generate structured diagnostic report (Markdown + JSON + HTML)
6. Save all results in ~/.deepdiver/sessions/<session_id>/

Report Output:

• summary.md: Executive summary with core conclusions and timeline
• report.json: Complete structured data for further processing
• report.html: Interactive HTML report with collapsible sections
• diagnosis_*.md: Detailed diagnosis files with evidence chains

Output Example

**Conclusion**: ANR root cause is `HeavyService.performHeavyOperation` calling `Thread.sleep` in main thread.

**Confidence**: High

**Evidence Strength**: High

**Core Evidence**:
1. **Log/Trace Evidence**:
   - `03:34:05.428` MainActivity: "Performing heavy database operation"
   - `03:34:11.428` ActivityManager reports ANR for service `com.example.testapp/.HeavyService`
   - ANR Trace shows main thread Sleeping at `Thread.sleep`, called by `HeavyService.performHeavyOperation`

**Timeline**:
| Time           | Event                                       | Source              |
|----------------|---------------------------------------------|---------------------|
| 03:34:05.428   | Heavy operation starts                      | MainActivity log    |
| 03:34:11.428   | ANR reported                                | ActivityManager log |
| 03:34:11       | Main thread blocked in sleep                | ANR Trace           |

Project Structure

SWEDeepDiver/
├── src/deepdiver_cli/          # Source code
│   ├── react_core/             # ReAct core engine (agent, llm, tool)
│   ├── tools/                  # Analysis tools (grep, glob, read, inspect, etc.)
│   ├── events/                 # Event-driven architecture (NEW)
│   ├── ui/                     # UI rendering system (NEW)
│   ├── app/                    # Application logic
│   ├── chat/                   # Chat models and providers
│   ├── plugins/                # Plugin interfaces (datamask, decryptor, filter)
│   ├── templates/              # Report templates (HTML, Markdown)
│   ├── config.py              # Configuration management
│   └── cli.py                 # CLI entry point
├── examples/                   # Example issues
├── config/                     # Configuration templates
├── knowledge/                  # Knowledge base directory
├── pyproject.toml             # Python project configuration
├── README.md                  # This file
└── CLAUDE.md                  # Development guide

Technology Stack

• Python 3.12+ - Primary language
• Typer - Modern CLI framework
• Pydantic - Data validation and settings management
• Rich - Terminal UI and formatting
• OpenAI - LLM API client
• HTTPX - Async HTTP client
• Tenacity - Retry library with exponential backoff
• Structlog - Structured logging
• ReAct Pattern - Reasoning + Acting architecture for agent decision-making
• Event-Driven Architecture - Decoupled UI and business logic (NEW)
• ripgrep - Fast text search for log analysis

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

Development Setup

git clone https://github.com/SteveYang92/SWEDeepDiver.git
cd SWEDeepDiver
uv venv --python 3.12
source .venv/bin/activate  # Unix/macOS
uv pip install -e ".[dev]"
uv run pytest tests/ -v

License

MIT License - see LICENSE file.

Disclaimer

Security & Privacy

• SWEDeepDiver is designed for local/self-hosted use
• Logs, traces, and source code may contain sensitive information
• Implement proper data masking/decryption plugins for your security requirements
• API keys and configurations should be kept secure

Diagnostic Limitations

• Results depend on available data, knowledge bases, and LLM capabilities
• Not guaranteed to be completely accurate in all scenarios
• Use as an auxiliary analysis tool, not the sole basis for decisions

Usage Responsibility

• Provided "as-is" without warranties
• Test thoroughly in controlled environments before production use

Acknowledgments

• Configuration system references OpenManus
• Prompt and tool design references ClaudeCode

---

For Chinese documentation, see README_CN.md