Inspiration

Everyone is vibe coding now. You prompt it, it works, you ship it. Then a teammate asks "how does this actually work?" and you realise you're reading your own code for the first time.

AI writes code much faster than anyone can read it, and there's no proper way to understand a codebase except reading it top to bottom and hoping. The same problem hits anyone joining a new team: hundreds of functions, no walkthrough, no idea where to start. We wanted something that turns your own repo into practice: answering questions about the real code and hunting for real-looking bugs, until you could explain it to someone else.

What it does

Import any public GitHub repo (Python, JavaScript, TypeScript or TSX). CodeWiz parses every function without ever running the code, builds the call graph and ranks functions by how much of the repo depends on them.
See the important code: an overview map from entry points to core logic, data access and helpers, plus a call map for any single function.
Quiz. The AI picks important functions you haven't reviewed and asks questions about the real code. You choose multiple choice (easier, good for beginners) or written answers (graded against a rubric). Every answer comes with the reason it's right and the industry practice behind it, and you can ask for more questions.
Bug drills. Realistic bugs are planted in a copy of the function. You click the line you think is wrong and explain why. Stuck? Reveal the bugs, and an AI tutor explains each one, asks you to explain it back, and tries a different explanation until it clicks.
Understanding score for every function, and a skill profile that makes your next drills plant more of the bug types you miss.

How we built it

Next.js 15 (App Router, strict TypeScript) on Vercel, with Tailwind and shadcn/ui.
Supabase: Postgres with Row Level Security on every table (owner and a 2FA session), plus TOTP two-factor sign-in for every account. Answer keys live in a table that signed-in users have no read policy for, so rubrics and planted bugs never reach the browser before you submit.
web-tree-sitter for static parsing. Each function gets an importance score from how many functions call it, how many it calls, how many branches it has (capped at 10), and whether it touches data (1 if it does, 0 if not):

$$ \text{importance} = 3\ln(1 + \text{callers}) + 2 \cdot \text{data} + \frac{\min(\text{branches}, 10)}{10} + 0.5\ln(1 + \text{callees}) $$

Gemini through one typed wrapper: every AI step asks for JSON only, is validated with zod, retries once with the validation errors, and fails cleanly. We treat AI output as untrusted. Every line number it returns is checked against the function's range, and repo code is wrapped in delimiters and labelled as data, not instructions.
Verified bug planting. A planted bug only counts if it passes every check:
1. the changed code has the same line count as the original;
2. the diff touches exactly the lines the model listed;
3. the changed code still parses;
4. a second AI step confirms the behaviour really changes.
Real-bug check. If you flag a line with no planted bug, an agent with tool calls (read a function, find its callers, search the repo) checks whether you found a real bug, and must cite evidence that exists.
Scoring. Each part is between 0 and 1. The drill part rewards catches and good explanations, and takes 0.1 off for each false alarm:

$$ \text{drill} = \min\left(1, \max\left(0,\; 0.7 \cdot \frac{\text{caught}}{\text{planted}} + 0.3 \cdot \text{explanation} - 0.1 \cdot \text{false alarms}\right)\right) $$

The understanding score weights the quiz, the drill and how well you defend your choices on suggestion cards. Parts with no data are left out, and the remaining weights are scaled up:

$$ \text{score} = 100 \cdot \frac{0.4 \cdot \text{quiz} + 0.4 \cdot \text{drill} + 0.2 \cdot \text{defend}}{\text{total weight of the parts with data}} $$

We published 6 reusable pieces as Devmarketplace code gigs: a GitHub repo indexer, a verified bug planter, Supabase TOTP 2FA, typed LLM JSON calls, a package registry verifier and a React call map.
We used AI coding assistants (including Claude Code) throughout, as listed in AI_DISCLOSURE.md.

Challenges we ran into

Making AI-planted bugs trustworthy. Models love to "fix" the code they were asked to break, change extra lines or produce code that doesn't parse. The four-step verification above came from watching drills fail.
Serverless memory. Parsing big repos with tree-sitter ran out of memory on Vercel until we pinned the runtime to Node 22 and capped imports.
Race conditions. Reloading mid-round could generate the same quiz twice. We added a claim lock so only one request writes a quiz or drill, with stale-claim takeover.
Keeping secrets secret. It's easy to leak an answer key through an API response or a readable column. Every view is built server-side and checked so keys appear only after an answer.
Readable graphs. Our first call map was a hairball. We rebuilt it as labelled columns (called by → selected → calls) and an overview of only the most important functions.
Email limits. Supabase's built-in mailer allows two emails an hour, so sign-up confirmations and password resets needed custom SMTP.

What we learned

Treat every AI output like user input: validate it, check it against the code and have a fallback.
Static analysis gets you surprisingly far: callers, branches and data access make a solid importance signal without running anything.
"Did you understand it?" is best measured by asking the learner to explain it back, which is why the bug tutor works that way.

What's next

NotebookLM changed how people learn from documents; we want to do that for code:

Flashcards generated from your own functions
An audio overview: a podcast-style tour of your repo
Mind maps of how the code fits together
Onboarding guides for new teammates
A pull request check that makes sure you understand a change before you merge it