CodeLens AI: Voice & Visual Python Debugger for Alexa+

Watch Python run line by line and ask Alexa to explain errors, inspect variables, and test and validate fixes out loud. Powered by a secure sandbox and a self-hosted MCP server.

Comment

Inspiration

Beginners don't fail because Python is hard. They fail because they can't see what their code is doing, and error messages are scary. We wanted a debugger you can talk to: run your code, ask "why did it crash?" out loud, and get an answer built from what actually happened, not a guess.

What it does

CodeLens AI lets anyone, from an 8-year-old to a professional developer, watch their Python run and ask about it with their voice.

  • Ask Alexa about your code. "Alexa, run my code." "Why did it crash?" "What is total?" "Fix it." "Test the fix." Alexa answers in one or two spoken sentences, e.g. "The program crashed with an IndexError on line 4: list index out of range."
  • Autopilot. Say "debug my code" and Alexa plans and chains the tools herself: run → diagnose → propose a fix → validate it with tests generated from the run.
  • See every step. A sandbox records every line, call, return, exception and variable, then replays the run beside the code in three views:
    • Robo Lab for kids: plain-English sentences for each step, values shown as labeled boxes, "New idea" cards, read-aloud, Blockly blocks, 8 challenges and a turtle drawing stage.
    • Game mode: variable cards, object arrows, and a predict-the-next-line game with XP and streaks.
    • Classic: editor, variables table, call stack, timeline and breakpoints.
  • Fix with evidence. Fixes are proposed as a unified diff and only called "fixed" after real pytest passes in a fresh sandbox, including regression tests generated from the calls that worked.
  • Lexi, Alexa's on-screen character, speaks answers and flies to the code to point at the line being discussed.

How we built it

  • Self-hosted MCP server (MCP Python SDK, Streamable HTTP, protocol 2025-11-25+) exposing 19 tools, including six voice-ready tools that return a short speech string plus structured data. Served at /mcp, protected by an access code / bearer token with DNS-rebinding protection on.
  • Alexa+ simulator in React: an Echo Show-style screen with voice input and spoken answers (Web Speech API), driven by an MCP client we wrote from scratch. A live panel shows every initialize, tools/list and tools/call on the wire.
  • Backend: FastAPI plus a sys.settrace worker that builds an evidence trace. Explanations come from the syntax tree plus recorded values. When an LLM (Gemini, Nebius or local Ollama) is used, its claims are checked against real line numbers, variable names and values before they are shown. With no AI key, a deterministic offline engine still explains and fixes common bugs.
  • Sandbox: every run gets its own Docker container: no network, read-only filesystem, all capabilities dropped, non-root, 256 MB memory, half a CPU, 64 processes, 5-second deadline.
  • Frontend: React, TypeScript, Monaco, Tailwind, Blockly.
  • REA (reverse-engineering toolkit) was used to study Scratch's open-source pen engine, which shaped our turtle drawing stage.
  • Testing: 140+ backend tests (including MCP over Streamable HTTP end to end), frontend unit tests and a headless-browser e2e suite, all running in GitHub Actions CI.

Challenges we ran into

  • Mounting MCP inside FastAPI: the Streamable HTTP session manager can only run() once per instance, which broke every restart in our test suite. We wrote a small ASGI wrapper that rebuilds the endpoint on each startup.
  • SDK changes: the MCP SDK's 1.x → 2.x rename (FastMCP → MCPServer), and host-header protection that blocked public tunnel URLs until we configured allowed hosts.
  • Keeping AI honest: we built a fact-checker so the model can't mention lines or variables that don't exist in the trace.
  • Safe inspection: reading variables never calls user __repr__/__getattr__, and long runs keep the first 300 and latest 700 steps so the crash is always visible.

Accomplishments that we're proud of

  • Every spoken answer is grounded in a real recorded run.
  • An 8-year-old and a professional can use the same tool, just in different views.
  • A fix is never "done" until real tests pass in a fresh sandbox.
  • Fully open source (MIT), works offline with no AI key, and deploys with one command.

What we learned

MCP's surface is small enough that a useful client fits in a few messages, which made a browser-based Alexa+ simulator practical. Voice changes what a good answer looks like: one or two sentences with a concrete value beats a paragraph. And grounding beats cleverness: people trust "total is 247" far more than a fluent guess.

What's next for CodeLens AI

  • Connect and test the MCP endpoint on a live Alexa+ device, and publish it to MCP registries.
  • Support more languages beyond Python, and non-English explanations for kids.
  • A classroom mode with teacher dashboards and shared challenges.
  • Postgres and Redis for multi-replica hosting.

Built With

Share this project:

Updates

Submission history