How a student developer built a provider-agnostic, sandbox-safe CLI tool that scans repos for technical debt, AI-refactors messy files, and visualizes it all in a local dark-mode dashboard.
I want to tell you about the moment I realized I was scared to show senior developers my code.
I'd built something I was genuinely proud of. A real tool. A CLI that scans your repository, calculates how much technical debt is buried in it, uses AI to refactor the worst files, and then generates a dark-mode HTML dashboard right on your machine — no server, no account, no data leaving your computer.
But before I posted it anywhere, I sat there thinking: "What if they look at my code and just laugh?"
I'm 16. This is my first production-grade project. And I shipped it anyway.
This is the story of what I built, why I built it, and an honest invitation for you to break it.
The Problem I Was Trying to Solve
Every developer I've watched on YouTube, every open-source codebase I've dug through — they all have the same thing hiding in them. Files nobody wants to touch. Functions that grew from 10 lines to 300 lines because nobody had time to clean them up. Variables named x2, tempFinal, useThisOne.
Technical debt is real, it's everywhere, and nobody has a great way to see it clearly before it becomes a crisis.
Most existing tools either:
- Just lint your code (tells you what's wrong, doesn't fix it)
- Send your code to the cloud (a privacy nightmare for companies)
- Require complex setup and configuration before you get any value
I wanted to build something that felt like a brilliant, paranoid senior engineer who audits your codebase, fixes the worst parts in a safe sandbox, and then hands you a clean visual report — all in one command.
What Tech Debt Agent Actually Does
🔍 The Auditor — Brutal, Honest, Quantified
When you point it at a directory, it doesn't just flag style issues. It looks for:
- Security traps (hardcoded secrets, unsafe eval usage, SQL injection patterns)
- Logic debt (deeply nested conditions, duplicated logic blocks)
- Maintenance debt (dead code, overly complex functions, missing error handling)
And then it calculates something I call Debt Hours — an estimated number of hours a developer would need to spend cleaning up each file. This turns an abstract feeling ("this codebase feels messy") into a concrete, prioritized number.
🤖 The Sandbox Fixer — AI Refactoring With Zero Risk
This is the part I'm most proud of, and the design decision I think matters most:
The agent never touches your original code. Ever.
Instead, it dynamically creates a fixed_code_output/ folder. Every file it refactors goes in there — clean, restructured, with comments explaining what it changed and why. Your original repo stays exactly as it was.
You can diff the files, cherry-pick the improvements you like, or throw the whole output away. No risk. No surprises.
📊 The Visual Dashboard — Because Numbers Need Context
After the audit, it generates a single-file dark-mode HTML dashboard and automatically opens it in your browser.
No framework. No server. No internet connection required. Just one .html file you can share with your team, archive, or just close when you're done.
It shows debt scores per file, a breakdown by debt type, the worst offenders, and overall codebase health — all in one place.
🔒 100% Offline Support — Your Code Stays Yours
This is the feature that I think matters most for professional developers and companies.
Tech Debt Agent is provider-agnostic. You can run it with:
- OpenAI / Anthropic APIs — for convenience
- Ollama — for fully local, offline inference
- LM Studio — for a GUI-based local model setup
When you run it with Ollama, zero bytes of your code touch the internet. For teams working on proprietary codebases, this isn't a nice-to-have. It's a requirement.
How to Try It Right Now
# Clone the repo
git clone https://github.com/prithvi-1106/tech-debt-agent
cd tech-debt-agent
# Install globally
pip install -e .
# Run an audit on any directory
techdebt audit ./your-messy-project
# Or run fully offline with Ollama
techdebt audit ./your-messy-project --provider ollama --model codellama
That's it. No config file to set up first. No account to create. It just runs.
What I Learned Building This
1. The sandbox idea was the hardest design decision.
My first version modified files in place. I showed it to one developer online and the first thing they said was: "I would never run this on a real project." That feedback completely changed the architecture. The fixed_code_output/ quarantine folder was born from that one comment.
2. Provider-agnostic design is harder than it sounds.
Abstracting over different LLM providers — cloud APIs, Ollama's local API, LM Studio — meant building a clean provider interface early. It forced me to write better, more modular Python than I ever had before.
3. The dashboard made everything feel real.
Before the HTML dashboard, this was just a CLI tool that printed colored text. The moment I added the visual output — dark mode, debt scores, color-coded files — it stopped feeling like a script and started feeling like a product. Presentation is part of the tool.
What I'm Asking From You
I'm not asking you to star the repo (though I won't say no).
I'm asking you to run it on your messiest directory and tell me one of these things:
- Something that broke
- Something that's missing
- Something that could be smarter
- Something you actually liked
Open a GitHub issue, leave a comment below, or reach out directly. Every single piece of feedback will go into the next version.
I'm 16. I'm learning in public. And I built something I genuinely believe is useful.
Prove me right. Or prove me wrong. Either way, I want to know.
GitHub: [https://github.com/prithvi-1106/tech-debt-agent]
*If you work on a team with a codebase that has genuine debt problems, I'd especially love to hear from you. I want to understand whether the Debt Hours metric actually resonates with how real teams think about this problem.