# AI Debugger 0.1.0 - Initial Release
**GitHub Release**: [0.1.0](https://github.com/ai-debugger-inc/aidb/releases/tag/0.1.0)
**PyPI**: [ai-debugger-inc](https://pypi.org/project/ai-debugger-inc/)
---
## Introducing AI Debugger
AI Debugger (AIDB) is a lightweight, language-agnostic Python API that enables AI systems to programmatically control and introspect live debugging sessions through the Debug Adapter Protocol (DAP).
Instead of reading code and guessing at fixes, AI agents can now set breakpoints, pause execution, inspect the actual values in variables, and step through code line by line - just like a human developer would.
### Why It Matters
We've all seen AI agents confidently propose fixes that don't work. The problem is they're reasoning about static code without seeing what actually happens at runtime. With AI Debugger, an agent can:
- Pause execution at the exact line where something goes wrong
- Look at the actual values in variables, not what they "should" be
- Trace the call stack to understand how execution got there
- Make grounded fixes based on real runtime state
### What You Can Do With It
- **Debug flaky tests** - Let the agent inspect state when tests fail intermittently
- **Attach to running containers** - Debug JVMs in Docker without stopping the service
- **Investigate production-like environments** - Remote attach to staging servers
- **Understand unfamiliar codebases** - Step through execution to learn behavior
---
## Installation
```bash
pip install ai-debugger-inc
```
### MCP Client Configuration
Add to your MCP client configuration (Claude Code, Cline, Cursor, etc.):
```json
{
"mcpServers": {
"ai-debugger": {
"command": "python",
"args": ["-m", "aidb_mcp"]
}
}
}
```
### Debug Adapters
Adapters are downloaded automatically on first use:
- **Python**: debugpy (Microsoft)
- **JavaScript/TypeScript**: vscode-js-debug (Microsoft)
- **Java**: java-debug (Microsoft)
Storage location: `~/.aidb/adapters/`
---
## Supported Languages
### Python (3.10+)
**Frameworks**: pytest, django, flask, fastapi, pyramid, asyncio, behave
**Capabilities**:
- Conditional breakpoints with expression evaluation
- Logpoints with template syntax
- Hit count breakpoints (7 condition modes)
- Function breakpoints
- Variable modification at runtime
- Exception breakpoints
### JavaScript/TypeScript (Node 18+)
**Frameworks**: jest, mocha, express, node, typescript
**Capabilities**:
- Full source map support for TypeScript
- Conditional and hit count breakpoints
- Logpoints
- Restart frame (step backwards)
- Memory inspection
- Child process debugging
### Java (JDK 17+)
**Frameworks**: JUnit, Spring, Maven, Gradle
**Capabilities**:
- Conditional breakpoints
- Logpoints
- Hit count breakpoints
- Data breakpoints (watchpoints) - break on variable read/write
- Function breakpoints
- Hot code replace (when JVM supports it)
---
## MCP Tools Reference
AI Debugger exposes 12 tools through the Model Context Protocol:
### Initialization
| Tool | Description |
|------|-------------|
| `init` | **Required first step.** Initializes debugging context, discovers capabilities, loads launch.json configurations |
### Session Management
| Tool | Description |
|------|-------------|
| `session_start` | Create and start a debug session (launch, attach, or remote attach modes) |
| `session` | Manage session lifecycle: status, list, stop, restart, switch |
### Execution Control
| Tool | Description |
|------|-------------|
| `execute` | Run program from beginning or continue from current position |
| `step` | Step through code: into functions, over lines, or out of current function |
| `run_until` | Run to a specific location using temporary breakpoints |
### Inspection & Modification
| Tool | Description |
|------|-------------|
| `inspect` | Examine program state: locals, globals, stack, threads, expressions |
| `variable` | Get, set, or patch variables at runtime |
| `breakpoint` | Manage breakpoints: set, remove, list, clear; supports conditions and logpoints |
### Configuration
| Tool | Description |
|------|-------------|
| `config` | Show configuration, environment, launch.json discovery, adapter status |
| `context` | Get debugging context with intelligent next-step suggestions |
| `adapter` | Download, list, and manage debug adapters |
---
## Key Features
### Advanced Breakpoints
- **7 hit condition modes**: `>`, `>=`, `=`, `<`, `<=`, `%` (modulo), exact count
- **Conditional breakpoints**: Break only when expression evaluates true
- **Logpoints**: Log values to output without pausing execution
- **Column-level breakpoints**: Precise placement for minified code
- **Real-time verification**: Immediate feedback on breakpoint validity
### VS Code Integration
Reuse your existing `launch.json` configurations:
```python
session_start(
language="python",
launch_config_name="Python: Django",
workspace_root="/path/to/project"
)
```
No duplicate configuration needed - AI Debugger discovers and uses your existing debug settings.
### Remote Debugging
Attach to running processes locally or across networks:
```python
# Attach to JVM in Docker container
session_start(
language="java",
mode="remote_attach",
host="localhost",
port=5005,
source_paths=["/local/path/to/source"]
)
```
### Multi-Session Support
Debug multiple processes simultaneously - useful for microservices, client-server applications, or comparing behavior across environments.
---
## Architecture Highlights
### Human-Cadence Operation
AI Debugger is designed for AI agent workflows, not typical API speed:
- Breakpoints must be set before starting execution
- Inspection happens when the program is paused
- Stepping is one operation per line - just like a human debugger
### Language-Agnostic Design
The same Python API works across all supported languages through pluggable adapters built on the Debug Adapter Protocol (DAP).
### Minimal Dependencies
Core installation requires only 3 dependencies:
- `mcp` - Model Context Protocol
- `aiofiles` - Async file operations
- `psutil` - Process utilities
No heavy IDE dependencies.
---
## Platform Support
| Platform | Status |
|----------|--------|
| macOS (Intel) | Fully supported |
| macOS (ARM/M1+) | Fully supported |
| Linux (x86_64) | Fully supported |
| Windows | WSL recommended; native support in progress |
---
## Documentation
- **[Quickstart Guide](../user-guide/mcp/quickstart)** - Get debugging in 60 seconds
- **[Python Guide](../user-guide/languages/python)** - Python-specific features
- **[JavaScript Guide](../user-guide/languages/javascript)** - Node.js and TypeScript debugging
- **[Java Guide](../user-guide/languages/java)** - JVM debugging
- **[Tools Reference](../user-guide/mcp/tools/index)** - Complete MCP tools documentation
---
## What's Next
This 0.1.0 release establishes the foundation. Coming in future releases:
- Additional framework-specific configurations
- CI/CD integration for automated test failure debugging
- Enhanced cross-platform support
- Performance optimizations
- Additional language adapters based on community feedback
---
## Getting Help
- **GitHub Issues**: [github.com/ai-debugger-inc/aidb/issues](https://github.com/ai-debugger-inc/aidb/issues)
- **Discord**: [discord.com/invite/UGS92b6KgR](https://discord.com/invite/UGS92b6KgR)
- **Documentation**: [AI Debugger Docs](../index)
---
## Acknowledgments
AI Debugger builds on excellent open-source projects:
- **Debug Adapter Protocol** - Microsoft's language-agnostic debugging protocol
- **debugpy** - Python debugging adapter
- **vscode-js-debug** - JavaScript/TypeScript debugging adapter
- **java-debug** - Java debugging adapter
- **Model Context Protocol** - Anthropic's protocol for AI tool integration
