lesson

lesson

An AI coding plugin that turns real working sessions into grounded, reusable lessons.

lesson watches tool activity inside a live AI session, keeps a compact record of the important turns, and turns the final arc into a lesson built from your actual files, commands, errors, and wrong assumptions.

Instead of generating a generic tutorial from scratch, it produces a lesson about what really happened:

• what you were trying to do
• where it broke
• which concept was actually missing
• why the misconception was believable
• what fixed it
• how to test whether you now understand it

/lesson react useEffect infinite loop when depending on an object
# work normally
/lesson-done

.claude/lessons/
├── sessions/<slug>/
│   ├── meta.json
│   ├── arc.jsonl
│   ├── session_graph.json      # created after the first compression cycle
│   └── arc.jsonl.archive.N
└── output/
    ├── <slug>.md
    ├── <slug>.pdf              # optional
    ├── index.html
    └── map.html

---

Why This Exists

Most learning tools start with a topic and invent an explanation.

lesson starts with a real failure path.

That difference matters. A working session contains high-quality teaching signal: the commands you ran, the outputs you misread, the hypotheses you formed, the file edits you tried, and the observation that finally changed your mind. That is the raw material a serious lesson should be built from.

Generic tutorial	lesson
Starts from an abstract topic	Starts from your actual session
Uses canned examples	Uses your files, errors, and commands
Explains the concept in general	Explains why you got stuck
Often guesses at relevance	Has a concrete arc to teach from

---

Platform Support

Works across 10 AI coding platforms. One install script, one core format.

Platform	Hook support	Config location	Command prefix
Claude Code	PostToolUse + Stop (automatic)	~/.claude/hooks.json	/lesson
Codex	None (manual logging)	~/.codex/CODEX.md	$lesson
Cursor	None (manual logging)	<project>/.cursor/rules/lesson.mdc	/lesson
Gemini CLI	BeforeTool (optional)	~/.gemini/GEMINI.md	/lesson
GitHub Copilot CLI	None (manual logging)	~/.github/copilot-instructions.md	/lesson
OpenCode	None (manual logging)	~/.opencode/OPENCODE.md	/lesson
OpenClaw	None (manual logging)	~/.claw/CLAW.md	/lesson
Factory Droid	None (manual logging)	~/.droid/DROID.md	/lesson
Trae	None (manual logging)	~/.trae/TRAE.md	/lesson
Google Antigravity	None (manual logging)	<project>/.agent/lesson.md	/lesson

On platforms with hooks (Claude Code, Gemini), event logging is automatic. On all others, the AI logs significant events manually to arc.jsonl during the session.

---

What Ships Today

• Silent-by-default tracking. Once /lesson starts, the plugin never speaks to the main conversation until you call it back. No reminders, no exit blocks, no model nags.
• Session tracking via hooks (Claude Code, Gemini) or manual LLM logging (all other platforms)
• Deterministic compression — lesson compress CLI runs EventGraphBuilder in ~50 ms with zero LLM tokens. The PostToolUse hook spawns it in a detached subprocess at the 25-event threshold.
• Session knowledge graph (session_graph.json) — structured causal record of the session
• Cross-session learner profile at ~/.claude/lessons/profile.json — tracks recurring misconceptions and concepts across all projects and platforms
• "You've hit this before" callout when the same misconception recurs
• Per-session token tracking with cost estimates
• Canonical markdown lesson output with YAML frontmatter
• Best-effort PDF rendering with Mermaid diagrams rendered as SVG
• /regenerate [notes] to rewrite the latest lesson with new guidance
• /lesson resume to continue a paused session
• /lesson-profile to display your learning history and token usage
• /lesson-index to build a browsable lesson list
• /lesson-map to build a concept map across generated lessons
• lesson CLI — use the compression and graph tooling standalone, outside of any AI assistant
• Eval framework — measure compression quality (node F1, edge accuracy, graph quality score)

---

Install

Requirements

• Python 3.10+
• An AI coding platform listed above
• Optional for PDF export:
  • npx with @mermaid-js/mermaid-cli
  • pandoc plus weasyprint, wkhtmltopdf, xelatex, or pdflatex
  • or a Chromium-based browser for the fallback renderer

Python Package