term-ai-debugger

A multimodal Gemini 2.0 Flash terminal agent that explains cryptic errors, generates CLI commands from natural language, and analyzes screenshots to guide developers.

Comment

💡 Inspiration

As the Web Development Frontend Coordinator at DSC SIT Pune, I often see first-year engineering students get paralyzed by cryptic terminal errors. I wanted to create a tool that doesn't just "fix" the code, but explains the logic behind the failure, turning every terminal crash into a personal tutoring session.

🛠️ What it does

Term-AI-Debugger is an agentic AI terminal assistant that:

  • Intercepts Errors: Automatically captures exit codes and tracebacks in real-time.
  • Smart Analysis: Uses Gemini 2.0 Flash to provide a "Fix Command" and a "Plain English Explanation."
  • Ask Mode: Converts natural language (e.g., "ask create a folder on desktop") into precise shell commands.
  • Command Explain: Breaks down complex shell scripts so users understand the risks before running them.

⚙️ How we built it

  • Intelligence: Powered by Gemini 2.0 Flash via the Vertex AI SDK for high-speed, low-latency reasoning.
  • Logic: Built with Python, utilizing custom interactive shell loops to wrap standard subprocess execution.
  • Cloud Infrastructure: The backend is containerized with Docker and deployed on Google Cloud Run to handle API requests securely and scalably.

🚧 Challenges we ran into

The biggest hurdle was handling Google Cloud authentication across different environments. Debugging 401 Unauthorized and 404 Model Not Found errors at 1:00 AM while ensuring the local CLI could talk to the Vertex AI project was a massive learning curve in IAM roles and Service Account management.

🏆 Accomplishments that we're proud of

I am incredibly proud of successfully deploying the backend to Cloud Run. Seeing the debugger work "live" on my terminal while the logic was being processed in the cloud was a major technical milestone for me.

📚 What we learned

I learned the intricacies of the Gemini API, specifically how to structure prompts for agentic behavior. I also gained significant experience in Dockerizing Python applications and managing environment variables in a production setting.

🚀 What's next for Term-AI-Debugger

I plan to build a VS Code Extension version of this tool and add multimodal support, allowing the agent to analyze screenshots of the terminal or IDE to debug visual errors like CSS layout shifts or frontend build failures.

Built With

Share this project:

Updates

Submission history