roma debug

ROMA Debug is an investigation-first AI debugger with CLI + web UI. It reads real code, finds root causes across files, returns diffs, and on the web UI can open GitHub PRs.

Comment

Inspiration

Every developer knows the pain: You get a cryptic error in your terminal, you copy it, tab over to Gemini/ChatGPT, paste it, and the AI says, "Can you show me the code?" You then spend 5 minutes copy-pasting file contents back and forth.

I realized that Chatbots are bad debuggers because they are blind. They see the error, but they don't see the environment.

I built ROMA Debug to close that gap. I wanted a tool that lives where the error happens, in the CLI and acts not just as an advisor, but as an Agentic Patcher that reads your local files, understands the context, and proposes safe, apply-ready fixes.

What it does

ROMA is a dual-interface (CLI & Web) debugging agent powered by gemini-3-flash-preview, gemini-2.5-flash, gemini-2.5-flash-lite.

  1. The Interactive CLI:

    • You run roma in your terminal.
    • You paste an error log.
    • ROMA automatically scans your directory, finds the relevant files mentioned in the stack trace, and reads the code context (using AST parsing).
    • It generates a Unified Diff (Red for deletions, Green for additions).
    • It asks: > Apply this fix to src/server.py? [y/n]. If you say yes, it patches your file instantly.

  2. The Web Interface (GitHub Mode):

    • Paste a GitHub Repository URL and an Error Log.
    • ROMA clones the repo (asynchronously) to a sandbox.
    • It analyzes the error within the full context of the repo.
    • It generates a fix ready for a Pull Request.

How we built it

I prioritized speed, safety, and developer experience.

  • The Brain (Gemini-3-flash-preview): I migrated to the new google-genai SDK to leverage Gemini 2.5 Flash. Its high throughput and low latency make it perfect for iterative debugging.
  • The Backend (FastAPI + AsyncIO): I built a robust Python backend. A critical architectural choice was using asyncio.to_thread for heavy operations (like Git cloning or File I/O). This ensures my Health Checks pass and the UI remains responsive even while analyzing large repos.
  • The Safety Layer (Local Diffs): I don't blindly trust the AI. The AI returns the new code, but the Python engine calculates the difflib delta locally. This ensures the user sees exactly what will change before it touches the disk.
  • Context Awareness: I wrote a custom ContextManager that parses stack traces to locate files. If a file is missing locally (e.g., a 404 error caused by a missing route), ROMA detects it and proposes creating the missing file.

Challenges we ran into

This was a bit of battle against system limits.

  1. ** "Blocking" Event Loop:** When I first deployed to Render, my "Clone Repo" task was synchronous. It froze the server, causing Render's 5-second health check to timeout and kill the instance. I had to completely refactor the backend to be non-blocking using asynchronous workers.
  2. The "Passive" AI: Initially, when it shown a 404 error (like a missing favicon), Gemini would say "This is expected behavior." I had to engineer an "Aggressive Fixer" System Prompt, forcing the model to propose code solutions rather than just giving advice.
  3. SDK Deprecation: Halfway through, I hit FutureWarnings because Google deprecated google.generativeai. I had to rewrite my engine to support the modern google-genai client standard.
  4. Hallucinations: The AI would sometimes invent filenames. I implemented a validation layer that checks if filepath exists in the context before proposing a fix, falling back to "General Advice" if the path is invalid.

Accomplishments that we're proud of

  • Zero-Friction Install: pip install -e . and it just works.
  • GitHub-Style Diffs in Terminal: Using the rich library, I replicated the "Red/Green" diff experience inside the command line.
  • Resilience: The system gracefully handles missing API keys, network timeouts, and missing files without crashing.

What we learned

  • Context is King: An LLM with 50 lines of surrounding code is 10x more accurate than an LLM with just an error log.
  • Async is Mandatory: In modern AI agents that perform real-world actions (IO, Git, API calls), synchronous code is a death sentence for UX.
  • Agents need "Tools": Giving the AI the ability to write files turned it from a "Chatbot" into a "Teammate."

What's next for roma debug

  • - adding request IDs and structured logs for every analysis.
  • - adding CI integration so ROMA can automatically investigate failed builds and open PRs.
  • VS Code Extension: Bringing the ROMA experience directly into the IDE sidebar.

Built With

  • ast
  • asyncio
  • click
  • difflib-(python-standard-library)
  • fastapi
  • gemini-2.5-flash
  • gemini-3-flash-preview
  • git
  • github
  • google-genai
  • gunicorn
  • python-3.10+
  • react
  • react.js
  • render
  • rich-(for-terminal-ui-and-diffs)
  • syntax
  • tailwind-css
  • uvicorn
Share this project:

Updates