TraceTutor AI

TraceTutor AI helps students understand why code fails using real test runs, misconception tracking, and step-by-step AI hints—without giving away the final fix.

Comment

Inspiration

AI coding assistants are great at fixing code, but for students that can become the problem. When a learner immediately receives the corrected solution, they may pass the task without understanding why their original code failed.

I wanted to build something with the opposite philosophy:

“Don’t fix my code. Teach me why it broke.”

That idea became TraceTutor AI — a debugging tutor that combines real code execution with Socratic AI guidance so students can discover the fix themselves.

What it does

TraceTutor AI provides interactive JavaScript debugging challenges where students:

  1. Inspect and edit buggy code.
  2. Run real deterministic test cases.
  3. See expected vs. received values and runtime symptoms.
  4. Request progressive Socratic AI hints instead of receiving the final solution.
  5. Fix the code themselves.
  6. Build a history of misconceptions and concept mastery.

The tutor uses three progressive hint levels:

  • Hint 1: Conceptual question
  • Hint 2: Small analogous counterexample
  • Hint 3: Focuses attention on the relevant logic without revealing the corrected code

TraceTutor currently includes five debugging challenges covering:

  • Array bounds and loops
  • Conditionals and equality
  • Missing return paths
  • Async JavaScript
  • State and accumulator mistakes

How I built it

TraceTutor AI is built with Next.js, React, TypeScript, Tailwind CSS, and Google Gemini.

Student code is executed inside an isolated browser Web Worker. The worker runs deterministic test cases and reports real pass/fail results, expected values, received values, and runtime errors.

The AI does not decide whether code is correct.

Only the deterministic test runner determines pass or fail.

When tests fail, a server-side Next.js API route sends the challenge context, student code, and actual test evidence to Gemini 3.5 Flash-Lite using the Gemini Interactions API.

Gemini returns structured tutoring data including:

  • detected misconception
  • runtime observation
  • Socratic hint
  • guiding focus
  • reflection question

Additional validation and spoiler-detection guardrails reject responses that attempt to reveal the corrected solution.

If the Gemini API is unavailable, TraceTutor automatically falls back to built-in Socratic hints so the learning flow still works.

Progress and misconception tracking

TraceTutor stores learning progress locally in the browser.

It tracks:

  • attempts
  • failed runs
  • successful runs
  • hints used before the first successful solve
  • self-corrected bugs
  • detected misconceptions
  • concept mastery

The mastery score is intentionally simple and explainable. Solving independently receives the highest score, while using progressive hints reduces the score for that solve episode.

Hints explored after a challenge has already been solved do not retroactively reduce previous mastery.

Challenges I faced

One major challenge was safely executing arbitrary student JavaScript without freezing the application.

I solved this using an isolated Web Worker with execution timeouts.

Another challenge was preventing the AI tutor from simply revealing the answer. I combined prompt-level restrictions, structured output validation, and spoiler-detection checks to keep the tutor focused on questions and reasoning.

I also had to design progress tracking so later experimentation with hints would not incorrectly reduce mastery from an earlier independent solution.

Accomplishments that I'm proud of

  • Built a real deterministic JavaScript test runner instead of displaying simulated results
  • Added isolated Web Worker execution with timeout protection
  • Integrated real Gemini-powered Socratic tutoring
  • Created progressive three-level AI hints
  • Added misconception detection and mastery tracking
  • Built five reusable debugging challenges
  • Added graceful offline/fallback tutoring
  • Created a full challenge catalog and analytics dashboard
  • Reached 30 passing automated tests with a clean production build

What I learned

Building TraceTutor taught me that AI in education can be more useful when it provides less of the final answer and more of the reasoning path.

I also learned a lot about sandboxed browser execution, structured LLM responses, prompt guardrails, state persistence, and designing AI features where deterministic software remains the source of truth.

What's next

Future versions could include:

  • More programming languages
  • User accounts and cloud-synced progress
  • Personalized challenge recommendations
  • More advanced debugging scenarios
  • Teacher dashboards
  • Student-created debugging exercises
  • Longer-term misconception analytics

Built With

Share this project:

Updates

Submission history