The AI Language Learning Kit for Claude Code and others
A comprehensive set of rules, guidance, and intelligent tracking systems that transform Claude Code into your personal language tutor. Master any language through adaptive practice powered by proven cognitive science—spaced repetition, active recall, and progress tracking that learns from you.
language.learning.claude.code.mp4
claude plugin marketplace add m98/fluent && claude plugin install fluent@m98One line. Registers the marketplace, installs the plugin. Works globally from any directory after this.
Restart Claude Code, then:
/setup # onboard: name, target language, level, goals
/learn # begin your first session
That's it.
- Claude Code installed
- Python 3.8+ (most systems already have it — check with
python3 --version). Install via python.org,brew install python3, or your distro's package manager. No pip packages needed — Fluent uses only the standard library. - Bash for the PreCompact backup hook (built-in on macOS/Linux; on Windows use WSL or Git Bash).
claude plugin list # expect: fluent@m98 enabled
claude plugin update fluent@m98 # pull latest version
claude plugin uninstall fluent@m98 # remove entirelyPrefer to hack on the skills or keep per-project state?
git clone https://github.com/m98/fluent.git
cd fluent
claude # launch from repo root
/setupLearner data lives in ./data/ inside the cloned repo instead of ~/.claude/fluent-data/.
Fluent resolves the data directory in this order — first match wins:
$FLUENT_DATA_DIRif set (override everything).$CLAUDE_PROJECT_DIR/data/if it haslearner-profile.json(clone mode, running from outside the repo root)../data/if it haslearner-profile.json(clone mode, running inside the repo).~/.claude/fluent-data/(plugin-install default).
Set FLUENT_DATA_DIR to run multiple learners on one machine:
export FLUENT_DATA_DIR=~/.fluent/dutchCheck where Fluent is currently looking:
python3 -c "import sys; sys.path.insert(0, '.claude/hooks'); from fluent_paths import data_dir; print(data_dir())"Most language learning apps fail because they're built for engagement metrics, not actual learning. This system is different.
1. Zero Distractions, Pure Focus
- ❌ No ads interrupting your flow
- ❌ No gamification gimmicks designed to waste your time
- ❌ No unreliable fancy UI that breaks
- ✅ Just you, the language, and an AI that adapts to your needs
2. Infinitely Adaptable Intelligence
- 🧠 Want to practice job interview phrases? Just ask.
- 🧠 Need help with a specific grammar rule? It explains it.
- 🧠 Want to focus on restaurant vocabulary? It creates exercises instantly.
- 🧠 You're in control. The AI does exactly what you need, when you need it.
3. Your Private, Smart Tutor
- 📊 Tracks everything - Every answer, every mistake, every improvement
- 🔄 Learns about YOU - Knows your weak patterns and strengths
- 📈 Adapts to YOU - Adjusts difficulty based on your performance
- 🔒 Private - All data stays on your machine, no external tracking
- 🎯 Personal - Like having a tutor who knows your exact level and learning style
The Result? A learning system that feels like a conversation with an expert friend who remembers everything, tracks your progress scientifically, and makes learning actually enjoyable.
This is a comprehensive, open-source language learning system that transforms Claude Code into your personal AI language tutor.
The system uses evidence-based learning methodologies including:
- Spaced Repetition (SM-2 algorithm) - Review at optimal intervals
- Active Recall - Test yourself before seeing answers
- Adaptive Difficulty - Always challenging, never frustrating
- Comprehensive Tracking - Every answer tracked and analyzed
- 🎯 Multi-Language Support - Learn any language (French, Spanish, German, Japanese, Korean, Arabic, Dutch, etc.)
- 📊 Comprehensive Tracking - Automatic progress monitoring with detailed statistics
- 🧠 Spaced Repetition - SM-2 algorithm schedules reviews just before you forget
- 🎮 Gamification - Streaks, achievements, mastery levels (0-5 stars)
- 🔄 Adaptive Difficulty - Automatically adjusts to your performance (targets 60-70% success rate)
- 📝 Multi-Modal Practice - Writing, speaking, vocabulary, reading, listening
- ⚡ Immediate Feedback - Clear explanations with every correction
- 🎨 Interactive Sessions - One question at a time, conversational feel
- 📈 Progress Visualization - Detailed statistics and trend analysis
- 💾 Automatic Backups - Hooks ensure your data is always safe
Every practice session follows this intelligent cycle:
| Step | What Happens | Why It Matters |
|---|---|---|
| 1. You Practice | Answer a question in your target language | Active recall forces your brain to retrieve information |
| 2. AI Analyzes | System evaluates your response instantly | Identifies exactly what you got right or wrong |
| 3. Get Feedback | Clear explanation of mistakes + correct version | Learning happens when you understand WHY |
| 4. System Tracks | Updates 4 databases automatically | Remembers your weak spots and strengths |
| 5. Adapts | Next question matches your current level | Always challenging, never frustrating |
What Gets Tracked:
- ✅ Error Patterns - Which grammar/vocab you struggle with
- ✅ Mastery Levels - Your skill rating (0-5 stars) for each topic
- ✅ Review Schedule - When to review based on SM-2 algorithm
- ✅ Progress Stats - Accuracy trends, streak days, total practice time
This system implements proven learning science:
1. Active Recall - You retrieve from memory before seeing answers
- 🔬 Research shows: 2-3x better retention than passive review
2. Spaced Repetition (SM-2 Algorithm) - Reviews appear just before you forget
- 🔬 Research shows: Prevents forgetting curve, optimizes long-term retention
3. Immediate Feedback - Mistakes corrected within seconds
- 🔬 Research shows: Faster learning when feedback is immediate
4. Interleaving - Mix topics to prevent drilling fatigue
- 🔬 Research shows: Better discrimination and long-term retention
5. Comprehensible Input (i+1) - Content slightly above your level
- 🔬 Research shows: Optimal learning zone (Krashen's Input Hypothesis)
6. Desirable Difficulty - Targets 60-70% success rate
- 🔬 Research shows: Too easy = no learning, too hard = frustration
Fluent is built as Claude Code skills — 12 of them. Skills work two ways:
- Type the slash command (
/learn,/vocab, etc.) — you explicitly start a session. Learner-facing skills are gated so they only run this way. No accidental 20-minute session triggered by a chat message. - Ask naturally — read-only skills like
/progressauto-trigger when you ask "how am I doing?" or "what's my streak?". Helper skills (SM-2 math, feedback formatter, DB updater, session analyzer) auto-load whenever Claude needs them during a session.
All 12 skills appear in your / menu so you can always invoke any of them manually.
These are the commands you'll use daily. Each is backed by a dedicated skill under .claude/skills/.
| Command | What It Does | When & Why to Use It |
|---|---|---|
/setup |
One-time onboarding - Asks you questions about your name, target language, current level, goals, and timeline. Creates your personalized learning profile. | First time only - Run this once to set up your account. The system generates a custom learning plan based on your answers. |
/learn |
Adaptive mixed practice - Combines different exercise types (vocabulary, grammar, sentences) based on your weak areas. Adjusts difficulty in real-time based on your performance. | Daily core practice - Your main command for general improvement. The AI decides what you need to practice most. Best after /review. |
/review |
Spaced repetition session - Shows you items that are due for review today based on the SM-2 algorithm. Focuses on things you learned before that need reinforcement. | Start every day here! - Review before learning new content. This is scientifically proven to be the most effective way to retain what you've learned. |
| Command | What It Does | When & Why to Use It |
|---|---|---|
/vocab |
Flashcard-style vocabulary drills - Rapid-fire translation practice (target language ↔ native language). Tracks which words you struggle with. | 2-3x per week - When you need to build vocabulary quickly. Great for preparing for specific topics (travel, business, etc.). |
/writing |
Writing practice - Practice emails, letters, essays, or forms in your target language. Get detailed corrections with grammar explanations. | Daily for exam prep - Essential if you're preparing for language exams. Also great for building confidence in real-world communication. |
/speaking |
Conversation practice - Role-play scenarios through typed dialogue. Practice natural conversations, asking for directions, ordering food, etc. | 2-3x per week - Builds confidence for real conversations. Typed practice helps you think through responses without pressure. |
/reading |
Reading comprehension - Read short texts (stories, articles, dialogues) then answer comprehension questions. Expands vocabulary in context. | 2-3x per week - Improves overall understanding. Best for intermediate+ learners. Reading is one of the fastest ways to absorb grammar patterns. |
| Command | What It Does | When & Why to Use It |
|---|---|---|
/progress |
Statistics dashboard - Shows your accuracy trends, streak days, mastery levels, achievements unlocked, and weak areas. Visual progress charts. | Weekly check-in - Read-only and safe to auto-invoke. Ask "how am I doing?" and Claude will open the dashboard automatically. |
These skills don't change what the learner-facing commands do — they let Claude apply the same algorithms, feedback format, and database logic consistently across every session. You can still invoke them via / if curious.
| Skill | What It Does | When It Runs |
|---|---|---|
/sm2-calculator |
SM-2 spaced-repetition algorithm reference: quality scale, interval formula, easiness-factor update, mastery-level transitions. | Auto-loaded whenever a review item is scored. |
/feedback-formatter |
Canonical per-answer feedback template — severity tagging (🔴 critical / 🟡 moderate / 🟢 minor), category labels, tone rules. | Auto-loaded every time Claude grades an answer. |
/db-updater |
How to call update-db.py with a single JSON payload that atomically updates all 6 databases at session end. |
Auto-loaded when a session ends. |
/session-analyzer |
Parses /results/{skill}-session-{ID}.md files to extract error patterns, strengths, and focus areas for the next session. |
Auto-loaded when planning the next session. |
🌅 Morning Session (15 min)
/review # Must do first - Review what you learned before
/vocab # Learn 5-10 new wordsWhy? Your brain is fresh. Reviewing first reinforces old knowledge, then new vocabulary sticks better.
🌙 Evening Session (15 min)
/writing # Practice real-world writing
/learn # Let AI choose what you need mostWhy? Writing solidifies what you learned today. /learn fills in any gaps.
📊 Weekly Check-In (5 min)
/progress # See your stats and celebrate progress!Why? Seeing improvement = motivation. You need to see you're getting better!
Your learning data is tracked in 6 JSON databases (created automatically by /setup):
| File | Purpose | Created When |
|---|---|---|
learner-profile.json |
Your info, level, preferences, streak | /setup - One time |
progress-db.json |
Overall statistics and trends | /setup - Updated every session |
mistakes-db.json |
Error patterns with frequency and examples | /setup - Updated when you make mistakes |
mastery-db.json |
Skill mastery levels (0-5 stars) | /setup - Updated after practice |
spaced-repetition.json |
Review queue (SM-2 algorithm) | /setup - Updated after each answer |
session-log.json |
Complete session history | /setup - New entry each session |
📋 Want to see the structure? Check /data-examples/ for template files showing the complete schema.
🔒 Privacy: All data stays on your machine. Automatically excluded from git via .gitignore.
The AI follows these guides:
LEARNING_SYSTEM.md- Complete methodology (how to teach)CLAUDE.md- AI tutor's role and personalityPRACTICE.md- Pattern analysis and tracking.claude/references/- Shared templates (SM-2 worked examples, feedback template, DB payload schema, session-file format) that every skill references
- Skills (
.claude/skills/) — 12 skills total. 8 learner-facing (/setup,/learn,/vocab,/writing,/speaking,/reading,/review,/progress) run when you invoke them. 4 helper skills (/sm2-calculator,/feedback-formatter,/db-updater,/session-analyzer) auto-load whenever Claude needs them during a session — and are also directly/-invokable if you want to read the reference. - Plugin manifests (
.claude-plugin/) —plugin.json+marketplace.jsonmake Fluent installable via/plugin marketplace add m98/fluent. - Automatic Hooks (
.claude/hooks/) — SessionStart welcome, SessionEnd backups, PostToolUse JSON validation + backups, PreCompact safety backup. Bothhooks.json(plugin mode) and.claude/settings.json(clone mode) wire them up. - Session Results (
/results/) — Detailed practice logs per session, parsed bysession-analyzerto plan future sessions.
Example progression for a difficult word:
Day 1: Make a mistake → Review tomorrow (interval = 1 day)
Day 2: Answer correctly → Review in 6 days
Day 8: Correct again → Review in 2 weeks
Day 22: Still remember → Monthly review (mastered!)
The system tracks for each item:
- Easiness Factor - How easy it is for YOU specifically
- Interval Days - When to review next
- Repetitions - Practice count
- Quality Score - Your performance (0-5)
Every skill and pattern gets a star rating:
- ⭐☆☆☆☆ (1) - Just started
- ⭐⭐☆☆☆ (2) - Learning
- ⭐⭐⭐☆☆ (3) - Good understanding
- ⭐⭐⭐⭐☆ (4) - Strong skill
- ⭐⭐⭐⭐⭐ (5) - Mastered!
The system automatically adjusts:
- Success rate 40-50% → Too hard, makes easier
- Success rate 60-70% → Perfect challenge! ✨
- Success rate 80-90% → Too easy, makes harder
Goal: Keep you in the "sweet spot" where learning happens.
- Platform: Claude Code (Anthropic), installable as a plugin or by clone
- AI Model: Claude (any Claude Code-supported model)
- Data Format: JSON (human-readable)
- Skills: Markdown
SKILL.mdfiles with YAML frontmatter (12 total — 8 learner-facing + 4 helper) - Hooks: Python + Bash, triggered on SessionStart / SessionEnd / PostToolUse / PreCompact
- Algorithm: SM-2 (SuperMemo 2)
- Version Control: Git
- ✅ All data stays local on your machine
- ✅ No external API calls (except Claude Code itself)
- ✅ Automatic .gitignore prevents committing personal data
- ✅ Automatic backups to
.backups/directory - ✅ No tracking, no analytics, no telemetry
Fluent uses intelligent Claude Code hooks to ensure your data is always safe and validated:
🔄 PostToolUse Hook (after every Write/Edit)
- ✅ Creates timestamped backup:
data/file.json.backup-20231117-143022 - ✅ Validates JSON structure automatically
- ✅ Alerts you immediately if data is malformed
📦 SessionEnd Hook (when you finish practicing)
- ✅ Creates daily snapshot in
.backups/YYYYMMDD/ - ✅ Displays session summary with current streak
- ✅ Shows total practice sessions completed
🌅 SessionStart Hook (when you begin)
- ✅ Welcome message with your name and stats
- ✅ Shows current language, level, and streak
- ✅ Alerts you if reviews are due today
🔒 PreCompact Hook (before compaction)
- ✅ Safety backup to prevent data loss
You'll never lose your progress. All backups are automatic and excluded from git.
See .claude/hooks/README.md for technical details.
We welcome contributions! See CONTRIBUTING.md for guidelines.
We're especially interested in:
- 🌐 Language-specific optimizations - Grammar rules, common errors for specific languages
- 🎵 Audio features - Pronunciation practice, listening exercises
- 📊 Visual enhancements - Better progress charts, statistics
- 📱 Mobile support - Companion app or mobile interface
- ⚡ Performance - Optimize data loading, improve speed
- ♿ Accessibility - Make system more accessible
- 🧪 Testing - Add comprehensive test coverage
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Test thoroughly
- Commit with clear messages
- Push and open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- Claude by Anthropic - For the amazing AI capabilities
- SuperMemo - For the SM-2 algorithm
- Anki - For inspiring the flashcard approach
- Language learning research - Krashen, Bjork, Ebbinghaus, and many others
- Open-source community - For making this possible
- 📖 Documentation: Full docs in this repo
- 💬 Discussions: GitHub Discussions
- 🐛 Bug Reports: GitHub Issues
- 📧 Email: For sensitive issues
If this system helps you learn a language, please star the repository ⭐
It helps others discover this project and motivates us to keep improving it!
- Skills: 12 (8 learner-facing + 4 helper)
- Hooks: 5 automated (SessionStart, SessionEnd, PostToolUse, PreCompact, DB helpers)
- Databases: 6 JSON tracking files
- Install paths: 2 (Claude Code plugin + git clone — both supported)
- Languages Supported: All (system is fully language-agnostic)
- Learning Methods: 6 evidence-based principles
- Contributors: See contributors
Want to share your language learning success? Open a PR to add your story here!
python3: command not found when hooks run.
Install Python 3.8+ and make sure python3 is on your PATH. On macOS: brew install python3. On Debian/Ubuntu: sudo apt install python3. On Windows: install via python.org or use WSL.
Hooks silently do nothing on Windows. The PreCompact hook is a Bash script. Run Claude Code from WSL or Git Bash. The Python hooks (SessionStart, SessionEnd, PostToolUse) work on native Windows Python — only PreCompact is Bash-only.
Learner data is showing up in the wrong place.
Check the data-dir resolution order (see above). Set FLUENT_DATA_DIR explicitly in your shell to force a specific location.
JSON validation fails after a manual edit.
The PostToolUse hook exits with status 2 if it finds malformed JSON. The last 10 backups live at <data_dir>/<filename>.json.backup-<timestamp>. Restore with: cp <data_dir>/learner-profile.json.backup-XXXXXX <data_dir>/learner-profile.json.
Skills don't appear in the / menu after plugin install.
Restart Claude Code. If still missing, verify install:
claude plugin list # should show fluent@m98 enabled
claude plugin validate fluent@m98Or from inside a session: /plugin list. If the plugin is disabled, enable it: claude plugin enable fluent@m98.
- Claude Code Documentation
- Claude Code Plugins
- SM-2 Algorithm Explained
- CEFR Levels
- Spaced Repetition Research
- Active Recall Benefits
Q: How is this different from Duolingo/Babbel/etc? A: It’s ultra-minimalistic, just a terminal and pure learning. No extra distributions, no ads, no gimmicks. Infinitely adaptable. You ask it to teach you something, and it does. And best of all, everything stays private on your machine.
Q: Do I need to know how to code?
A: No! Just install Claude Code and run /setup. That's it.
Q: How long until I see progress? A: Most learners see measurable improvement within the first week. The system tracks everything so you can see exactly how you're improving.
Q: Can I use this for exam preparation? A: Yes! The system adapts to your goals. Tell it you're preparing for DELE/DELF/TestDaF/etc. and it'll focus on exam-relevant content.
Q: Is my data safe? A: Absolutely. Everything stays on your machine. No cloud storage, no external servers (except Claude Code itself).
Q: Can I export my progress? A: Yes! All data is in human-readable JSON. You can export, analyze, or migrate it anytime.
Q: Can I use Open AI's Codex CLI or Gemini CLI instead of Claude Code? A: We have AGENTS.md for instructing other AI CLIs as well, but this kit is specifically optimized for Claude Code and its unique capabilities. Using other AI platforms may not yield the same results. But feel free to experiment and share your findings!
Start your language learning journey today! 🚀
git clone https://github.com/m98/fluent.git
cd fluent
claude
/setup