Metadata-Version: 2.4
Name: dbgagent
Version: 0.5.1
Summary: AI-powered Python debugger — run a broken script, get root cause, explanation, and fix
Author: Aryan Tyagi
License-Expression: MIT
Project-URL: Homepage, https://github.com/aryantyagi2211/Debug_agent
Project-URL: Issues, https://github.com/aryantyagi2211/Debug_agent/issues
Keywords: debugger,python,ai,llm,groq,openai,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: groq
Requires-Dist: openai
Requires-Dist: anthropic
Requires-Dist: python-dotenv
Requires-Dist: rich
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0; extra == "mcp"

# dbgagent

**Your AI-powered code assistant.** Debug, explain, simplify, review, test, secure, optimize, convert, and document any programming language.

> Built by [Aryan Tyagi](https://github.com/aryantyagi2211) with Codex/GPT-5.6 during OpenAI Build Week.

---

## What is dbgagent?

dbgagent is a tool that helps you with any code. Here's what it does:

1. **Fix** — Run a broken script, catch the error, explain it, and fix it automatically
2. **Explain** — Understand what any code does, line by line
3. **Simplify** — Make code shorter and cleaner without changing behavior
4. **Review** — Find bugs, bad practices, and improvements
5. **Test** — Generate unit tests for your code
6. **Secure** — Find security vulnerabilities
7. **Optimize** — Find performance bottlenecks
8. **Convert** — Convert code between programming languages
9. **Doc** — Generate documentation for your code

Works with **any programming language** — Python, JavaScript, Go, Rust, Java, C++, and more.

---

## How to install

Open your terminal and type:

```bash
pip install dbgagent
```

That's it. One command.

---

## How to set up

You need a free API key from Groq (this is what powers the AI):

1. Go to [console.groq.com](https://console.groq.com) and sign up (free)
2. Copy your API key
3. When you first run dbgagent, it will ask you to paste your key

---

## How to use

### Option 1: Interactive menu (easiest)

Just type `dbgagent` and press Enter:

```bash
dbgagent
```

You'll see a professional terminal UI:

```
╭─────────────────────────────────────────────────────╮
│                                                     │
│   ██████╗ ██╗   ██╗██╗ ██████╗ ███████╗            │
│  ██╔════╝ ██║   ██║██║██╔═══██╗██╔════╝            │
│  ██║  ███╗██║   ██║██║██║   ██║███████╗            │
│  ██║   ██║██║   ██║██║██║   ██║╚════██║            │
│  ╚██████╔╝╚██████╔╝██║╚██████╔╝███████║            │
│   ╚═════╝  ╚═════╝ ╚═╝ ╚═════╝ ╚══════╝            │
│                                                     │
│             AI-Powered Code Assistant               │
╰─────────────────────────────────────────────────────╯

CODE TOOLS

  F  fix       Debug and fix Python scripts
  X  explain   Understand what code does
  S  simplify  Make code shorter and cleaner
  R  review    Find bugs and bad practices
  T  test      Generate unit tests
  K  secure    Security vulnerability scan
  O  optimize  Performance analysis
  C  convert   Convert between languages
  D  doc       Generate documentation

CONFIGURATION

  A  add       Add MCP server
  L  list      List MCP servers
  M  remove    Remove MCP server
  E  edit      Edit config file
  P  settings  Show current settings
  Q  quit      Exit dbgagent

╭─────────────────────────────────────────────────────╮
│ Enter command:                                      │
╰─────────────────────────────────────────────────────╯
```

Just type the letter (F, X, S, R, T, K, O, C, D, A, L, M, E, P, Q) and press Enter.

### Option 2: Direct commands

If you know what you want to do:

```bash
dbgagent fix myscript.py      # Debug and fix errors
dbgagent explain app.js       # Understand what code does
dbgagent simplify utils.go    # Make code shorter
dbgagent review main.rs       # Find bugs
dbgagent test calculator.py   # Generate tests
dbgagent secure auth.py       # Security scan
dbgagent optimize slow.py     # Performance check
dbgagent convert main.py --to javascript  # Convert languages
dbgagent doc helpers.py       # Generate docs
```

---

## What happens when you debug a script?

Here's what you'll see:

```
$ dbgagent run myscript.py

Running: myscript.py

Script failed (exit 1)

╭────── Traceback ──────╮
│ ZeroDivisionError:    │
│   division by zero    │
╰───────────────────────╯

  Analyzing with LLM... ⠋

╭─── Root Cause ───╮
│ Division by zero │
│ on line 3        │
╰──────────────────╯

╭─── Explanation ──╮
│ You tried to     │
│ divide by zero   │
╰──────────────────╯

╭─── Proposed Fix ─╮
│ Add a check      │
│ before dividing  │
╰──────────────────╯

  Testing fix in sandbox... ⠋

╭─── Sandbox ──────╮
│ Fix verified!    │
╰──────────────────╯

Apply fix to original file? (y/n): y
File updated.
```

---

## Adding MCP servers (advanced)

MCP servers give dbgagent extra information to make better fixes. For example, if your script uses a database, dbgagent can check your database structure to understand the error better.

### Adding a server

Type this in your terminal:

```bash
dbgagent add
```

It will ask you:
1. **Server name** — just a label (like "mydatabase")
2. **Type** — URL (if your server has a web address) or command (if it runs locally)
3. **Triggers** — words that tell dbgagent when to use this server (like "sql,database")

Example:

```
Server name: mydatabase
Type: 1 (URL)
URL: http://localhost:8000/sse
Triggers: sql,database,postgres

Server 'mydatabase' added!
```

### Viewing your servers

```bash
dbgagent list
```

### Removing a server

```bash
dbgagent remove
```

### Editing the config file

```bash
dbgagent config
```

---

## Settings

To see your current setup:

```bash
dbgagent settings
```

This shows:
- Which AI provider you're using
- If your API key is set
- How many MCP servers you have

---

## What can dbgagent do?

### Debug any language
Catches errors in any programming language and fixes them automatically.

### Explain code
Paste any code and get a clear explanation of what it does, line by line.

### Simplify code
Take working but complex code and make it shorter and cleaner.

### Review code
Find bugs, security issues, performance problems, and bad practices.

---

## Examples

### Fix a broken script

```bash
dbgagent fix myscript.py
```

### Explain any code

```bash
dbgagent explain app.js
```

### Simplify any code

```bash
dbgagent simplify utils.go
```

### Review any code

```bash
dbgagent review main.rs
```

### Generate tests

```bash
dbgagent test calculator.py
```

### Security scan

```bash
dbgagent secure auth.py
```

### Performance analysis

```bash
dbgagent optimize slow.py
```

### Convert between languages

```bash
dbgagent convert main.py --to javascript
```

### Generate documentation

```bash
dbgagent doc helpers.py
```

---

## Troubleshooting

### "API key not set"

Run `dbgagent` and choose P (Settings) to check your setup.

### "No .py files found"

Make sure you're in the folder that contains your Python script.

### "MCP package not installed"

If you want to use MCP servers, install with:

```bash
pip install "dbgagent[mcp]"
```

---

## Who is this for?

- **Students** — learn any programming language faster with AI explanations
- **Developers** — debug, review, and clean up code quickly
- **Data scientists** — fix scripts and understand complex pipelines
- **Anyone** who writes code — no more searching Stack Overflow for error messages

---

## How the retry works

dbgagent doesn't give up after one failed fix. Here's what happens:

1. First fix is tested in a safe temporary folder
2. If it fails, the error is saved
3. dbgagent tries again, using the previous error to learn what went wrong
4. This happens up to 3 times
5. If all 3 fixes fail, no changes are made to your file

Your original file is **never modified** until you say "yes" to apply the fix.

---

## Config file format

When you add MCP servers, dbgagent creates a `.dbgagent.json` file in your project folder. Here's what it looks like:

```json
{
  "mcp_servers": {
    "mydatabase": {
      "url": "http://localhost:8000/sse",
      "triggers": ["sql", "database", "postgres"]
    },
    "myfiles": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "."],
      "triggers": ["file", "directory", "path"]
    }
  }
}
```

**Two ways to connect to a server:**

- **URL** — if your server has a web address (like `http://localhost:8000/sse`)
- **Command** — if it runs locally (like `npx @modelcontextprotocol/server-postgres`)

**Triggers** are words that tell dbgagent when to use that server. For example, if your error mentions "sql" or "database", dbgagent will query your database server for more information.

---

## Using dbgagent with other AI tools

dbgagent can also work as a server that other AI tools can call. This means you can use dbgagent inside Claude Desktop, Cursor, or opencode.

### Run the MCP server

```bash
dbgagent-mcp
```

This starts dbgagent as a server that other AI tools can connect to.

### Claude Desktop setup

Add this to your Claude Desktop config file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dbgagent": {
      "command": "dbgagent-mcp"
    }
  }
}
```

### Cursor / opencode setup

Add this to your `opencode.json`:

```json
{
  "mcpServers": {
    "dbgagent": {
      "command": "dbgagent-mcp"
    }
  }
}
```

Once set up, you can ask Claude or Cursor to debug Python scripts, and they'll use dbgagent automatically.

---

## Available MCP servers

Here are some servers you can connect to:

| Type | Server | What it does |
|------|--------|--------------|
| Database | PostgreSQL | Check your database structure |
| Database | SQLite | Check your SQLite database |
| Database | MongoDB | Check your MongoDB collections |
| Database | Redis | Check your Redis cache |
| Files | Filesystem | Read files and folders |
| Files | Git | Check git history and branches |
| Web | Fetch | Get information from websites |
| Web | Brave Search | Search the internet |
| DevOps | GitHub | Check repositories and issues |
| DevOps | Kubernetes | Check your Kubernetes cluster |
| Monitoring | Sentry | Get error tracking info |
| Memory | Memory | Remember previous errors |

---

## Commands summary

| Command | What it does |
|---------|--------------|
| `dbgagent` | Show the interactive menu |
| `dbgagent fix script.py` | Debug and fix Python scripts |
| `dbgagent explain file.js` | Explain what any code does |
| `dbgagent simplify utils.go` | Simplify any code |
| `dbgagent review main.rs` | Review any code for issues |
| `dbgagent test calculator.py` | Generate unit tests |
| `dbgagent secure auth.py` | Security vulnerability scan |
| `dbgagent optimize slow.py` | Performance analysis |
| `dbgagent convert main.py --to js` | Convert between languages |
| `dbgagent doc helpers.py` | Generate documentation |
| `dbgagent add` | Add an MCP server |
| `dbgagent list` | Show your MCP servers |
| `dbgagent remove` | Remove an MCP server |
| `dbgagent edit` | Edit the config file |
| `dbgagent settings` | Show current settings |
| `dbgagent-mcp` | Run as MCP server for other AI tools |

---

## License

MIT — do whatever you want with it.
