⚡ ChipTutor

Learn how a CPU is built — by building one. ChipTutor is a local web app where you drag logic gates onto a board, wire them up, flip switches and watch the bulbs light, while a Socratic AI tutor guides you one step at a time. Every circuit you build is shown as live Verilog (HDL) so you graduate from dragging blocks to reading real hardware code.

The curriculum climbs gradually from a single wire all the way to a tiny processor — no leaps, each step built only from parts you made in the step before.

✨ Features

• Drag-and-drop circuit board with a live logic simulator (bulbs light instantly as you flip switches).
• Live Verilog panel — see the HDL for whatever you've wired, updating as you build.
• Socratic AI tutor that sets challenges, watches your board, hints when you're stuck, and confirms when you solve a level.
• 22-level curriculum, gates → CPU, split into 7 tiers.
• The machine grades correctness (truth-table comparison), so the tutor stays focused on teaching, never on grading logic.

🎓 The path (22 levels)

Tier	Theme	Levels
1	Signals & Gates	wire · NOT · AND · OR
2	Composing Gates	NAND · NOR · XOR (built from gates)
3	Routing Data	multiplexer · demultiplexer
4	Arithmetic	half adder · full adder · 2-bit adder
5	The ALU	1-bit ALU · ALU + zero flag
6	Memory & Time	clock & flip-flop · register · toggling bit · counter
7	Becoming a CPU	program counter · instruction decode · datapath · tiny CPU

15 levels auto-grade by truth table; the 7 sequential/CPU levels are open-ended, tutor-guided free builds.

🚀 Run

Requires Node.js. No npm dependencies — the app uses only Node built-ins and the browser.

node server.js

Then open http://localhost:5179. (Override the port with PORT=8080 node server.js.)

🧠 The tutor brain

The tutor is powered by the local claude CLI (Claude Code), which authenticates via your Claude subscription — no API key required. If the claude CLI isn't installed, the board, simulator, grading, and Verilog panel all still work; only the chat tutor goes into a graceful offline mode.

🧪 Tests

node --test              # unit tests for the simulator, HDL generator, and tutor bridge
node verify_targets.mjs  # re-derives every gradable level's answer key and checks the curriculum

The HDL generator's output is also checked against Icarus Verilog (iverilog) to confirm the generated Verilog actually compiles.

🏗️ How it works

 Browser (the game)            Local server (Node)          Claude Code
 ┌──────────────────┐  HTTP   ┌────────────────────┐  runs ┌────────────┐
 │ drag-drop board  │ ──────► │ POST /tutor         │ ────► │ claude -p  │
 │ live simulator   │ ◄────── │  build prompt,      │ ◄──── │ (your sub) │
 │ Verilog panel    │  JSON   │  call claude, parse │       └────────────┘
 │ tutor chat       │         │ + serve curriculum  │
 └──────────────────┘         └────────────────────┘

• public/ — the single-page game: board.js (drag/drop + wiring), simulator.js (logic engine), hdl.js (circuit → Verilog), tutor.js (chat + level progression).
• server.js — static server + the /tutor bridge to the claude CLI.
• curriculum/ — the levels, split one file per tier; curriculum-loader.js merges them in order.
• test/ — unit tests.

License

MIT