"I cannot teach anybody anything. I can only make them think." — Socrates
An autonomous retro-arcade Socratic AI coding coach for beginners that refuses to give solutions away.
Teaching computational thinking through guided inquiry, adaptive hint ladders, sandboxed execution, and autonomy scoring.
🎮 Live Demo • 📋 Devpost Submission • ✨ Features • ⚡ Quick Start • 🏛️ Socratic Philosophy
ThinkCode runs 100% offline out-of-the-box using an integrated mock backend, procedural WebAudio synth, and in-browser Web Worker execution engine. No API keys or external services required!
# 1. Clone the repository
git clone https://github.com/ouzejop/thinkcode.git
cd thinkcode
# 2. Install dependencies
npm install
# 3. Start the application
npm run dev
# 4. Open in browser
# http://localhost:5173# Runs contrast verification, retro style validation, pure code runner, and mockApi contract tests
npm test
# Typecheck with TypeScript
npm run typecheckWhen beginners learn to code today, traditional AI assistants (ChatGPT, Copilot) provide complete, copy-pasteable solutions to every syntax error or logic challenge.
❌ TRADITIONAL AI (Passive Consumption):
Beginner gets stuck ──> AI generates 50 lines ──> Copy & Paste ──> Zero Learning
✅ THINKCODE (Active Deduction):
Beginner gets stuck ──> Socrates asks targeted questions ──> Adaptive Hint Ladder ──> Genuine Understanding!
This creates a dangerous illusion of competence: learners feel productive, but cannot write five lines of code when staring at a blank file.
ThinkCode fixes this. It acts as Socrates—a wise, encouraging retro-arcade mentor that diagnoses errors, asks guiding questions, and rewards autonomy and independence.
- Analyzes broken code and test failures without ever writing the answer for the learner.
- Asks targeted questions to prompt reflection: "What does your accumulator variable contain after the first loop pass?"
- Embedded directly in the IDE terminal and the Hint Ladder drawer.
- Rung 1 — Concept: Explains the theoretical concept behind the problem (e.g. accumulator pattern, boundary indices).
- Rung 2 — Socratic Question: Pinpoints the logical discrepancy in the user's specific attempt.
- Rung 3 — Algorithm / Pseudocode: Provides structured logic steps without language syntax.
- Rung 4 — Solution Reveal (with penalty): Unlocks the full solution, but triggers a mandatory Rematch variant with altered constraints to prove genuine mastery!
- Pure JavaScript execution inside dedicated Web Workers (
runner.worker.ts). - Watchdog Timeout: Strict 2-second timeout preventing infinite loops (
while(true)) from freezing the browser UI. - Security Shadowing: Shadowed globals (
fetch,XMLHttpRequest,importScripts) ensure safe, leak-free execution. - Real-time ANSI terminal logging and automated test assertion runners.
- Unlike standard platforms that rank by typing speed (encouraging AI copy-pasting), ThinkCode ranks players by Autonomy Score, Zero-Reveal clears, and S-Ranks!
- Dual views: Course-wide ranking & Per-exercise leaderboard.
- Real-time player placement against 12 simulated CPU peers + personal pinned record.
- Rule of the 3 Zones:
ZONE WORK(80% screen): Clean, accessible Atkinson Hyperlegible typography with maximum contrast.ZONE ARCADE: Cartridge shelf, hint ladder, stage clears, and retro sounds.ZONE TOUCH: Retro badges, status indicators, and SVG pixel sprites.
- 3 Retro Style Levels: Switch between
Clean(modern soft),Balanced(subtle arcade), andArcade(full 8-bit styling) via settings. - WebAudio Procedural Synthesizer: Generates authentic 8-bit chimes and fanfare on-the-fly with zero audio asset downloads.
- Automated Contrast Compliance: 30/30 color pairs verified to satisfy strict WCAG AAA contrast ratios (≥ 7:1 for text).
thinkcode/
├── src/
│ ├── api/ # Unified API layer (types.ts, client.ts, mockApi, httpApi)
│ ├── app/ # Application entry, layout & router
│ ├── engine/ # Web Worker sandbox, LanguageRunner, runner.core.ts
│ ├── features/
│ │ ├── title/ # Neo-arcade boot sequence & title screen
│ │ ├── onboarding/ # 5-step interactive onboarding & diagnostic placement
│ │ ├── shelf/ # Interactive cartridge shelves (Variables, Conditions, Loops)
│ │ ├── workstation/ # 3-column accessible IDE (Mission, Tests, Editor, Console, Ladder)
│ │ ├── scores/ # Accessible Dual High Scores table with CPU peers & filters
│ │ ├── report/ # Progression save file, rank radar & independence metrics
│ │ ├── about/ # Pedagogical manifesto (Typical AI vs ThinkCode)
│ │ └── settings/ # Theme switcher, retro levels, audio synth & profile controls
│ ├── lib/ # Procedural WebAudio synth (sfx.ts), contrast checker, shortcuts
│ ├── sprites/ # Custom 12x12 & 16x16 scalable SVG pixel matrices
│ ├── stores/ # Zustand stores (profile, settings, session, leaderboard)
│ ├── styles/ # Design tokens, themes (Lavender/Night), retro levels, 3-zone styles
│ └── ui/ # Accessible design system (CodeEditor, Panel, Led, Stepper, Modal)
├── server/ # Optional Express + OpenRouter AI microservice
├── scripts/ # verifyAll.mjs (Contrast, Retro CSS, Runner & Contract tests)
└── README.md
ThinkCode includes an automated test verification harness (verifyAll.mjs) ensuring zero regressions and strict compliance:
--- THINKCODE TEST & INTEGRITY VERIFICATION ---
[1/7] Testing Theme Contrast Ratios...
✓ All 30 theme contrast pairs satisfy strict accessibility thresholds (≥ 7:1).
[2/7] Testing Retro Style CSS Rules...
✓ Retro styles (Clean, Balanced, Arcade) strictly conform to specification.
[3/7] Testing Leaderboard Generation...
✓ Leaderboard sorting and YOU entry placement verified.
[4/7] Testing Placement Quiz Evaluation...
✓ Placement evaluation logic verified.
[5/7] Testing Pure Code Runner Core...
✓ Code execution sandbox and test assertions verified.
[6/7] Testing Hint Ladder Reducer...
✓ Ladder state reducer and rung transitions verified.
[7/7] Testing mockApi Contract Compliance...
✓ mockApi strictly complies with the ThinkCode contract.
🎉 ALL 7/7 TEST SUITES PASSED (68 assertions, 0 failures)!
In compliance with the Beginner's Paradise – FirstCommit hackathon rules:
- AI Tools Used: Google Antigravity & LLM models were utilized as an agile brainstorming partner, pair programmer, and code reviewer.
- Human Work & Authorship: All architectural blueprints, Socratic pedagogical guardrails, custom Web Worker sandboxing, WebAudio synthesis algorithms, design tokens, and comprehensive verification test suites were engineered, integrated, and validated specifically for this hackathon.
Distributed under the MIT License. See LICENSE for more information.