You use ChatGPT, Claude, or Copilot to learn something new. It explains clearly. You think "Got it!" and move on.
Two days later? You may struggle to recall or apply it.
A conversation alone may leave gaps in the learning workflow:
- β No active recall β you read answers, don't retrieve from memory
- β No spaced repetition β you learn once, never review
- β No mastery validation β "I understand" β "I can explain it back"
Learning isn't consuming information. It's proving you retained it.
Tutor is a file-based template that guides an AI coding assistant through diagnosis, teaching, quizzes, review scheduling, and persistent learner state.
Evidence boundary: These are workflow features, not demonstrated learning gains. This README does not present a controlled evaluation of Tutor, and does not claim that the template reproduces published tutoring effect sizes or guarantees mastery.
Instead of this:
You: "Explain Python decorators"
AI: [Long explanation]
You: "Thanks!" [Never touches it again]
The intended interaction looks like this:
Tutor: "Before I explain decorators, can you recall what a higher-order function is?"
You: [Struggles to remember]
Tutor: "Let's review that first. No skipping prerequisites."
[After solid review]
Tutor: "Now, explain decorators back to me in your own words."
You: [Feynman-style explanation]
Tutor: "Good. I'll quiz you on this in 6 days."
| Workflow concern | Tutor's approach | What this does not establish |
|---|---|---|
| Unstructured study sessions | Diagnose β Teach β Quiz β Review | Better outcomes than a comparison group |
| Review scheduling | SM-2 spaced repetition | An optimal schedule for every learner |
| Missing prerequisites | Concept paths and prerequisite gates | That an AI assessment is always correct |
| Passive answer reading | Retrieval and explain-back prompts | Durable mastery from one good answer |
| State lost between sessions | File-based progress and review history | Independent verification of learning gains |
1οΈβ£ Onboard 2οΈβ£ Diagnose 3οΈβ£ Teach 4οΈβ£ Quiz
βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ
β Build your β β β Find real β β β Fill ONLY β β β Active β
β learning β β gaps with β β the gaps β β recall + β
β profile β β questions β β step by stepβ β Feynman testβ
βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ
β
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
βΌ
7οΈβ£ Evolve 6οΈβ£ Mastery Gate 5οΈβ£ Schedule Review
βββββββββββββββ βββββββββββββββ βββββββββββββββ
β System β β β Don't skip β β β Spaced β
β learns from β β weak β β repetition β
β mistakes β β prerequisitesβ β (SM-2) β
βββββββββββββββ βββββββββββββββ βββββββββββββββ
The 7-Step Mastery Loop:
- Onboard β Tell Tutor your goals, background, and learning pace
- Diagnose β Socratic questioning finds your real starting point
- Teach β Explains only what you're missing, not everything
- Quiz β Forces active recall: "Explain it back to me"
- Schedule β Uses SM-2 rules and review ratings to propose the next review date
- Gate β Blocks new material if prerequisites aren't solid
- Evolve β Tracks mistakes and adjusts teaching strategies
The dialogues and progress values below are illustrative examples of the intended workflow, not recorded study results or evidence of educational effectiveness. Actual behavior depends on the host agent, learner responses, and configuration.
You: Please read CLAUDE.md to initialize Tutor learning mode.
Tutor: I'm now in learning coach mode. Let's build your learner profile.
What subject or skill do you want to master?
You: I want to learn Python for data analysis.
Tutor: Great goal. A few questions to personalize your path:
1. What's your current Python level? (never coded / basics / intermediate)
2. What's your background? (student / analyst / engineer / other)
3. Time commitment? (hours per week)
You: Basics. I'm a business analyst. Maybe 3-4 hours per week.
Tutor: Perfect. I'll design a path that:
- Builds on your analyst mindset (familiar contexts)
- Focuses on pandas, visualization, real datasets
- Fits 3-4 hours/week (2-3 concepts per session)
β Learner profile saved to .tutor/config/learner-profile.md
Ready to start? Type: /plan Python
You: /plan Python
Tutor: Before I design your path, let me diagnose your starting point.
Quick check: Can you explain what a list comprehension does?
You: Hmm... it's a shortcut for loops?
Tutor: Close! Let me see where exactly you are...
[asks 3-4 diagnostic questions]
β Diagnosis complete. Here's your personalized path:
π Python for Data Analysis β Concept Map
Foundation (Week 1-2):
ββ Variables & Types β List operations β Dictionaries
β
Data Structures (Week 3-4):
ββ List comprehensions β Pandas Series β DataFrames
β
Analysis (Week 5-8):
ββ Filtering data β Groupby β Joins β Visualization
Prerequisites are mapped. I won't let you skip ahead with gaps.
Ready to learn? Type: /learn
You: /learn
Tutor: Today's plan:
β’ Review: 2 concepts due (from 6 days ago)
β’ New: Learn list comprehensions
βββββββββββββββββββββββββββββββββββββββββ
π
REVIEW: Dictionaries (learned 6 days ago)
βββββββββββββββββββββββββββββββββββββββββ
Before I show you anything, try to recall:
How do you get a value from a dict if the key might not exist?
You: Use dict.get()?
Tutor: Exactly! And what does get() return if the key is missing?
You: Umm... None?
Tutor: Perfect. You've got this solid. β
Quality: 5/5 (perfect recall)
Next review: 15 days from now
βββββββββββββββββββββββββββββββββββββββββ
π NEW CONCEPT: List Comprehensions
βββββββββββββββββββββββββββββββββββββββββ
First, tell me: what do you already know about them?
You: They're... shorter ways to create lists?
Tutor: Good starting point. Let me build on that...
[teaches concept step by step]
Now, explain it back: How would you use a list comprehension
to get all even numbers from [1,2,3,4,5,6]?
You: [x for x in [1,2,3,4,5,6] if x % 2 == 0]
Tutor: Perfect! You understand the syntax AND the logic. β
Quality: 4/5 (correct, slight hesitation)
I'll quiz you on this in 6 days.
βββββββββββββββββββββββββββββββββββββββββ
π SESSION SUMMARY
βββββββββββββββββββββββββββββββββββββββββ
Reviewed: 2 concepts (both solid β)
Learned: 1 new concept (list comprehensions)
Mastered: 0 β 2 concepts (dicts, loops promoted to mastered!)
Next review: 2026-07-24 (2 concepts due)
You: /learn
Tutor: Before we continue, let's review what's due today.
π
REVIEW: List Comprehensions (learned 6 days ago)
Write a comprehension that filters names starting with 'A'
from ['Alice', 'Bob', 'Anna', 'Charlie']
You: Um... [name for name in names if name[0] == 'A']?
Tutor: Correct logic, but you hesitated. Let's verify understanding.
What if the list had empty strings? Would name[0] crash?
You: Oh... yeah, it would.
Tutor: Exactly. Let's review error handling...
[reviews defensive programming]
Quality: 3/5 (correct but shaky)
β οΈ MASTERY GATE ACTIVATED
You planned to learn "Pandas DataFrames" today, but list
comprehensions are still wobbly (need quality β₯4 to proceed).
Let's do targeted practice on comprehensions first.
[deliberate practice exercises]
β Now you're solid. Ready for DataFrames!
You: /status
Tutor: π Learning Progress β Python for Data Analysis
Mastery Overview:
ββββββββββββββββββββ 12/20 concepts (60%)
Status Breakdown:
β Mastered: 8 concepts (>21 day intervals, stable recall)
β‘ Learning: 4 concepts (active review cycle)
π
Scheduled: 4 concepts (due in next 7 days)
π― Planned: 8 concepts (not started yet)
Recent Performance:
Last 7 days: 6 reviews, avg quality: 4.2/5
Streak: 12 days consecutive practice
Next Review: 2026-07-20 (2 concepts due)
Weak Points: Lambda functions (failed 2x), review scheduled
Ready to: /learn (continue) | /review (catch up) | /test (quiz)
You: /learn Python decorators
Tutor: Before we start, can you explain what a closure is?
You: Umm... not really
Tutor: No problem. Let's review closures first.
[Teaches closures β Quiz β Pass]
Tutor: Now you're ready for decorators!
Design intent: Check prerequisite knowledge before introducing dependent concepts.
Day 1: Learn concept A (mastery: 30%)
Day 2: Quiz on A (quality: 4/5) β next review scheduled in 6 days
Day 8: Active recall test (quality: 5/5) β interval extended to 15 days
Day 23: Still remembers perfectly β marked as MASTERED β
Design intent: Use prior review ratings to schedule another retrieval attempt. The example is not a measured retention result or proof of an optimal schedule.
You: I understand recursion now
Tutor: Great! Explain it back to me like I'm 10 years old
You: Well... it's when a function... calls itself... and...
Tutor: You're stuck on the concept, not just the syntax. Let's break it down differently.
Design intent: Use an explanation task to surface gaps for further practice; fluency alone is not proof of understanding.
Tutor takes design inspiration from mastery learning, retrieval practice, and spaced review. These ideas inform the workflow; they are not evidence that this particular software produces a specified learning gain.
What the template is designed to support:
- Retrieval practice: ask for an answer or explanation before showing the solution.
- Spaced review: propose review dates from SM-2 rules and recorded ratings.
- Prerequisite checks: use configurable gates before introducing dependent topics.
- Learner-state tracking: retain review history and mistakes in inspectable files.
What is not established here:
- Reproduction of Bloom's tutoring results or any particular effect size.
- A fixed percentage improvement in retention over re-reading or cramming.
- An optimal review schedule for every learner, subject, or assessment.
- Independent validation that the template's "mastered" label measures durable knowledge.
A software or state-validation test can check workflow behavior without establishing educational effectiveness. A credible efficacy claim would need a documented evaluation with a comparison condition, defined learning outcomes, delayed assessment, and reported limitations. Until such evidence is published, treat Tutor as a research-inspired workflow template, not a proven substitute for human tutoring.
git clone https://github.com/YusenZhang0601/tutor.git
cd tutorWorks with:
- Claude Code (recommended)
- Cursor
- GitHub Copilot
- OpenAI Codex
- Gemini CLI
- Any agent that can read project instructions
Send this message to your AI agent:
Please read CLAUDE.md (or AGENTS.md) to initialize Tutor learning mode.
/onboard # Build your learner profile
/plan <subject> # e.g., /plan Python
/learn # Start the mastery loop
That's it! Tutor handles the rest: diagnosis, teaching, quizzes, scheduling, gates.
| Command | What It Does |
|---|---|
/onboard |
First-time interview: goals, background, pace, preferences |
/plan <subject> |
Diagnose your starting point, generate concept path |
/learn |
Full session: recall β teach β quiz β review β schedule |
/review |
Review today's due concepts only (no new material) |
/test <topic> |
Take a mastery quiz on a specific topic |
/status |
See your progress, mastery levels, review queue |
/evaluate |
Analyze learning effectiveness and bottlenecks |
Example workflow:
# Day 1
/onboard
/plan Machine Learning
/learn # Learns 2-3 new concepts
# Day 2
/review # Reviews yesterday's material
/learn # Adds new concepts
# Day 8
/review # Spaced repetition kicks in
/status # Check what you've mastered.
βββ AGENTS.md / CLAUDE.md # Agent entry point (read this first)
βββ .tutor/
β βββ config/
β β βββ learner-profile.md # Your personalized profile
β β βββ project.yml # System configuration
β βββ core/
β β βββ protocol.md # Session workflow & command mapping
β β βββ settings.yml # Mastery thresholds & SM-2 parameters
β β βββ scripts/ # Validation & maintenance scripts
β β βββ skills/ # 9 learning skills (onboard, teach, quiz...)
β βββ data/
β β βββ review-cards.json # Quiz templates for each concept
β βββ docs/ # Session checklists & upgrade notes
βββ state/
β βββ mastery.json # Concept mastery states & progress
β βββ reviews.jsonl # Review history (SM-2 log)
β βββ due.md # Today's review queue
β βββ mistakes.md # Error tracking for targeted practice
βββ subjects/ # Your learning content
β βββ <subject>/
β βββ INDEX.md # Subject overview & concept graph
β βββ topics/ # Organized by topics
β βββ progress.md # Session-by-session learning log
βββ examples/ # Example subject structures
Key concepts:
- State lives in files (not databases) so the AI can read/write directly
- Concept notes have frontmatter with SM-2 state (ef, interval, reps, due)
- Protocol is explicit so the agent stays disciplined
Every concept tracks:
ef(easiness factor) β how hard it is for youintervalβ days until next reviewrepsβ successful review countdueβ next review date
Quality ratings (0-5) adjust scheduling:
- 5 = Perfect recall β long interval
- 3-4 = Correct but slow β moderate interval
- <3 = Forgot β reset to 1 day
The template assigns the workflow label mastered only when:
- β Reviewed successfully β₯3 times (configurable)
- β Interval extended to β₯21 days
- β Quality rating β₯4 in recent quizzes
Until prerequisites meet the configured thresholds, new material is blocked. This label is an operational rule, not an independently validated measure of durable mastery.
Wrong answers aren't lost β they go to state/mistakes.md:
- Tutor biases future quizzes toward your weak points
- Explanations are adjusted based on your error patterns
- Deliberate practice targets specific gaps
The system learns from:
- User corrections ("That explanation didn't work for me")
- Repeated mistakes (concept needs a different approach)
- Session data (pacing, difficulty calibration)
Changes are proposed, not auto-applied (you stay in control).
We welcome contributions! Areas where you can help:
- πΈ Screenshots & demos β Show Tutor in action
- π¨ Visual design β Banner, badges, diagrams
- π Subject templates β Add example learning paths (Python, React, Stats...)
- π Bug reports β Found an issue? Open an issue
- π Feature ideas β Suggest improvements in Discussions
- π Documentation β Improve explanations, add FAQs
See CONTRIBUTING.md for guidelines.
- β Core mastery learning loop
- β SM-2 spaced repetition
- β 9 learning skills
- β File-based state management
- β Multi-agent support (Claude, GPT, Gemini)
- Web dashboard for progress visualization
- Export to Anki/Obsidian
- Community skill templates
- Mobile app support
- FSRS v5 algorithm (better than SM-2)
- Collaborative learning (study groups)
- LLM-as-Judge for automated grading
- Integration with note-taking tools
- GitHub Discussions: Ask questions, share learning paths
- Issues: Report bugs, request features
- Twitter/X: @YusenZhang0601 β updates & learning science tips
MIT License β Free to use, modify, and distribute.
Tutor stands on the shoulders of giants:
- Benjamin Bloom β 2 Sigma Problem (1984)
- Richard Feynman β Feynman Learning Technique
- Hermann Ebbinghaus β Spacing Effect research
- Piotr WoΕΊniak β SuperMemo & SM-2 algorithm
- Andy Matuschak β Evergreen notes & spaced repetition systems
Special thanks to Hu Lao Shi for introducing me to the Feynman technique, which inspired this entire project.
Made with β€οΈ by TonyRainforest
If Tutor helped you truly master something, give it a star β