LangGraph multi-agent pipeline that monitors Claude Code's CHANGELOG.md and generates validated tutorials for new features.
A supervisor-subagent pattern built on LangGraph:
fetch_changelog → diff_features → [feature loop]
│
supervisor
╱ │ ╲
researcher writer script_generator
│
validator ↔ script_fixer
│
save_tutorial → next feature
| Layer | Files | Purpose |
|---|---|---|
| State | state.py |
PipelineState TypedDict with reducer annotations |
| Graph | graph.py |
StateGraph assembly, routing helpers, conditional edges |
| Agents | agents/supervisor.py |
Routes work via structured output (RouteDecision) |
agents/researcher.py |
Classifies feature type, gathers context | |
agents/writer.py |
Generates tutorial markdown | |
agents/script_generator.py |
Creates executable demo scripts | |
agents/validator.py |
Runs scripts in sandboxed subprocess | |
agents/script_fixer.py |
Repairs scripts that fail validation | |
| Nodes | nodes/fetch.py |
Fetches CHANGELOG.md from GitHub |
nodes/diff.py |
Parses changelog, filters already-processed features | |
nodes/save.py |
Writes tutorial files, updates DB | |
| DB | db.py |
SQLite tracking for processed features |
| CLI | cli.py |
Click-based CLI (tutgen run/status/list) |
python -m venv .venv source .venv/bin/activate pip install -e ".[dev]"
Required environment variables (.env or exported):
ANTHROPIC_API_KEY=sk-ant-...
# Full pipeline — fetch changelog, generate tutorials for all new features tutgen run # Limit to N features tutgen run --limit 3 # Preview what would be generated (no LLM calls) tutgen run --dry-run # Check processing status tutgen status # List generated tutorials tutgen list
Output is written to tutorials/<date>-<slug>/ with tutorial.md and demo.sh.
The pipeline generates scripts that mirror realistic Claude Code usage:
- Session chaining (primary) — captures
session_idvia--output-format json, then uses--resumefor multi-step workflows - Slash commands (
/simplify,/cost, etc.) — demonstrated via session chaining since they are interactive commands used inside Claude sessions, not standalone CLI args - File-based workflows — creates project files, then uses session chaining for iterative work
- Simple one-shots —
claude -pfor standalone demos only
pytest tests/ -v
42 tests covering all agents (mocked LLM), nodes, graph construction, routing, and save logic.
src/tutorial_gen/
├── agents/ # LLM-powered subagents
│ ├── __init__.py # Shared extract_script utility
│ ├── supervisor.py
│ ├── researcher.py
│ ├── writer.py
│ ├── script_generator.py
│ ├── script_fixer.py
│ └── validator.py
├── nodes/ # Non-LLM processing nodes
│ ├── fetch.py
│ ├── diff.py
│ └── save.py
├── prompts/ # Prompt templates per agent
├── state.py # PipelineState schema
├── graph.py # StateGraph construction
├── db.py # SQLite feature tracking
└── cli.py # CLI entry point
tests/
├── test_agents.py
├── test_diff.py
├── test_fetch.py
├── test_graph.py
├── test_save.py
├── test_supervisor.py
└── test_validate.py