Skip to content
Back to search

m98

MarketplaceWorks with Claude CodeGitHub

The AI Language Learning Kit for Claude Code and others

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/m98--fluent/badge.svg)](/listings/m98--fluent)

HTML

<a href="/listings/m98--fluent"><img src="/api/listings/m98--fluent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install

claude plugin marketplace add m98/fluent && claude plugin install fluent@m98

One line. Registers the marketplace, installs the plugin. Works globally from any directory after this.

2. Start learning

Restart Claude Code, then:

/fluent-setup     # onboard: name, target language, level, goals
/fluent-learn     # begin your first session

That's it.

---

Requirements

- [Claude Code](https://code.claude.com) installed - **Python 3.8+** (most systems already have it — check with `python3 --version`). Install via [python.org](https://www.python.org/downloads/), `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).

Verify, update, uninstall

claude plugin list                    # expect: fluent@m98  enabled
claude plugin update fluent@m98       # pull latest version
claude plugin uninstall fluent@m98    # remove entirely

Alternative: git clone

Prefer 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
/fluent-setup

Learner data lives in `./data/` inside the cloned repo instead of `~/.claude/fluent-data/`.

Where your data lives

Fluent resolves the data directory in this order — first match wins:

1. `$FLUENT_DATA_DIR` if set (override everything). 2. `$CLAUDE_PROJECT_DIR/data/` if it has `learner-profile.json` (clone mode, running from outside the repo root). 3. `./data/` if it has `learner-profile.json` (clone mode, running inside the repo). 4. `~/.claude/fluent-data/` (plugin-install default).

Set `FLUENT_DATA_DIR` to run multiple learners on one machine:

export FLUENT_DATA_DIR=~/.fluent/dutch

Check where Fluent is currently looking:

python3 -c "import sys; sys.path.insert(0, '.claude/hooks'); from fluent_paths import data_dir; print(data_dir())"

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 28 lines
  1. {
  2. "name": "m98",
  3. "owner": {
  4. "name": "Mohammad Kermani"
  5. },
  6. "metadata": {
  7. "description": "Fluent — AI Language Learning Kit for Claude Code. Single-plugin marketplace hosting the fluent plugin.",
  8. "version": "0.3.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "fluent",
  13. "source": "./",
  14. "description": "Fluent — AI Language Learning Kit. Personal AI tutor for any target language (Dutch, Spanish, French, German, Japanese, Korean, Arabic, and more). Uses spaced repetition (SM-2), active recall, adaptive difficulty, and progress tracking across 6 databases. Run /fluent-setup to onboard, then /fluent-learn, /fluent-vocab, /fluent-writing, /fluent-speaking, /fluent-reading, /fluent-review daily.",
  15. "category": "education",
  16. "tags": ["language", "learning", "tutor", "spaced-repetition", "education", "sm2", "flashcards"],
  17. "homepage": "https://github.com/m98/fluent",
  18. "repository": "https://github.com/m98/fluent",
  19. "license": "MIT",
  20. "author": {
  21. "name": "Mohammad Kermani",
  22. "url": "https://github.com/m98"
  23. },
  24. "version": "0.3.0",
  25. "strict": true
  26. }
  27. ]
  28. }
README.md · README · 535 lines
  1. # 🌍 Fluent
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Claude Code](https://img.shields.io/badge/Powered%20by-Claude%20Code-blue)](https://code.claude.com)
  4. **The AI Language Learning Kit for Claude Code and others**
  5. *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.*
  6. https://github.com/user-attachments/assets/66d68aad-210a-452d-b405-b58c13f42f53
  7. ---
  8. ## 🚀 Quick Start
  9. ### 1. Install
  10. ```bash
  11. claude plugin marketplace add m98/fluent && claude plugin install fluent@m98
  12. ```
  13. One line. Registers the marketplace, installs the plugin. Works globally from any directory after this.
  14. ### 2. Start learning
  15. Restart Claude Code, then:
  16. ```
  17. /fluent-setup # onboard: name, target language, level, goals
  18. /fluent-learn # begin your first session
  19. ```
  20. That's it.
  21. ---
  22. ### Requirements
  23. - [Claude Code](https://code.claude.com) installed
  24. - **Python 3.8+** (most systems already have it — check with `python3 --version`). Install via [python.org](https://www.python.org/downloads/), `brew install python3`, or your distro's package manager. No pip packages needed — Fluent uses only the standard library.
  25. - **Bash** for the PreCompact backup hook (built-in on macOS/Linux; on Windows use WSL or Git Bash).
  26. ### Verify, update, uninstall
  27. ```bash
  28. claude plugin list # expect: fluent@m98 enabled
  29. claude plugin update fluent@m98 # pull latest version
  30. claude plugin uninstall fluent@m98 # remove entirely
  31. ```
  32. ### Alternative: git clone
  33. Prefer to hack on the skills or keep per-project state?
  34. ```bash
  35. git clone https://github.com/m98/fluent.git
  36. cd fluent
  37. claude # launch from repo root
  38. /fluent-setup
  39. ```
  40. Learner data lives in `./data/` inside the cloned repo instead of `~/.claude/fluent-data/`.
  41. ### Where your data lives
  42. Fluent resolves the data directory in this order — first match wins:
  43. 1. `$FLUENT_DATA_DIR` if set (override everything).
  44. 2. `$CLAUDE_PROJECT_DIR/data/` if it has `learner-profile.json` (clone mode, running from outside the repo root).
  45. 3. `./data/` if it has `learner-profile.json` (clone mode, running inside the repo).
  46. 4. `~/.claude/fluent-data/` (plugin-install default).
  47. Set `FLUENT_DATA_DIR` to run multiple learners on one machine:
  48. ```bash
  49. export FLUENT_DATA_DIR=~/.fluent/dutch
  50. ```
  51. Check where Fluent is currently looking:
  52. ```bash
  53. python3 -c "import sys; sys.path.insert(0, '.claude/hooks'); from fluent_paths import data_dir; print(data_dir())"
  54. ```
  55. ---
  56. ## 💡 Why This Actually Works
  57. Most language learning apps fail because they're built for engagement metrics, not actual learning. This system is different.
  58. ### 🎯 Three Reasons This Works Where Others Fail:
  59. **1. Zero Distractions, Pure Focus**
  60. - ❌ No ads interrupting your flow
  61. - ❌ No gamification gimmicks designed to waste your time
  62. - ❌ No unreliable fancy UI that breaks
  63. - ✅ Just you, the language, and an AI that adapts to your needs
  64. **2. Infinitely Adaptable Intelligence**
  65. - 🧠 Want to practice job interview phrases? Just ask.
  66. - 🧠 Need help with a specific grammar rule? It explains it.
  67. - 🧠 Want to focus on restaurant vocabulary? It creates exercises instantly.
  68. - 🧠 **You're in control.** The AI does exactly what you need, when you need it.
  69. **3. Your Private, Smart Tutor**
  70. - 📊 **Tracks everything** - Every answer, every mistake, every improvement
  71. - 🔄 **Learns about YOU** - Knows your weak patterns and strengths
  72. - 📈 **Adapts to YOU** - Adjusts difficulty based on your performance
  73. - 🔒 **Private** - All data stays on your machine, no external tracking
  74. - 🎯 **Personal** - Like having a tutor who knows your exact level and learning style
  75. **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.
  76. ---
  77. ## 📖 What Is This?
  78. This is a comprehensive, **open-source language learning system** that transforms [Claude Code](https://code.claude.com) into your personal AI language tutor.
  79. The system uses **evidence-based learning methodologies** including:
  80. - **Spaced Repetition (SM-2 algorithm)** - Review at optimal intervals
  81. - **Active Recall** - Test yourself before seeing answers
  82. - **Adaptive Difficulty** - Always challenging, never frustrating
  83. - **Comprehensive Tracking** - Every answer tracked and analyzed
  84. ### ✨ Key Features
  85. - 🎯 **Multi-Language Support** - Learn any language (French, Spanish, German, Japanese, Korean, Arabic, Dutch, etc.)
  86. - 📊 **Comprehensive Tracking** - Automatic progress monitoring with detailed statistics
  87. - 🧠 **Spaced Repetition** - SM-2 algorithm schedules reviews just before you forget
  88. - 🎮 **Gamification** - Streaks, achievements, mastery levels (0-5 stars)
  89. - 🔄 **Adaptive Difficulty** - Automatically adjusts to your performance (targets 60-70% success rate)
  90. - 📝 **Multi-Modal Practice** - Writing, speaking, vocabulary, reading, listening
  91. - ⚡ **Immediate Feedback** - Clear explanations with every correction
  92. - 🎨 **Interactive Sessions** - One question at a time, conversational feel
  93. - 📈 **Progress Visualization** - Detailed statistics and trend analysis
  94. - 💾 **Automatic Backups** - Hooks ensure your data is always safe
  95. ---
  96. ## 📚 How It Works
  97. ### The Learning Loop
  98. Every practice session follows this intelligent cycle:
  99. | Step | What Happens | Why It Matters |
  100. |------|--------------|----------------|
  101. | **1. You Practice** | Answer a question in your target language | Active recall forces your brain to retrieve information |
  102. | **2. AI Analyzes** | System evaluates your response instantly | Identifies exactly what you got right or wrong |
  103. | **3. Get Feedback** | Clear explanation of mistakes + correct version | Learning happens when you understand WHY |
  104. | **4. System Tracks** | Updates 4 databases automatically | Remembers your weak spots and strengths |
  105. | **5. Adapts** | Next question matches your current level | Always challenging, never frustrating |
  106. **What Gets Tracked:**
  107. - ✅ **Error Patterns** - Which grammar/vocab you struggle with
  108. - ✅ **Mastery Levels** - Your skill rating (0-5 stars) for each topic
  109. - ✅ **Review Schedule** - When to review based on SM-2 algorithm
  110. - ✅ **Progress Stats** - Accuracy trends, streak days, total practice time
  111. ### Evidence-Based Methods
  112. This system implements proven learning science:
  113. **1. Active Recall** - You retrieve from memory before seeing answers
  114. - 🔬 Research shows: **2-3x better retention** than passive review
  115. **2. Spaced Repetition (SM-2 Algorithm)** - Reviews appear just before you forget
  116. - 🔬 Research shows: **Prevents forgetting curve**, optimizes long-term retention
  117. **3. Immediate Feedback** - Mistakes corrected within seconds
  118. - 🔬 Research shows: **Faster learning** when feedback is immediate
  119. **4. Interleaving** - Mix topics to prevent drilling fatigue
  120. - 🔬 Research shows: **Better discrimination** and long-term retention
  121. **5. Comprehensible Input (i+1)** - Content slightly above your level
  122. - 🔬 Research shows: **Optimal learning zone** (Krashen's Input Hypothesis)
  123. **6. Desirable Difficulty** - Targets 60-70% success rate
  124. - 🔬 Research shows: **Too easy = no learning, too hard = frustration**
  125. ---
  126. ## 🎮 Available Commands & Skills
  127. Fluent is built as **Claude Code skills** — 12 of them. Skills work two ways:
  128. 1. **Type the slash command** (`/fluent-learn`, `/fluent-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.
  129. 2. **Ask naturally** — read-only skills like `/fluent-progress` auto-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.
  130. All 12 skills appear in your `/` menu so you can always invoke any of them manually.
  131. ### Learner-facing commands
  132. These are the commands you'll use daily. Each is backed by a dedicated skill under `.claude/skills/`.
  133. #### Core Commands
  134. | Command | What It Does | When & Why to Use It |
  135. |---------|--------------|----------------------|
  136. | **`/fluent-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. |
  137. | **`/fluent-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 `/fluent-review`. |
  138. | **`/fluent-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. |
  139. #### Skill-Specific Commands
  140. | Command | What It Does | When & Why to Use It |
  141. |---------|--------------|----------------------|
  142. | **`/fluent-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.). |
  143. | **`/fluent-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. |
  144. | **`/fluent-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. |
  145. | **`/fluent-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. |
  146. #### Progress Command
  147. | Command | What It Does | When & Why to Use It |
  148. |---------|--------------|----------------------|
  149. | **`/fluent-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. |
  150. ### Helper skills (behind the scenes)
  151. 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.
  152. | Skill | What It Does | When It Runs |
  153. |-------|--------------|--------------|
  154. | **`/fluent-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. |
  155. | **`/fluent-feedback-formatter`** | Canonical per-answer feedback template — severity tagging (🔴 critical / 🟡 moderate / 🟢 minor), category labels, tone rules. | Auto-loaded every time Claude grades an answer. |
  156. | **`/fluent-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. |
  157. | **`/fluent-session-analyzer`** | Parses `/results/fluent-{skill}-session-{ID}.md` files to extract error patterns, strengths, and focus areas for the next session. | Auto-loaded when planning the next session. |
  158. ### 📅 Recommended Daily Routine
  159. **🌅 Morning Session (15 min)**
  160. ```bash
  161. /fluent-review # Must do first - Review what you learned before
  162. /fluent-vocab # Learn 5-10 new words
  163. ```
  164. **Why?** Your brain is fresh. Reviewing first reinforces old knowledge, then new vocabulary sticks better.
  165. **🌙 Evening Session (15 min)**
  166. ```bash
  167. /fluent-writing # Practice real-world writing
  168. /fluent-learn # Let AI choose what you need most
  169. ```
  170. **Why?** Writing solidifies what you learned today. `/fluent-learn` fills in any gaps.
  171. **📊 Weekly Check-In (5 min)**
  172. ```bash
  173. /fluent-progress # See your stats and celebrate progress!
  174. ```
  175. **Why?** Seeing improvement = motivation. You need to see you're getting better!
  176. ---
  177. ## 📁 System Architecture
  178. ### Data Layer (`/data` directory)
  179. **Your learning data is tracked in 6 JSON databases** (created automatically by `/fluent-setup`):
  180. | File | Purpose | Created When |
  181. |------|---------|--------------|
  182. | `learner-profile.json` | Your info, level, preferences, streak | `/fluent-setup` - One time |
  183. | `progress-db.json` | Overall statistics and trends | `/fluent-setup` - Updated every session |
  184. | `mistakes-db.json` | Error patterns with frequency and examples | `/fluent-setup` - Updated when you make mistakes |
  185. | `mastery-db.json` | Skill mastery levels (0-5 stars) | `/fluent-setup` - Updated after practice |
  186. | `spaced-repetition.json` | Review queue (SM-2 algorithm) | `/fluent-setup` - Updated after each answer |
  187. | `session-log.json` | Complete session history | `/fluent-setup` - New entry each session |
  188. **📋 Want to see the structure?** Check `/data-examples/` for template files showing the complete schema.
  189. **🔒 Privacy:** All data stays on your machine. Automatically excluded from git via `.gitignore`.
  190. ### Intelligence Layer
  191. The AI follows these guides:
  192. - **`LEARNING_SYSTEM.md`** - Complete methodology (how to teach)
  193. - **`CLAUDE.md`** - AI tutor's role and personality
  194. - **`PRACTICE.md`** - Pattern analysis and tracking
  195. - **`.claude/references/`** - Shared templates (SM-2 worked examples, feedback template, DB payload schema, session-file format) that every skill references
  196. ### Interface Layer
  197. - **Skills** (`.claude/skills/`) — 12 skills total. 8 learner-facing (`/fluent-setup`, `/fluent-learn`, `/fluent-vocab`, `/fluent-writing`, `/fluent-speaking`, `/fluent-reading`, `/fluent-review`, `/fluent-progress`) run when you invoke them. 4 helper skills (`/fluent-sm2-calculator`, `/fluent-feedback-formatter`, `/fluent-db-updater`, `/fluent-session-analyzer`) auto-load whenever Claude needs them during a session — and are also directly `/`-invokable if you want to read the reference.
  198. - **Plugin manifests** (`.claude-plugin/`) — `plugin.json` + `marketplace.json` make Fluent installable via `/plugin marketplace add m98/fluent`.
  199. - **Automatic Hooks** (`.claude/hooks/`) — SessionStart welcome, SessionEnd backups, PostToolUse JSON validation + backups, PreCompact safety backup. Both `hooks.json` (plugin mode) and `.claude/settings.json` (clone mode) wire them up.
  200. - **Session Results** (`/results/`) — Detailed practice logs per session, parsed by `fluent-session-analyzer` to plan future sessions.
  201. ---
  202. ## 🎯 Learning Principles
  203. ### Spaced Repetition (SM-2 Algorithm)
  204. **Example progression for a difficult word:**
  205. ```
  206. Day 1: Make a mistake → Review tomorrow (interval = 1 day)
  207. Day 2: Answer correctly → Review in 6 days
  208. Day 8: Correct again → Review in 2 weeks
  209. Day 22: Still remember → Monthly review (mastered!)
  210. ```
  211. The system tracks for each item:
  212. - **Easiness Factor** - How easy it is for YOU specifically
  213. - **Interval Days** - When to review next
  214. - **Repetitions** - Practice count
  215. - **Quality Score** - Your performance (0-5)
  216. ### Mastery Levels
  217. Every skill and pattern gets a star rating:
  218. - ⭐☆☆☆☆ (1) - Just started
  219. - ⭐⭐☆☆☆ (2) - Learning
  220. - ⭐⭐⭐☆☆ (3) - Good understanding
  221. - ⭐⭐⭐⭐☆ (4) - Strong skill
  222. - ⭐⭐⭐⭐⭐ (5) - Mastered!
  223. ### Adaptive Difficulty
  224. The system automatically adjusts:
  225. - **Success rate 40-50%** → Too hard, makes easier
  226. - **Success rate 60-70%** → Perfect challenge! ✨
  227. - **Success rate 80-90%** → Too easy, makes harder
  228. **Goal:** Keep you in the "sweet spot" where learning happens.
  229. ---
  230. ## 🔬 Technical Details
  231. ### Technology Stack
  232. - **Platform:** Claude Code (Anthropic), installable as a plugin or by clone
  233. - **AI Model:** Claude (any Claude Code-supported model)
  234. - **Data Format:** JSON (human-readable)
  235. - **Skills:** Markdown `SKILL.md` files with YAML frontmatter (12 total — 8 learner-facing + 4 helper)
  236. - **Hooks:** Python + Bash, triggered on SessionStart / SessionEnd / PostToolUse / PreCompact
  237. - **Algorithm:** SM-2 (SuperMemo 2)
  238. - **Version Control:** Git
  239. ### Data Privacy & Security
  240. - ✅ **All data stays local** on your machine
  241. - ✅ **No external API calls** (except Claude Code itself)
  242. - ✅ **Automatic .gitignore** prevents committing personal data
  243. - ✅ **Automatic backups** to `.backups/` directory
  244. - ✅ **No tracking, no analytics, no telemetry**
  245. ### Hooks System (Automated Data Management)
  246. Fluent uses intelligent Claude Code hooks to ensure your data is always safe and validated:
  247. **🔄 PostToolUse Hook** (after every Write/Edit)
  248. - ✅ Creates timestamped backup: `data/file.json.backup-20231117-143022`
  249. - ✅ Validates JSON structure automatically
  250. - ✅ Alerts you immediately if data is malformed
  251. **📦 SessionEnd Hook** (when you finish practicing)
  252. - ✅ Creates daily snapshot in `.backups/YYYYMMDD/`
  253. - ✅ Displays session summary with current streak
  254. - ✅ Shows total practice sessions completed
  255. **🌅 SessionStart Hook** (when you begin)
  256. - ✅ Welcome message with your name and stats
  257. - ✅ Shows current language, level, and streak
  258. - ✅ Alerts you if reviews are due today
  259. **🔒 PreCompact Hook** (before compaction)
  260. - ✅ Safety backup to prevent data loss
  261. **You'll never lose your progress.** All backups are automatic and excluded from git.
  262. See [`.claude/hooks/README.md`](.claude/hooks/README.md) for technical details.
  263. ---
  264. ## 🤝 Contributing
  265. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  266. ### Priority Areas
  267. We're especially interested in:
  268. 1. 🌐 **Language-specific optimizations** - Grammar rules, common errors for specific languages
  269. 2. 🎵 **Audio features** - Pronunciation practice, listening exercises
  270. 3. 📊 **Visual enhancements** - Better progress charts, statistics
  271. 4. 📱 **Mobile support** - Companion app or mobile interface
  272. 5. ⚡ **Performance** - Optimize data loading, improve speed
  273. 6. ♿ **Accessibility** - Make system more accessible
  274. 7. 🧪 **Testing** - Add comprehensive test coverage
  275. ### How to Contribute
  276. 1. Fork the repository
  277. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  278. 3. Make your changes
  279. 4. Test thoroughly
  280. 5. Commit with clear messages
  281. 6. Push and open a Pull Request
  282. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
  283. ---
  284. ## 📄 License
  285. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  286. ---
  287. ## 🙏 Acknowledgments
  288. - **Claude** by Anthropic - For the amazing AI capabilities
  289. - **SuperMemo** - For the SM-2 algorithm
  290. - **Anki** - For inspiring the flashcard approach
  291. - **Language learning research** - Krashen, Bjork, Ebbinghaus, and many others
  292. - **Open-source community** - For making this possible
  293. ---
  294. ## 📞 Support & Community
  295. - 📖 **Documentation:** [Full docs in this repo](docs/)
  296. - 🐛 **Bug Reports & Questions:** [GitHub Issues](https://github.com/m98/fluent/issues)
  297. - 📧 **Email:** For sensitive issues
  298. ---
  299. ## 🌟 Star This Project!
  300. If this system helps you learn a language, please **star the repository** ⭐
  301. It helps others discover this project and motivates us to keep improving it!
  302. ---
  303. ## 📈 Project Stats
  304. - **Skills:** 12 (8 learner-facing + 4 helper)
  305. - **Hooks:** 5 automated (SessionStart, SessionEnd, PostToolUse, PreCompact, DB helpers)
  306. - **Databases:** 6 JSON tracking files
  307. - **Install paths:** 2 (Claude Code plugin + git clone — both supported)
  308. - **Languages Supported:** All (system is fully language-agnostic)
  309. - **Learning Methods:** 6 evidence-based principles
  310. - **Contributors:** [See contributors](https://github.com/m98/fluent/graphs/contributors)
  311. ---
  312. ## 🎓 Success Stories
  313. *Want to share your language learning success? Open a PR to add your story here!*
  314. ---
  315. ## 🛠️ Troubleshooting
  316. **`python3: command not found` when hooks run.**
  317. 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](https://www.python.org/downloads/) or use WSL.
  318. **Hooks silently do nothing on Windows.**
  319. 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.
  320. **Learner data is showing up in the wrong place.**
  321. Check the data-dir resolution order (see above). Set `FLUENT_DATA_DIR` explicitly in your shell to force a specific location.
  322. **JSON validation fails after a manual edit.**
  323. 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`.
  324. **Skills don't appear in the `/` menu after plugin install.**
  325. Restart Claude Code. If still missing, verify install:
  326. ```bash
  327. claude plugin list # should show fluent@m98 enabled
  328. claude plugin validate fluent@m98
  329. ```
  330. Or from inside a session: `/plugin list`. If the plugin is disabled, enable it: `claude plugin enable fluent@m98`.
  331. ---
  332. ## 🔗 Useful Links
  333. - [Claude Code Documentation](https://code.claude.com/docs)
  334. - [Claude Code Plugins](https://code.claude.com/docs/en/plugins)
  335. - [SM-2 Algorithm Explained](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2)
  336. - [CEFR Levels](https://www.coe.int/en/web/common-european-framework-reference-languages/level-descriptions)
  337. - [Spaced Repetition Research](https://www.gwern.net/Spaced-repetition)
  338. - [Active Recall Benefits](https://en.wikipedia.org/wiki/Testing_effect)
  339. ---
  340. ## ❓ FAQ
  341. **Q: How is this different from Duolingo/Babbel/etc?**
  342. 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.
  343. **Q: Do I need to know how to code?**
  344. A: No! Just install Claude Code and run `/fluent-setup`. That's it.
  345. **Q: How long until I see progress?**
  346. A: Most learners see measurable improvement within the first week. The system tracks everything so you can see exactly how you're improving.
  347. **Q: Can I use this for exam preparation?**
  348. 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.
  349. **Q: Is my data safe?**
  350. A: Absolutely. Everything stays on your machine. No cloud storage, no external servers (except Claude Code itself).
  351. **Q: Can I export my progress?**
  352. A: Yes! All data is in human-readable JSON. You can export, analyze, or migrate it anytime.
  353. **Q: Can I use Open AI's Codex CLI or Gemini CLI instead of Claude Code?**
  354. A: We have AGENTS.md for instructing other AI CLIs as well, but this kit is specifically optimized for
  355. Claude Code and its unique capabilities. Using other AI platforms may not yield the same results.
  356. But feel free to experiment and share your findings!
  357. ---
  358. *Start your language learning journey today!* 🚀
  359. ```bash
  360. git clone https://github.com/m98/fluent.git
  361. cd fluent
  362. claude
  363. /fluent-setup
  364. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.