CodeSensei

An in-context coding tutor for Claude Code, for builders who ship with AI and want to understand what they built.

CodeSensei is a free, open-source Claude Code plugin by Dojo Coding that turns every coding session into a learning session.

It watches what you build locally, explains what just happened in plain language, quizzes you on concepts from your own project, and tracks your growth with a martial arts belt progression system.

Get started · Commands · Privacy · Contribute · Report an issue

---

Why it exists

Millions of people are building with AI before they fully understand the code.

That is not a failure — it is a new starting point.

The problem is what happens next:

• something breaks
• a new feature needs a custom change
• the AI explanation feels too abstract
• the user realizes they shipped something they cannot yet reason about

CodeSensei closes that gap.

Instead of forcing people to stop building and go study in a separate environment, it teaches inside the workflow they already use.

---

What you get

• 🧠 Contextual explanations — learn from your actual project, not fake toy examples
• 🧩 Micro-quizzes — quick checks that reinforce understanding instead of syntax memorization
• 🥋 Belt progression — White Belt to Black Belt, earned through XP + mastery gates
• 🔁 Persistent local profile — progress follows you across projects on the same machine
• 🎯 Adaptive teaching — explanations adjust to your belt level and professional background
• 🔒 Local-first design — no telemetry, no external calls, no code uploads from the plugin scripts

---

Quick start

Requirements

• Claude Code with plugin support
• jq installed locally
  • macOS: brew install jq
  • Ubuntu/Debian: sudo apt install jq

jq is required for profile tracking, imports, quizzes, and diagnostics.

Supported platforms

• ✅ macOS
• ✅ Linux
• ⚠️ Windows via WSL recommended

CodeSensei is a Unix-shell plugin today. Its runtime depends on bash, jq, and standard Unix tools, so WSL is the safest path on Windows.

Install from marketplace

Inside Claude Code:

/plugin marketplace add DojoCodingLabs/code-sensei
/plugin install code-sensei@code-sensei

First-run flow

After install:

1. Run /code-sensei:progress to initialize your local profile
2. Optional: run /code-sensei:level background marketing (or design, finance, medicine, etc.)
3. Build normally with Claude Code
4. Use /code-sensei:explain after a code change you want to understand
5. Run /code-sensei:doctor if you want to verify setup or inspect local storage paths

Update

Inside Claude Code:

/plugin marketplace update DojoCodingLabs/code-sensei
/plugin update code-sensei@code-sensei

Restart your Claude Code session after updating so hooks reload cleanly.

Local development install

git clone https://github.com/DojoCodingLabs/code-sensei.git
cd code-sensei

/plugin marketplace add .
/plugin install code-sensei

---

Commands

CodeSensei currently ships with 10 commands:

Command	What it does
/code-sensei:explain	Explain what Claude just changed in terms you understand
/code-sensei:quiz	Test your understanding with a contextual quiz
/code-sensei:why	Explain why a specific decision or pattern was used
/code-sensei:progress	Show your learning dashboard, streak, mastery, and next belt requirements
/code-sensei:recap	Summarize what you learned in the session
/code-sensei:level	Adjust difficulty or set your professional background
/code-sensei:belt	Show current belt rank and progress
/code-sensei:export	Export your local profile for backup or migration
/code-sensei:import	Restore a profile from a previous export
/code-sensei:doctor	Verify setup health and inspect exactly what CodeSensei stores locally

---

How it works

1. You build normally Prompt Claude to create files, edit code, install dependencies, and run commands.

2. Hooks watch local activity CodeSensei listens for file changes and shell commands, then queues lightweight teaching moments locally.

3. You ask when curious Use /code-sensei:explain, /code-sensei:why, or /code-sensei:quiz whenever you want to understand something better.

4. Teaching adapts to you White Belt gets analogy-first explanations. Advanced belts get more technical language, tradeoffs, and architecture discussion.

5. Progress persists locally Your profile lives in ~/.code-sensei/ and carries across projects on that machine.

---

Belt progression

⬜ White Belt    →     0 XP    “You wrote your first prompt”
🟡 Yellow Belt   →   500 XP    “You understand files & folders”
🟠 Orange Belt   → 1,500 XP    “You get frontend vs backend”
🟢 Green Belt    → 3,500 XP    “You can read and modify code”
🔵 Blue Belt     → 7,000 XP    “You understand APIs & databases”
🟤 Brown Belt    → 12,000 XP   “You can architect a full app”
⚫ Black Belt    → 20,000 XP   “You think like an engineer”

Promotion is not XP-only.

Each new belt also requires:

• concept mastery gates
• quiz accuracy of at least 60%

That keeps progress tied to understanding, not just activity.

---

Adaptive teaching examples

White Belt / beginner

“Claude just added a translator to your server. Raw form data arrives as text, and this translator turns it into something your code can actually read.”

Blue Belt / advanced learner

“Claude added middleware to parse JSON before requests hit your route handlers, so req.body is already normalized when your business logic runs.”

Same project. Same concept. Different depth.

Background-specific analogies

Set a backgrou