Course Builder — a kit for generating self-paced courses

Builds long-form, fact-checked, self-paced courses on any topic, plus a beautiful self-contained reading app to read them in (sidebar nav, progress tracking, search, light/dark themes, rendered math, optional natural-voice audio with synced read-along highlighting).

Install (Claude Code plugin)

In Claude Code:

/plugin marketplace add vishnutskumar/course-builder-kit
/plugin install course-builder@course-builder-kit

Two skills do everything:

• /course-builder:setup — one-time. Picks local (default) or remote hosting, creates your courses root (default ~/courses), installs the tiny HTTP server as a user service (launchd on macOS, systemd user unit on Linux — no sudo), and optionally installs the Kokoro audio toolchain (uv/pip venv, ffmpeg + espeak-ng, GPU-aware torch). Re-running it reconfigures safely.
• /course-builder:new-course — generates a course end to end (curriculum design → web research → long-form modules → fact-check), builds the reading app into your courses root, rebuilds the landing index (the library's landing page), and prints the URL.

That's it: install, /course-builder:setup once, then /course-builder:new-course whenever you want a new course.

Platform notes

• Windows: no service install — after generating, serve manually with python _serve.py from your courses root (set COURSES_ROOT/PORT env vars as needed), or just open site/index.html in a browser.
• HTTPS: the bundled server speaks plain HTTP on your LAN/tailnet. For HTTPS (required for offline audio caching and PWA installs beyond localhost), put it behind a TLS reverse proxy such as Tailscale Serve or Caddy — no automation is provided.

What you need

• Claude Code — the generator is a Claude Code workflow, not a standalone CLI.
• Python 3 — for the site builder and server. No third-party packages needed to generate, read, or host.
• rsync/ssh only for remote hosting; ffmpeg, espeak-ng, and the requirements-audio.txt venv only if you want audio. Both are optional.

What's in the kit

.claude-plugin/                plugin + marketplace manifests
skills/                        the setup and new-course skills
workflow/course-builder.js     the Claude Code workflow that generates a course
course-template/               the reading app + build scripts installed per course
  site/                        app assets, build_site.py, make_audio.py, text_normalize.py
  publish-course.sh            build a finished course; publish in place (--local) or rsync to a server
  USAGE.md                     the detailed manual
server/                        self-hosting pieces (server, landing index, PWA, service templates)
requirements-audio.txt         deps for the OPTIONAL Kokoro TTS audio pipeline
scripts/scan_personal.py       repo hygiene: flags personal paths/emails/hosts
tests/                         stdlib-only test suite (each file runs standalone)

Audio (optional)

make_audio.py pre-renders each module to natural-voice audio (Kokoro af_heart, 24 kHz → AAC) with per-block timing sidecars that drive the synced read-along highlight in the player. /course-builder:setup offers to install the toolchain for you; manual setup is in the header of requirements-audio.txt. Devices: --device {auto,cuda,mps,cpu} (auto picks CUDA when available, else CPU; Apple-GPU mps is explicit opt-in). The renderer is incremental (per-module content hash) and prunes audio for deleted modules. Text-to-speech normalization lives in text_normalize.py and has its own test suite: python3 course-template/site/test_text_normalize.py.

Manual use (no plugin)

Everything also works from a plain clone of this repo.

1. Generate a course — in Claude Code, run the workflow by path:

Workflow({ scriptPath: "<repo>/workflow/course-builder.js", args: {
  topic: "Special relativity, from first principles",   // REQUIRED
  title: "Special Relativity",
  slug: "special-relativity",          // folder + URL + storage id
  outRoot: "/Users/YOU/study",         // ⚠️ a folder you own — always pass this
  audience: "software engineer, comfortable with calculus, no physics background",
  preferences: "computational rigor; worked examples; lots of intuition",
  targetModules: 18,
  factCheck: true
}})

It designs the curriculum, researches each module on the web, writes the long-form modules (LaTeX math supported), and fact-checks each one against the internet, correcting in place. Output lands in <outRoot>/<slug>/.

2. Read it locally (no server):

cp -R course-template/site/* "<outRoot>/<slug>/site/"
python3 "<outRoot>/<slug>/site/build_site.py"     # builds content.js
open "<outRoot>/<slug>/site/index.html"           # double-click works too

The app is fully self-contained — KaTeX, Markdown, and syntax-highlighting libs are vendored under site/assets/vendor/, so it works offline.

3. Host it: course-template/publish-course.sh builds the site, optionally renders audio, then publishes:

# in place, into the served root that holds _build_index.py (no rsync/ssh):
COURSE_TEMPLATE="$PWD/course-template" course-template/publish-course.sh --local "<outRoot>/<slug>"

# or to a remote box over ssh (rsyncs to ~/courses/<slug>/, rebuilds the index there):
COURSE_TEMPLATE="$PWD/course-template" course-template/publish-course.sh "<outRoot>/<slug>" my-ssh-alias

The server/ folder has the hosting side: a tiny HTTP server (_serve.py), landing-index generator (_build_index.py), PWA bits, launchd/systemd user service templates, a systemd unit example for a dedicated box, and render_all_audio.sh for batch re-renders. Remote mode assumes an SSH alias you configure (COURSE_HOST, default pi).

For the simplest hosting, skip all of that: cd into the course folder, run python3 -m http.server 8000, and browse to http://localhost:8000/site/.

Contributing / hygiene

The repo uses pre-commit: pre-commit install after cloning, plus brew install detect-secrets (or pipx install detect-secrets) — the hooks run as language: system, so the scanner must be on your PATH. Hooks scan staged changes for secrets (detect-secrets) and for personal information — home-directory paths, private emails, hostnames — via scripts/scan_personal.py, which you can also run standalone over the whole tree:

python3 scripts/scan_personal.py

Tests are plain stdlib scripts — no pytest, no third-party deps. Each file runs standalone:

for t in tests/test_*.py; do python3 "$t" || break; done
python3 course-template/site/test_text_normalize.py

See CLAUDE.md for the full contributor conventions.

Notes

• Each course keeps its own reading progress in the browser (keyed by course id); the theme is shared across courses on the same origin.
• course-template/USAGE.md is the detailed manual.