epub-visualizer

epub-visualizer — BookSlayer

A Claude Code Agent Skill that turns a technical .epub into a navigable, self-contained visual study-site.

Each section of the book becomes a beautifully designed HTML "plano" that re-teaches it — concept-complete (every definition, number, example and distinction is kept) with the narrative prose cut, plus diagrams, analogies, a glossary, reading progress, and cross-links between sections. Every page is a single file that opens with a double-click (file://) — no server, fully offline.

The name comes from the first book it ate: Designing Data-Intensive Applications → 134 linked study pages, 890-term glossary, every figure embedded.

What it produces

out/site/
  index.html          ← cover + full sidebar (the entry point, double-click this)
  glossary.html       ← every term → the plano that defines it
  plano_0001.html …   ← one self-contained page per book section

Run with --export and it also drops a clean, shareable copy in a folder named after the book, ready to zip.

Install

This repo is a Claude Code plugin marketplace containing one plugin (epub-visualizer), which in turn bundles the skill. Two ways to install:

A) Via the plugin marketplace (recommended)

In a claude session:

/plugin marketplace add th0rz05/epub-visualizer
/plugin install epub-visualizer@epub-visualizer

Claude Code clones the repo and registers the skill. Update later with /plugin marketplace update epub-visualizer.

B) Manual (copy the skill folder)

A skill is just a directory with a SKILL.md. Copy the inner skill into your personal skills folder:

git clone https://github.com/th0rz05/epub-visualizer.git /tmp/epub-visualizer
cp -R /tmp/epub-visualizer/skills/epub-visualizer ~/.claude/skills/epub-visualizer

Claude Code then discovers it automatically.

One-time setup (Python deps)

Either way, the skill's scripts need three packages. They live in a virtualenv inside the skill directory (${CLAUDE_SKILL_DIR} resolves to it wherever it's installed), so you do this once and every book reuses it:

# ${CLAUDE_SKILL_DIR} is the installed skill's folder — e.g.
#   ~/.claude/skills/epub-visualizer            (manual install), or
#   ~/.claude/plugins/.../skills/epub-visualizer (marketplace install)
python3 -m venv "${SKILL_DIR}/.venv"
"${SKILL_DIR}/.venv/bin/pip" install ebooklib beautifulsoup4 lxml

Nothing is ever copied into your project except the generated ./out/ folder.

Use

In a claude terminal session, just point it at a book:

Turn this into a visual study site:  ~/Downloads/some-book.epub

or simply "use epub-visualizer on this epub". The skill triggers and runs the pipeline:

1. Chunk the epub into one section per real heading (deterministic, no LLM; verifies no word is lost).
2. Generate one plano per section — concept-complete HTML, with figures and hand-drawn diagrams.
3. Verify each plano with a fresh-eyes pass that flags any teachable item missing vs. the source, then patches it ("no concept lost").
4. Assemble the site — builds index.html + glossary.html, bakes cross-links, and inlines every asset (CSS, JS, images as base64) so each page stands alone.

The full contract Claude follows is in SKILL.md.

Notes on cost & resumability

• Run interactively in a claude terminal on a Pro/Max subscription. Best results generating with Opus and verifying with Sonnet (a cheaper, mechanical check).
• All state lives on disk in ./out/, so a run is resumable: hit a usage limit, /clear, or close the laptop → next session reads what's on disk and continues. Just say "continue the book."

How it's wired (for the curious)

epub-visualizer/                       the repo = a one-plugin marketplace
  .claude-plugin/
    marketplace.json                   lists the plugin (source: this repo)
    plugin.json                        the plugin manifest
  skills/
    epub-visualizer/                   the skill (one self-contained directory)
      SKILL.md                         the instructions Claude loads when the skill triggers
      scripts/
        book_chunk.py                  epub → out/chunks/*.txt + out/images/ + manifest.json
        rebuild_state.py               plano sidecars → glossary.json + outline.json (the memory)
        build_site.py                  index + glossary + cross-links + asset inlining + export
        rough.js                       vendored rough.js for hand-drawn diagrams (auto-installed)
      template/
        plano_template.html            the design contract for each page
        plano.css                      the shared stylesheet (auto-installed + inlined by build)
  README.md  ·  LICENSE

Scripts are invoked via ${CLAUDE_SKILL_DIR} and write only to your project's ./out/, so the skill is fully self-contained and portable across machines.

License

MIT — see LICENSE. This covers the skill (code + templates) only. Books you process are your own; the skill never bundles or distributes book content. scripts/rough.js is vendored from rough.js (MIT).