Shadow Tutor

Shadow Tutor

A post-session programming tutor that runs inside your own Codex or Claude Code session. After you finish a chunk of AI-assisted work, it teaches you why the AI made each decision and drills you with forced-recall exercises — so your skills actually grow.

English · 中文

The problem

AI coding agents (Codex, Claude Code) let a novice ship things that run — but that they don't understand. Learning happens in the struggle, and the AI removed the struggle. The result: an ability illusion and permanent dependence. Junior engineers stay junior, because the productive friction where skill is built has been optimized away.

Shadow Tutor puts that friction back — without destroying productivity.

What it is

An in-session skill that runs in your own Codex or Claude Code session:

• No separate CLI to babysit, no hooks, no external API. You invoke /shadow-tutor inside the session.
• Uses your own quota. The review is generated in your current session, on the subscription you already pay for.
• Native skill on both Codex and Claude Code. Both use the identical skill format (<skills>/<name>/SKILL.md + name/description), so the same skill/SKILL.md + METHODOLOGY.md is installed into each — zero fork.

Why this is so simple: when you invoke it in-session, the model already has the whole session in context — its own reasoning, every diff, every decision. There's no need to reconstruct the session from logs, so adapters, subprocesses, and log parsing all disappear. The entire product is one high-quality teaching methodology (METHODOLOGY.md) plus a per-user knowledge profile.

How it works

You code with the AI as usual → reach a stopping point → /shadow-tutor → it:

1. Reads your knowledge profile ~/.shadow-tutor/knowledge.json (to suppress what you already know);
2. Picks 3–5 points from this session you most likely missed but that matter (cite-evidence-first, then teach);
3. Explains why this and not that for each (including the options the AI rejected), every point bound to your real code;
4. Walks you through 2–3 forced-recall exercises; where tests exist, it runs them to grade;
5. Updates your profile, so next time it won't re-teach what you've learned.

Install

# Option A — one-liner via npx (cross-platform, installs into both tools)
npx shadow-tutor install            # or: npx shadow-tutor install cc | codex

# Option B — Claude Code plugin marketplace
#   /plugin marketplace add lzfxxx/shadow-tutor
#   /plugin install shadow-tutor@shadow-tutor

# Option C — Codex skill-installer, straight from this repo
#   $skill-installer https://github.com/lzfxxx/shadow-tutor

# Option D — clone and run the installer
git clone https://github.com/lzfxxx/shadow-tutor && cd shadow-tutor
./install.sh                        # or: ./install.sh cc | ./install.sh codex

Then, in either tool, finish some coding and invoke /shadow-tutor.

What a review looks like

See examples/sample-review.md for a full real review (scored 15/16 by the eval rubric). A taste:

[decision] useMemo here isn't for "performance" — it's to avoid recomputing on unrelated re-renders

Why it did it this way: writing products.filter(...) directly in render is fine for small arrays — the AI considered exactly that. The real motivation: the component re-renders for reasons unrelated to filtering… The underlying concept you're missing: a React component function is called repeatedly, and everything in its body recomputes by default.

Exercise (fill-the-faded-blank): complete the dependency array. If you wrote only [query], what exact symptom would the user see?

Repository layout