itworkslocally.tech

AI debugging assistant that explains why your code works locally but fails in production - in a language you actually understand.

Comment

💡 Inspiration

We’ve all been there: it’s 3 AM, the code works perfectly on localhost, but production is on fire. You’re staring at cryptic logs, wondering if it’s a Node version mismatch, a missing environment variable, or just bad luck.

We realized that "It works on my machine" isn't a valid excuse—it's a universal problem. We built It Works Locally to bridge the gap between your local environment and production reality, turning hours of debugging into seconds of clarity.

🤖 What it does

It Works Locally is an AI debugging assistant that analyzes environment mismatches. You paste your error logs and describe your environments, and it identifies the root cause.

The twist? It adapts to you.

  • Intern Mode: Explains with analogies, patience, and humor.
  • Junior Mode: Step-by-step educational guidance.
  • Senior Mode: Concise, technical, root-cause focused.

⚙️ How we built it

We prioritized a modern stack for speed and a polished developer experience:

  • Frontend: React + TypeScript + Vite (for speed)
  • Styling: Tailwind CSS + shadcn/ui (for polish)
  • AI: Gemini 2.0 Flash (for sub-second analysis and context window)
  • Voice: ElevenLabs Text-to-Speech (for audio explanations)
  • Deployment: Vercel Edge Functions

🧠 Challenges we ran into

  • Taming the AI: Gemini sometimes slipped into technical jargon even in "Intern Mode." We fixed this by implementing strict JSON schema enforcement and regex cleaning to strip markdown artifacts.
  • Audio Memory Leaks: Rapidly toggling voice explanations caused overlapping audio tracks. We had to implement a custom React hook to properly manage audio cleanup and state.

🏆 Accomplishments we're proud of

  • Copy as GitHub Issue: We didn't just want to explain the error; we wanted to fix the workflow. Our "Export to Issue" button formats the AI's findings into a clean Markdown template, ready to paste into GitHub.
  • True Expertise Adaptation: The difference between our modes isn't just a gimmick. "Intern mode" genuinely teaches, while "Senior mode" respects your time.
  • Production Polish: We didn't want a flimsy prototype. We shipped with a custom domain (.tech), mobile responsiveness, keyboard shortcuts (Ctrl+Enter), and smooth Framer Motion animations.

📚 What we learned

  • Prompt Engineering is 80% of the work: Getting the AI to be accurate is easy; getting it to have personality and follow strict formatting required sophisticated prompting.
  • DX Matters: Features like keyboard shortcuts and dark mode aren't optional extras—they are expectations for developer tools.
  • Vercel Edge Functions: These were a game-changer for keeping the AI response times snappy globally.

🚀 What's next for It Works Locally

  • VS Code Extension: Bringing the analysis directly into the IDE so you never have to context-switch.
  • Browser Extension: A "Right-click to Analyze" feature for logs in the Chrome DevTools console.
  • Team Knowledge Base: Storing solved errors so if a teammate hits the same bug next week, the solution is already there.

Built With

Share this project:

Updates