dbgagent 0.5.1

AI-powered Python debugger — run a broken script, get root cause, explanation, and fix

dbgagent

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

Built by Aryan Tyagi 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:

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 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:

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:

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:

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

dbgagent list

Removing a server

dbgagent remove

Editing the config file

dbgagent config

---

Settings

To see your current setup:

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

dbgagent fix myscript.py

Explain any code

dbgagent explain app.js

Simplify any code

dbgagent simplify utils.go

Review any code

dbgagent review main.rs

Generate tests

dbgagent test calculator.py

Security scan

dbgagent secure auth.py

Performance analysis

dbgagent optimize slow.py

Convert between languages

dbgagent convert main.py --to javascript

Generate documentation

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:

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:

{
  "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

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):

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

Cursor / opencode setup

Add this to your opencode.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.