An interactive learning game for your terminal. Learn programming concepts through Socratic questioning while waiting for your builds to finish.
Socratic Quiz is a slash command for Claude Code and OpenCode that teaches you programming and computer science concepts through guided questions - not lectures.
Instead of explaining what "idempotency" means, it asks you questions that help you discover and understand the concept yourself.
- Socratic method - Learn through discovery, not memorization
- Concept chaining - Each topic builds on what you've already learned. Learned idempotency? Next session might cover retry strategies, referencing what you know: "Remember idempotency? That's why this matters..."
- 7 categories - CS fundamentals, design patterns, databases, networking, security, JS/TS, system design
- Progress tracking - Streaks, stats, and session history
- Enthusiasm detection - Digs deeper into topics you're excited about
- Interrupt recovery - Resume where you left off if you quit mid-session
git clone https://github.com/briankeefe/socratic-quiz.git
cd socratic-quiz
./install.shThe install script automatically detects whether you have Claude Code and/or OpenCode installed and sets everything up.
If you prefer to install manually:
Claude Code:
mkdir -p ~/.claude/commands ~/.config/socratic-quiz
cp SocraticQuiz.md ~/.claude/commands/
cp validate.py ~/.config/socratic-quiz/OpenCode:
mkdir -p ~/.config/opencode/commands ~/.config/socratic-quiz
cp SocraticQuiz.md ~/.config/opencode/commands/
cp validate.py ~/.config/socratic-quiz/Start a session:
/SocraticQuiz
That's it! Answer the questions and learn.
By default, your progress is saved to:
~/.config/socratic-quiz/state.json
Override with an environment variable:
export SOCRATIC_QUIZ_STATE_DIR=/path/to/your/dir> /SocraticQuiz
Welcome to Socratic Quiz! I'll teach you programming concepts through
interactive questions. Your progress is saved at ~/.config/socratic-quiz/state.json
Let's talk about something fundamental in distributed systems.
What would happen if you ran this code twice?
user.status = "active";
Would the result be different the second time?
> no, it stays active
Exactly! Setting a value to the same thing twice doesn't change anything
after the first time.
Now try this one:
user.loginCount = user.loginCount + 1;
Is this the same? Would running it twice give you the same result?
> no, it would increment twice
Correct! The count increases each time: 1 → 2 → 3...
So we have two types of operations here. The first one - where running it
multiple times gives the same result as running it once - has a name.
Any idea what it might be called?
...
- Topic Selection - Picks a topic based on what you've learned, category balance, and detected interests
- Question Flow - 4-6 questions over ~5 minutes, building from simple to complex
- Wrong Answers - Gives hints first, then explains if needed
- Session End - Shows score, updates streak, offers to continue
- State Persistence - Saves everything for continuity between sessions
| File | Purpose |
|---|---|
SocraticQuiz.md |
The slash command prompt |
validate.py |
State validation/repair script (runs after each session) |
schema.json |
JSON Schema reference for the state file |
install.sh |
Auto-detects Claude Code/OpenCode and installs |
See schema.json for the full schema. Key sections:
- summary - Aggregate stats, streak, category weights
- concepts - Every concept learned with scores and relationships
- sessions - Full history of all sessions with Q&A logs
- interrupted - Resume data if you quit mid-session
Ideas for new categories, topics, or improvements? Open an issue or PR!
MIT