Your agent fixed the bug.
lesson makes sure you learn why.

Step 01 — You start a session

You type /lesson with a short note about what you’re working on.

Example: /lesson useEffect infinite loop in React. Your agent runs the /lesson slash command, which is just a prompt that tells it to set up a folder for this session. No AI thinking is needed here — it’s mostly bookkeeping.

The agent creates a new session folder and a few tiny files inside it:

.claude/lessons/
├── active-session              ← one line: the session's slug
└── sessions/20260419-1430-useeffect/
    ├── meta.json              ← your goal, start time, working dir
    ├── arc.jsonl              ← empty — will fill up as you work
    └── counter                ← the number "0"

The active-session file is the switch. If it exists, tracking is on. If it doesn’t, the plugin does nothing. That one file is how the whole system stays silent until you want it.

Step 02 — You work, silently watched

Every tool call the agent makes fires a hook. The hook is the ears.

Claude Code has a feature called hooks — small scripts that run after every tool use (reading a file, running a command, editing code). The lesson plugin registers one of these hooks. It’s a ~200 line Python script called post_tool_use.py.

Here is what the hook does, in order, every single time you use a tool:

1. Check if .claude/lessons/active-session exists. If not, exit silently. No session, no work.
2. Score the tool call for significance. Was it an error? An edit? Did the output mention a version number? Simple heuristics, no AI.
3. Append one line to arc.jsonl describing what happened: tool name, arguments, result snippet, whether it errored.
4. Increment the counter file. One more event logged.
5. Exit with status 0. The hook never prints to your conversation.

A line in arc.jsonl looks like this:

{"ts": 1713542400.1, "tool": "Bash",
 "args": "{\"command\":\"npm test\"}",
 "result_head": "FAIL  src/App.test.tsx ...",
 "is_error": true, "significant": true}

Notice the significant: true flag. That’s the signal that will later decide: does this moment make it into the lesson, or does it get filtered out as noise? Reading a dozen files to warm up the context is noise. A test failing with a specific error is signal.

Step 03 — Every 25 events, the graph is rebuilt

When the counter hits 25, the hook quietly launches a second program that turns the raw log into a structured knowledge graph.

The hook doesn’t do the heavy work itself. It launches a detached subprocess called lesson compress and immediately returns. The subprocess runs in the background, takes about 50 milliseconds, and never talks to your conversation. It’s a pure Python pipeline — zero LLM tokens used.

Here is what lesson compress does:

1. Read every line of arc.jsonl.
2. Score each event with TF-IDF + error signal + edit signal. Novel content scores high. Repeated noise scores low.
3. Promote the top-scoring events into typed graph nodes: goal, observation, hypothesis, attempt, concept, resolution.
4. Deduplicate using cosine similarity on sentence embeddings — two events that say the same thing collapse into one node.
5. Wire edges between nodes to encode causality, not just order: motivated, produced, revealed, contradicted.
6. Find the root cause by running betweenness centrality on the graph. The concept node with the highest centrality is tagged root_cause: true.
7. Save the graph to session_graph.json and reset the counter to 0.

The graph is incremental. The next time compression runs, it reads the existing graph, folds in the new events, and saves the updated version. Node IDs never change — o1 is o1 forever.

Step 04 — You ask for the lesson

You type /lesson-done. The agent reads the graph and writes a textbook.

This is the one step where the AI actually does significant work. The /lesson-done slash command is a long, detailed prompt that walks the agent through generating a grounded lesson.

The agent:

1. Reads session_graph.json — the distilled story of your session.
2. Reads ~/.claude/lessons/profile.json — your learner history. If this is a misconception you’ve had before, the lesson will say so.
3. Identifies the root cause concept, the misconception that tripped you up, the pivotal moments, and the prerequisites you need to understand it.
4. Optionally does web research if the concept needs external sources (like a specific kernel version or a library’s release notes).
5. Fills in a markdown template with: narrative, foundations, explanation of the concept, mermaid diagrams of the session, quiz questions, and citations.
6. Writes .claude/lessons/output/<slug>.md, runs a script to render a PDF, updates your profile, deletes active-session, and reports back.

What you end up with: a real lesson. Grounded in your session. Keyed to your mistakes. Something you can re-read a year from now and actually learn from.