AI-powered debugging assistant with seamless Claude Code integration - Transform error messages into actionable solutions with advanced AI analysis, multi-language support, and native Claude Code commands. Let AI understand your bugs instantly!
- 🌐 Extended Language Support - Now supports 10+ languages including Shell/Bash, Docker, YAML/JSON, Kotlin, Swift, and SQL
- 🐳 Docker & Container Analysis - Comprehensive Dockerfile and Docker Compose error detection
- 📄 Configuration File Support - Smart YAML/JSON analysis for CI/CD pipelines and Kubernetes
- 📱 Mobile Development - Full support for Kotlin (Android) and Swift (iOS) error analysis
- 🚀 60% Faster Pattern Matching - Completely rewritten engine for better performance
- 🎯 Enhanced Pattern Recognition - 50+ new error patterns per language
- 🌍 Multi-Language Support - Full i18n with Chinese (中文) and English interface
- 🧠 Advanced Error Analysis - Three intelligent analyzers: Stack Trace, Pattern, and Code Context
- 🎯 ML-Ready Suggestion Engine - Confidence-scored solutions based on error patterns
- 🔍 Deep Stack Trace Analysis - Support for Python, JavaScript, TypeScript, Java, Ruby, Go, Shell/Bash, Docker, YAML/JSON, Kotlin, Swift, SQL
- 🤖 Claude Code Integration - Native
/ccdebugslash command for seamless workflow - 📋 Smart Clipboard Integration - Auto-detect and analyze errors from clipboard
- 🎨 Beautiful Terminal UI - Rich, colorful output with progress indicators
- 📊 Intelligent Error Patterns - Pre-configured patterns for common errors
- 🔧 Extensible Architecture - Plugin system for custom analyzers and patterns
- 📈 Learning System - Improves suggestions based on successful resolutions
- 🚀 Performance Optimized - Direct Python API for faster analysis
- 🔒 Secure by Default - Safe error handling without exposing sensitive data
# Install from source
git clone https://github.com/888wing/ClaudeCode-Debugger.git
cd ClaudeCode-Debugger
pip install -e .
# Setup Claude Code integration (NEW!)
python setup_claude_code.py# Analyze error with Chinese interface
ccdebug "TypeError: Cannot read property 'name' of undefined" --lang zh
# Deep analysis with suggestions
ccdebug "AttributeError: 'NoneType' object" --analyze-stack --suggest
# Read from clipboard
ccdebug -c --lang zh
# Interactive mode
ccdebug -i
# Claude Code integration
# In Claude Code, when you encounter an error:
/ccdebug --last --zh --deep# Chinese interface (中文界面)
cczh "錯誤信息" # Quick Chinese analysis
ccfull # Full analysis in Chinese
# English interface
ccen "error message" # Quick English analysis
ccdebug --lang en # Explicit English- Shell/Bash - Script errors, command not found, syntax issues
- Docker - Dockerfile syntax, build errors, runtime issues
- YAML/JSON - Configuration errors, CI/CD pipelines, Kubernetes manifests
- Kotlin - Null safety, coroutines, Android-specific patterns
- Swift - Optionals, memory management, SwiftUI errors
- SQL - Query syntax, joins, performance hints
- Python - Full stack traces, import errors, type errors
- JavaScript/TypeScript - Runtime errors, async issues, type mismatches
- Java - Exceptions, null pointers, classpath issues
- Ruby - Rails errors, gem conflicts, syntax issues
- Go - Compilation errors, goroutine panics, interface issues
CCDebugger now seamlessly integrates with Claude Code! Errors are automatically detected and analyzed without any manual intervention.
When you run commands in Claude Code that produce errors, CCDebugger automatically:
- Detects error patterns in real-time
- Extracts error context and stack traces
- Generates AI-powered debugging suggestions
- Provides instant solutions in Chinese or English
# Analyze last error
ccdebug last
# View error history
ccdebug history
# Start monitoring mode
ccdebug monitor start
# Configure settings
ccdebug config set defaultLanguage zh# When you run code with errors in Claude Code:
result = undefined_function() # NameError
# CCDebugger automatically shows:
╭─────────────────────────────────────────────────────────────────╮
│ 🔍 CCDebugger 自動錯誤分析 │
╰─────────────────────────────────────────────────────────────────╯
⚠️ **CCDebugger 錯誤分析報告**
**錯誤類型**: NameError
**嚴重程度**: high
**AI 調試提示**:
你遇到了一個 NameError，這表示 Python 無法找到名為 'undefined_function' 的函數。
**🎯 智能建議**:
1. 檢查是否正確導入了該函數
2. 確認函數名稱拼寫是否正確
3. 檢查函數是否在當前作用域內定義See CLAUDE_CODE_INTEGRATION.md for full documentation.
$ ccdebug "AttributeError: 'NoneType' object has no attribute 'profile'" --lang zh --suggest
🚨 Python 錯誤 - HIGH 優先級
檢測到: AttributeError - NoneType 錯誤
📊 堆疊追蹤分析:
- 根本原因: 嘗試訪問 None 對象的屬性
- 影響範圍: 1 個文件受影響
🎯 智能建議 (信心度: 85%):
1. 添加 None 檢查:
```python
if user and hasattr(user, 'profile'):
return user.profile.avatar_url
return None-
使用 getattr 安全訪問:
profile = getattr(user, 'profile', None) if profile: return profile.avatar_url
-
使用 try-except 處理:
try: return user.profile.avatar_url except AttributeError: return None
✅ 已複製到剪貼板
### JavaScript TypeError with Code Context
```bash
$ ccdebug --last --lang en --analyze-stack --suggest
🚨 JavaScript Error - HIGH Priority
TypeError: Cannot read property 'map' of undefined
🔍 Stack Trace Analysis:
┌─────────────────────────────────────────┐
│ at TodoList (TodoList.jsx:15:19) │
│ at renderWithHooks (react-dom.js:14985)│
│ at mountComponent (react-dom.js:17441) │
└─────────────────────────────────────────┘
📊 Pattern Analysis:
- Error Pattern: undefined_property_access
- Common in: React component props
- Severity: HIGH
🎯 Suggestions (Confidence: 92%):
1. Add default props:
```javascript
function TodoList({ todos = [] }) {
return <ul>{todos.map(todo => <li>{todo.text}</li>)}</ul>
}
-
Add conditional rendering:
function TodoList({ todos }) { if (!todos || !Array.isArray(todos)) { return <div>No todos available</div> } return <ul>{todos.map(todo => <li>{todo.text}</li>)}</ul> }
-
Use optional chaining:
return <ul>{todos?.map(todo => <li>{todo.text}</li>) || null}</ul>
[✓ Analysis complete]
### Claude Code Integration
```bash
# In Claude Code, when you encounter an error:
User: python manage.py runserver
Claude: [Shows Django error]
User: /ccdebug --last --zh --deep
Claude:
🚨 Django 錯誤分析
檢測到: ImproperlyConfigured
🔍 深度分析:
- 錯誤位置: settings.py:89
- 根本原因: DATABASES 配置缺失
- 影響: 應用程序無法啟動
🎯 解決方案:
1. 檢查 settings.py 中的 DATABASES 配置
2. 確保環境變數正確設置
3. 驗證數據庫連接參數
[詳細步驟和代碼示例...]
$ ccdebug "./deploy.sh: line 42: syntax error near unexpected token 'fi'" --lang en
🚨 Bash Script Error - HIGH Priority
Syntax error detected in shell script
📊 Error Analysis:
- Error Type: Syntax Error
- Location: deploy.sh, line 42
- Issue: Missing 'then' after 'if' statement
🎯 Solution:
Add 'then' keyword after your if condition:
```bash
if [ "$ENVIRONMENT" = "production" ]; then # Add 'then' here
deploy_production
fi
#### Docker Build Error
```bash
$ ccdebug "Service 'web' failed to build: COPY failed: no source files" --lang zh
🚨 Docker 構建錯誤 - HIGH 優先級
Docker 構建過程中檔案複製失敗
📊 錯誤分析:
- 錯誤類型: COPY 指令失敗
- 原因: 源檔案不存在或路徑錯誤
- 影響: Docker 映像無法構建
🎯 解決方案:
1. 檢查 Dockerfile 中的 COPY 路徑:
```dockerfile
# 確保路徑相對於構建上下文
COPY ./app /app # 而非 COPY app /app
- 驗證構建上下文包含所需檔案:
docker build -f Dockerfile . # '.' 是構建上下文
#### YAML Configuration Error
```bash
$ ccdebug "error validating data: ValidationError(Deployment.spec.replicas): invalid type" --lang en
🚨 Kubernetes YAML Error - MEDIUM Priority
Invalid YAML configuration detected
📊 Error Analysis:
- Error Type: Type Validation Error
- Field: spec.replicas
- Expected: integer, Got: string
🎯 Solution:
Fix the replicas field to use a number:
```yaml
spec:
replicas: 3 # Not "3" (string)
## 🛠️ Advanced Features
### Intelligent Analyzers
CCDebugger includes three advanced analyzers:
```python
# Stack Trace Analyzer - Multi-language support
from claudecode_debugger.analyzers import StackTraceAnalyzer
analyzer = StackTraceAnalyzer()
result = analyzer.analyze(error_text)
# Returns: language, frames, root_cause, error_type
# Pattern Analyzer - Detects common error patterns
from claudecode_debugger.analyzers import PatternAnalyzer
analyzer = PatternAnalyzer()
patterns = analyzer.analyze(error_text)
# Returns: matched patterns with solutions
# Code Context Analyzer - Extracts code context
from claudecode_debugger.analyzers import CodeContextAnalyzer
analyzer = CodeContextAnalyzer()
context = analyzer.extract_context("app.py", line_number=42)
# Returns: code snippet with surrounding lines
from claudecode_debugger.suggestions import SuggestionEngine
engine = SuggestionEngine()
suggestions = engine.generate_suggestions(
error_type="AttributeError",
error_patterns=["null_reference"],
stack_trace_info=stack_info
)
# Returns: Ranked suggestions with confidence scoresCreate ~/.ccdebugrc for personal preferences:
{
"defaultLanguage": "zh",
"defaultMode": "deep",
"autoSuggest": true,
"copyToClipboard": true,
"contextLines": 10,
"favoriteFrameworks": ["django", "react", "vue"],
"customPatterns": {
"myapp": {
"errorPattern": "MyAppError:",
"suggestion": "Check MyApp configuration"
}
}
}The /ccdebug command seamlessly integrates with Claude Code:
# Auto-detection and analysis
/ccdebug --last --zh
# Different analysis modes
/ccdebug --quick # Fast analysis
/ccdebug --deep # Detailed analysis with suggestions
/ccdebug --full # Complete analysis with code context
# Batch processing
/ccdebug --batch --dir logs/
# Watch mode
/ccdebug --watch server.logAdd your own error patterns:
from claudecode_debugger.analyzers.pattern import ErrorPattern
custom_pattern = ErrorPattern(
name="custom_api_error",
pattern=r"API Error: (\d+)",
description="Custom API error",
category="api",
severity="high",
common_causes=["Invalid API key", "Rate limit exceeded"],
solutions=["Check API credentials", "Implement retry logic"]
)CCDebugger is built with a modular, extensible architecture:
claudecode_debugger/
├── analyzers/ # Intelligent error analyzers
│ ├── stack_trace.py # Multi-language stack trace analysis
│ ├── pattern.py # Error pattern detection
│ └── code_context.py # Code context extraction
├── suggestions/ # ML-ready suggestion engine
│ └── engine.py # Confidence-scored solutions
├── i18n/ # Internationalization
│ ├── translator.py # Translation engine
│ └── messages/ # Language files (en, zh)
├── formatters/ # Output formatters
│ ├── console.py # Rich terminal output
│ └── markdown.py # Markdown formatting
└── cli_new.py # Enhanced CLI with full features
- I18n System: Full internationalization with automatic language detection
- Analyzer Framework: Pluggable analyzers for different error types
- Suggestion Engine: Knowledge base with confidence scoring
- Claude Code Integration: Native slash command support
- Rich UI: Beautiful terminal output with progress indicators
We welcome contributions! Please see our Contributing Guidelines for details.
# Clone the repository
git clone https://github.com/888wing/ClaudeCode-Debugger.git
cd ClaudeCode-Debugger
# Install in development mode
make dev
# Run tests
make test
# Format code
make formatThis project is licensed under the MIT License - see the LICENSE file for details.
- Built for the Claude Code community
- Inspired by the need for better debugging workflows
- Special thanks to all contributors
- 📖 Claude Code Integration Guide
- 🎯 /ccdebug Command Reference
- 📚 Real-World Examples
- 🐛 Issue Tracker
- 💬 Discussions
- 🔔 Changelog
- 🌐 Added support for Shell/Bash, Docker, YAML/JSON, Kotlin, Swift, and SQL
- 🚀 60% performance improvement in pattern matching
- 📊 500+ error patterns across all supported languages
- 🐳 Docker and container-specific error analysis
- 📄 Configuration file validation for CI/CD pipelines
- 📱 Mobile development support (Kotlin/Swift)
- 🎯 Enhanced confidence scoring algorithm
- 🌍 Full internationalization (i18n) with Chinese and English support
- 🧠 Three new intelligent analyzers for deep error analysis
- 🎯 ML-ready suggestion engine with confidence scoring
- 🤖 Native Claude Code integration with
/ccdebugcommand - 📊 Advanced error pattern detection
- 🔍 Multi-language stack trace analysis
- ✨ Complete architectural overhaul for extensibility