Skip to content
Conduit

skill

bodhikit

Research-backed interactive coding tutor for Claude Code. Mirror of codeberg.org/AnjanJ/BodhiKit

AnjanJ/bodhikitcommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/AnjanJ/bodhikit itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 26, 2026

BodhiKit

Version Buy Me A Coffee Sponsor

A research-informed tutor for any subject, with code first-class, for Claude Code, Codex, and ChatGPT.

Bodhi (Pali: "awakening") is a patient, wise guide. It teaches code and software engineering as it always has, and now genetics, history, philosophy, cooking, drawing, an instrument or a language too. It does not do the work for you: on code it will not write your code, and in any subject it teaches you to do the work yourself.

TL;DR

BodhiKit turns Claude Code, Codex, or ChatGPT into a research-informed tutor: a set of skills that teach by asking rather than answering, keep per-concept learning state when the platform exposes project files, and schedule your reviews. It does not write the code, or the essay, for you.

What it can check, and what it can't. It checks code by reading it and seeing it run, and problems and essays against the answers or criteria it saved before you started. It can't see a skill you practise away from the screen, like a dish, a drawing or a passage played. There it debriefs you, grades the debrief, and counts the practice as your account, labelled that way wherever it shows. In every subject the tutor itself grades your level, your reviews and your explain-backs. Tracked study needs a computer: Claude Code, Codex, or a claude.ai chat with Claude Desktop connected to your folder. Without one, on claude.ai or a phone, it teaches but can't keep your schedule. What "research-informed" does and does not claim is in The Science; the only outcome data so far — one learner, thin, published to be falsifiable — is in docs/outcomes.md.

Purpose & philosophy

The animating constraint: "The learner writes code. BodhiKit asks questions. The goal is to become unnecessary." In any subject, the learner does the work.

The voice comes from four named teachers (Gautama Buddha, Dr. B.R. Ambedkar, Master Oogway, Yoda) — a persona layer in the teaching-personality KB that sets the tone: patience, directness with care, "try it and see", education as empowerment. The pedagogy itself is owned by the methodology KBs below, each with its own citations.

How it works

  1. Pedagogical theories wired into behavior, not vibes. Bloom's taxonomy (per-concept level tracking), Vygotsky's ZPD (calibrated difficulty), Leitner spaced repetition (5-box system with date-computed reviews), Feynman (explain-back gates), Sweller's cognitive load (faded worked examples), Bjork's pretesting, Rawson & Dunlosky's successive relearning, Koriat's confidence calibration, deliberate practice, Whitmore's GROW, Kram's mentoring functions, Flavell's metacognition. Each lives in its own KB, loaded only when its phase fires (progressive disclosure).

  2. A Socratic protocol, checked two ways — but not enforced in code. /teach uses graduated hints (Direction → Approach → Near-solution) and forbids "Hint 4." /debug-together says "Do NOT look at the code yet." Whether the tutor actually withholds a solution is model behaviour: dev/check.sh checks that every skill references the protocol rather than restating it, and the LLM evals sample it (a fourth hint after three failed ones, a solution handed over on demand, an unearned correct — each is a detector, not a proof). The file mechanics in item 4 are deterministic; the Socratic behaviour is not, and this README does not claim otherwise.

  3. Cross-session memory. .bodhi/state.json, spaced-review.json, progress.md, and .bodhi-profile.json form a learner profile that persists. Streaks, Box-3 review dates, Bloom level per sub-topic, persistent challenges — all carried forward.

  4. A deterministic state layer (1.11.0). Every JSON mutation goes through scripts/bodhi-state — Leitner math, the Bloom ratchet, mastery formula, migration, and schema validation run in code, not in model prose. A Stop hook verifies tracking files before a session ends, and a two-layer test harness (free deterministic tests + pre-tag LLM evals asserting on file state) guards the contracts that manual dogfooding used to.

  5. Single sources of truth + lint as contract. state-ops KB owns the operational surface; state-schema KB owns every tracking-file shape (and loads only where a skill legitimately hand-mutates JSON). spaced-repetition KB owns every Leitner interval. teaching-personality owns the voice. dev/check.sh enforces the contracts — version sync (badge included), KB references, agent fallbacks, --invoked-from= chaining, the bodhi-state write path, skill size budgets — and runs the deterministic test suite.

  6. Sub-skill chaining for context efficiency. /continue → /quiz → /teach → /reflect, each passing --invoked-from=<caller> so callees skip redundant KB loads; the opening check-in is rendered from one bodhi-state snapshot call, not a skill load.

What Makes BodhiKit Different

  • Research-informed: Built on well-studied learning science (Oakley, Feynman, Bloom, Vygotsky, Ericsson, Dweck, Bjork) — see the honest note in The Science for what that does and does not claim
  • Deeply personalized: Assesses your unique skill level, builds a custom learning plan, adapts to your pace
  • Proactive teaching: /teach walks you through concepts step by step, not just answering questions
  • Hands-on, in any subject: Learn by doing — code that runs, problems checked against saved answers, essays read against saved criteria, practice reps debriefed. Never just reading.
  • Honest about evidence: Every piece of applied work says how it was seen: observed, a photo examined, or your own report. Your word counts only where nothing else is possible, and it is labelled as yours
  • Remembers your journey: Spaced repetition, progress tracking, cross-session continuity
  • Metacognitive reflection: End-of-session /reflect builds your awareness of HOW you learn
  • One command sessions: /continue runs the check-in, due reviews, teaching or practice, and reflection
  • Honest and wise: Feedback that is respectful, specific, and genuinely helpful

Install

Claude Code

/plugin marketplace add https://github.com/AnjanJ/bodhikit.git
/plugin install bodhikit@bodhikit

Restart Claude Code after installing. (To try a checkout without installing: claude --plugin-dir ~/code/bodhikit.)

Claude chats with your computer connected

A chat on claude.ai can keep your learning project in a folder on your computer, through the Claude Desktop app. Add BodhiKit in one of two ways:

  • From its marketplace, which updates in place. Customize → Plugins → Add → Add marketplace → Add from a repository, enter AnjanJ/bodhikit and choose Sync, then open Bodhikit and choose Add. When a new release is out: Add → Manage marketplaces → ⋯ beside bodhikit → Check for updates.
  • As a file. Download bodhikit.plugin from the latest release, then upload it under Customize → Plugins → Add → Upload plugin. It stays at that version until you upload a newer one.

To build bodhikit.plugin from a checkout instead:

python3 platforms/cowork/build_plugin.py --archive dist/bodhikit.plugin

Keep one BodhiKit plugin switched on, since two copies both register /bodhikit:*. In each new chat, with Claude Desktop open, choose + → Devices and tick your computer. When the chat asks for a folder, allow learningWithBodhi/ rather than a single project, because your profile lives there. How this was checked, and what wasn't, is in docs/cowork-probe.md.

ChatGPT

BodhiKit is listed in ChatGPT's Plugin Directory: find BodhiKit there and install it. OpenAI reviews each version before it goes live, so the listing can trail the latest release here.

Codex

Codex installs plugins through a marketplace. From a checkout, build the OpenAI-native package:

python3 platforms/openai/build_plugin.py

Then add dist/openai/bodhikit to your personal marketplace with Codex's $plugin-creator skill and run codex plugin add bodhikit@personal. BodhiKit for Codex and ChatGPT has the full steps, invocation, platform parity and verification. The public data and usage terms are in PRIVACY.md and TERMS.md.

Your first 15 minutes

Install — use the Claude commands or the Codex/ChatGPT instructions, then restart or refresh the selected host.

Pick a place to learn. cd into a folder you want to learn in (an empty one is fine). On your first project BodhiKit asks where to keep learning projects — the current folder is a fine answer — and creates learningWithBodhi/<topic>/ there. That is where your plan, progress, and review schedule live, and you can put it under git.

Start.

/bodhikit:learn <topic>

This is interactive. BodhiKit asks what is driving the topic and what "done" looks like, then runs a short adaptive assessment — around ten questions, roughly 10–20 minutes — so the plan starts from what you actually know rather than from zero. You will rate yourself before each sub-topic; the gap between your rating and your answers is the first thing the tutor learns about you. It ends with a personalized plan and a first small exercise.

Learn something.

/bodhikit:teach

The tutor explains the next concept in your plan, works a problem with you, hands you an exercise, and asks you to explain it back. It will not write the code for you. When you are stuck you get graduated hints — direction, then approach, then near-solution — and never a fourth.

Close the session.

/bodhikit:reflect

Three quick questions: what was hard, what you would do differently, how confident you feel — checked against what you actually did today, so the review schedule reflects evidence rather than mood.

Tomorrow: /bodhikit:continue. One command resumes where you left off: a 3-line check-in, any concepts due for review, the next lesson, and reflection.

BodhiKit loads 19 knowledge bases. To avoid polluting context in unrelated projects, enable it per-project instead of globally. In your learningWithBodhi/.claude/settings.json:

{
  "enabledPlugins": {
    "bodhikit@bodhikit": true
  }
}

Or disable it in projects where you do not need it by adding to .claude/settings.local.json:

{
  "enabledPlugins": {
    "bodhikit@bodhikit": false
  }
}

Upgrading from an earlier version? See MIGRATION.md — one command, /bodhikit:housekeep migrate, handles every tracking-file change since 1.6.

Feedback

BodhiKit currently has a very small number of real learners. If you try it, your experience is the most valuable thing you can send — one honest account of one session beats any feature request.

Full guide: see GUIDE.md — a complete worked example from Day 1 to capstone (10-week Rust journey), every skill with when to use / when not to / pairs well with / example, how teaching and analogies work, the spaced-review system, the optional capstone, and tips for using BodhiKit alongside books and courses.

Skills (18)

SkillDescription
/learnStart a new learning project with assessment and personalized plan
/continueResume from where you left off — auto-invokes check-in, teach, reflect
/teachProactive guided teaching: explain, demonstrate, practice, verify — or an understanding-only Feynman deep dive when that is all you want
/assessStandalone skill assessment on any topic
/reviewEducational code review (local files, GitHub, GitLab, Codeberg)
/quizActive recall check with spaced repetition tracking
/planView, adjust, or regenerate your learning plan
/progressProgress dashboard — plus quick (3-line check-in) and all (cross-project table with health flags)
/resourcesFind, verify, and manage learning resources
/practiceHands-on exercise calibrated to your level
/evaluateComprehensive evaluation of your learning journey
/reflectEnd-of-session metacognitive reflection
/mentorCareer and learning path guidance using the GROW model
/pairPair programming: strong-style, ping-pong, or navigator mode
/debug-togetherScientific debugging: reproduce, hypothesize, probe, isolate, fix
/forgetDemote a concept back to Box 1 — for honest self-assessment
/housekeepRotate tracking files into archive + summary form; one-shot 1.7.0 migration
/teach-backOptional capstone after completion: Socratic-style blog post on a formerly-shaky topic, master comparison, learner-decided publish

Agents (4)

Claude Code loads these as native agents. The OpenAI build preserves the same behavior as portable role procedures, so Codex may delegate when useful and ChatGPT can perform the procedure directly without depending on subagents.

AgentModelPurpose
skill-assessorSonnetAdaptive Bloom's taxonomy skill evaluation
code-reviewerSonnetEducational code review (what code reveals about understanding)
resource-finderHaikuWeb search for verified free learning resources
trajectory-analyzerSonnetReads full project history (sessions, archives, assessments) and returns a structured trajectory report — used by /evaluate so the heavy archive load happens in the agent's context, not the parent skill's

Knowledge Bases (19)

Each learning methodology lives in its own focused knowledge base, loaded only when needed (progressive disclosure). Since 1.18.1 they ship as model-only skills (skills/<kb>/SKILL.md, user-invocable: false) — hidden from the / menu, loaded through the Skill tool at the phase that needs them:

The OpenAI build converts the same 19 knowledge bases into progressively loaded references, preventing them from appearing as duplicate learner commands.

Knowledge BasePurpose
spaced-repetitionEbbinghaus forgetting curve, Leitner box system, update rules
blooms-taxonomy6 cognitive levels for programming, mastery criteria
feynman-technique4 steps for deep understanding, when to use
deliberate-practiceTargeted exercises at the edge of ability
growth-mindsetLanguage patterns, praising strategy over talent
metacognitionTeaching learners HOW to learn, Dunning-Kruger, confidence calibration
difficulty-calibrationVygotsky's ZPD (three zones, detection signals, gradual release), Sweller's cognitive load (worked examples, faded scaffolding, expertise reversal), Bjork's desirable difficulties (spacing, interleaving, retrieval, generation, variation, pretesting) — loaded as one
constructivismSpiral curriculum, project progression by level
ai-learning-safeguardsRisks of AI over-reliance, structural safeguards
mentoring-theoryGROW model, Kram's career and psychosocial functions
pair-programmingStrong-style, driver/navigator, ping-pong TDD, Williams & Kessler
scientific-debuggingTRAFFIC method, debugging mindset, wolf fence, expert vs novice
assessment-frameworkQuestion templates by Bloom's level, exercise design
evidence-kindsSubjects whose work is not code: problems checked against saved answers, writing against saved criteria, performed skills by practice reps and a graded debrief, photos (loaded only off the code path)
teaching-personalityVoice and tone — the four-teacher persona layer (patience, directness with care, "try it and see", education as empowerment); no pedagogy lives here
state-opsOperational surface: project discovery, the bodhi-state write path, session-type vocabulary, gate/mastery semantics — what every skill loads
state-schemaField-level reference for .bodhi/ tracking files (loaded only by manual carve-outs, fallbacks, and /housekeep)
state-lifecycleRotation, archiving, summary collapse, retirement (loaded by /housekeep only)
state-migrationSchema versioning + one-shot conversion procedures (loaded by /housekeep migrate)

Path-Scoped Rules (1)

RuleActivates On
learning-projectFiles inside learningWithBodhi/ directories

Learning Project Structure

When you start learning, BodhiKit creates a project folder. The v2 layout (1.7.0) uses live documents for the current state and archive directories for the historical detail — routine skills load only the live documents:

learningWithBodhi/
├── .bodhi-profile.json            # Top-level profile (career goals, cumulative stats)
├── .bodhi-profile.projects.json   # Per-project metadata (active + completed)
└── react-fundamentals/
    ├── .bodhi/
    │   ├── state.json             # Slim — current position, counts, streak
    │   ├── progress.md            # Latest session + "Summary of earlier sessions"
    │   ├── progress/archive/      # Full text of each archived session
    │   ├── plan/
    │   │   ├── README.md          # Arc overview, current phase pointer
    │   │   └── phase-{N}.md       # Per-phase detailed plan
    │   ├── assessments/
    │   │   ├── latest.md          # Most recent assessment + summary
    │   │   └── archive/           # Full text of each archived assessment
    │   ├── spaced-review.json     # Leitner box system for retention
    │   ├── assessment-history.json # Structured Bloom's-over-time data
    │   └── resources.md           # Curated resources
    ├── exercises/                 # Hands-on exercises
    ├── projects/                  # Larger project work
    ├── revision/                  # One take-home sheet per study day (written for you at session end)
    └── notes/                     # Your personal notes

We recommend backing this with git and a remote repository.

See docs/example-project/ for a realistic example of what these tracking files look like after a few sessions. Upgrading from any earlier version: run /bodhikit:housekeep migrate once per project — see MIGRATION.md.

How a Session Works

Run /bodhikit:continue and the plugin handles the entire flow:

/continue
  ├── check-in      → 3 lines from `bodhi-state snapshot`
  ├── spaced review → quiz on concepts due for review
  ├── /teach        → guided teaching of the next concept
  │     ├── explain with analogies and code examples
  │     ├── work through a problem together
  │     ├── independent exercise
  │     └── quick retention check
  └── /reflect      → end-of-session metacognitive reflection

One command. Complete learning session. No need to remember which skills to invoke.

The Science

BodhiKit integrates these methodologies from the learning-science literature. We stand on the shoulders of giants.

An honest note on the claim

  • BodhiKit's design follows the learning-science literature below — each mechanism cites its primary source and fires where the research says it should.

  • What we do not (yet) have is outcome data showing the plugin itself improves learning versus vanilla Claude; the thresholds and intervals are tuned on real but small-N usage.

  • "Research-informed" is a design claim, not an efficacy guarantee.

  • If you run real learning projects through BodhiKit and want to help change that, open an issue with your (anonymized) experience — what held, what decayed, where the calibration felt off. As of 1.11.3 this is one command: bodhi-state export-anonymized produces a shareable stats block (counts and rates only — no concept names, no free text), and the repo has a "Share your learning data" issue template for it.

  • bodhi-state retention shows you the same numbers privately: your %-correct at review time, by spacing gap and by box — the empirical check on whether the intervals are working for you.

  • The maintainer's own anonymized numbers — one learner, five projects, thin — are published in docs/outcomes.md and regenerated from bodhi-state export-anonymized. They are there to be falsifiable, not persuasive.

Evidence tiers

The citations below do not all carry equal weight, and each knowledge base declares which tier it sits in (since 1.11.2):

  • Load-bearing, most-replicated — retrieval practice, spacing, pretesting, worked examples, successive relearning. John Dunlosky et al., Improving Students' Learning With Effective Learning Techniques (2013), rates practice testing and distributed practice as the two highest-utility techniques of the ten reviewed.
  • Organizing frameworks — Bloom's, ZPD, and GROW give structure; they are not measured interventions.
  • Kept with explicit caveats — growth-mindset interventions show small-to-null average effects in meta-analyses (Sisk et al. 2018; BodhiKit uses only the low-cost language patterns), and deliberate practice's domain-generality claims are contested (Macnamara et al. 2014; BodhiKit uses only the uncontested core: targeted practice with immediate feedback).

Fencing the weak claims is what lets you trust the strong ones.

Want to know why each one is used and when it fires inside BodhiKit? See GUIDE.md → The Pedagogy Behind BodhiKit — per-methodology cards with what / why / when (skills + phases) / primary source, plus a "How they compose" table mapping methodology clusters to journey phases. The citations below are the primary sources; the GUIDE section explains how BodhiKit operationalizes them.

Reliability Architecture (1.11.0)

The 1.10.x release line proved a structural lesson: a spec being correct is not the same as a spec being binding on an LLM executor. 1.11.0 closes that class of bug at the architecture level instead of patching instances:

  • scripts/bodhi-state — a dependency-free Python CLI that performs every tracking-JSON mutation: Leitner box math, the Bloom ratchet, counter rules, sessionHistory vocabulary enforcement, the prerequisite-gate verdict, the mastery formula, migration with backup + verification. Skills decide what happened (the pedagogical judgment); the script decides what the file looks like. Unknown learner fields are preserved in code, atomically.
  • Two hook scripts (hooks/hooks.json): a SessionStart hook that injects the learning-project rule when a session starts inside a learning project (plugins cannot ship path-scoped rules; a cloud chat starts with no folder, so there the same script injects it when the first BodhiKit skill runs), and a Stop hook that runs bodhi-state verify on every project the session touched, wherever it is, before a session ends — broken tracking state blocks the stop once with a repair instruction instead of silently persisting, and a day that studied something does not end without its revision sheet (revision/YYYY-MM-DD-<concept>.md: the key idea in plain words, the worked example, where you slipped, two self-test prompts with answers, next review dates, free links from your saved resources).
  • A three-layer test harness (dev/eval/): a free deterministic suite covering every script contract (run by dev/check.sh on every change); headless LLM evals that run real skills against fixture projects and assert on the resulting file state — the automated successor to the manual dogfood passes of the 1.10.x line; and (1.12.0) grading-calibration evals — scripted learner answers of controlled quality asserted against honest grading bands (a jargon parrot must not pass the Feynman gate; missing trade-offs must cap tested-bloom at 4) — plus transcript-fidelity checks on the teaching protocol itself (pretest fires on first exposure, no fourth hint, ever). The deterministic layer makes the file mechanics trustworthy; the grading layer measures the judgment feeding them, and doubles as the model-drift detector.

Learn More

Read the full blog post on Medium — detailed scenarios, the science behind the plugin, and how to get the most out of it.

Uninstall

/plugin uninstall bodhikit@bodhikit

Your learningWithBodhi/ project folders are not affected.

License

MIT

Support

If this project saves you time, consider sponsoring. It keeps development going and lets me know people are finding it useful.

  

Made with ❤️ by Abhaya Code Labs

↑↓ navigate openesc close