ReadAware

ReadAware

A Claude Code plugin that reads a long book with you. It doesn't hand you a book report — it's your co-reader: you throw it a passage, it pinpoints the volume/chapter that passage belongs to, then reads it closely the way you, specifically, want to be read to.

The premise: close reading is personal. The same paragraph of The Brothers Karamazov should be unpacked one way for a philosophy student and another for someone reading it for the first time at midnight. ReadAware separates who you are, what the book is, and how to read into three independent skills that talk to each other through files on disk — so each can be triggered and re-run on its own.

The three skills

Skill	What it does	When to use it
readaware:onboarding	Interviews you and builds/updates your reading-preference profile	First run, or when you want to change "how it should talk to me"
readaware:ingest	Imports a book into a locatable structure	Adding a new book
readaware:read	The co-reading loop: locate the passage → analyze it per your profile	Every time you paste a passage and want to read it closely

The division of labor: onboarding owns "who you are", ingest owns "this book", read owns "how to read". Style lives entirely in your profile; read only carries the method of reading a book accurately and thoroughly — it never bakes in a voice.

Where data lives (global, reused across projects)

~/.claude/readaware/
├── profile.md              # onboarding output: the reader's preference profile
├── state.json              # which book is active: {"active_book": "<slug>"}
└── books/
    └── <slug>/
        ├── text.txt        # ingest output: cleaned body text
        ├── manifest.json   # ingest output: part/chapter structure, front/back-matter bounds
        └── card.md         # optional: this book's motifs/characters/structure, for read to reference

Body text and structure are inputs — they sit in the global library, so read works from any directory. The notes and writing you produce are your own output and stay wherever you work; this plugin doesn't touch them.

Scripts

scripts/
├── common.py           # shared: paragraph loading + text normalization
├── extract_text.py     # used by ingest: .epub/.html/.txt → one-paragraph-per-line body + epub TOC sidecar (pure stdlib, no pandoc)
├── build_manifest.py   # used by ingest: build part/chapter structure → manifest.json
├── verify_manifest.py  # used by ingest: objective pass/fail check that the parse matches the text
└── locate.py           # used by read: read the manifest, locate a passage → part/chapter + context

The key design rule: all knowledge of "what this book looks like" lives in ingest; locate.py stays universal, forever. Switching translation or layout means re-running ingest — never editing the locator.

Structure is resolved in order of reliability:

• For .epub, extract_text.py reads the book's own NCX/nav table of contents and writes a text.struct.json sidecar; build_manifest.py uses that authoritative part/chapter list (epub-struct mode) — no pattern-guessing, so author initials like "V." aren't mistaken for a chapter and chapter numbers that live in markup aren't missed.
• For a .txt, it falls back to layout auto-detection across Chinese (第X卷/第X章/bare 一 标题) and Western (Part/Book + Chapter, Arabic/Roman numbering) editions — using an in-text table of contents when present (toc), or scanning the body directly when not (scan).

The volume/part layer is optional either way — flat chapter-only books work too. Unusual .txt layouts can still be nudged with --part-re / --chap-re / --epilogue / --front / --back; readaware:ingest walks you through it.

No parser fits every book, so ingest verifies and self-repairs: verify_manifest.py gives an objective pass/fail (catching things like citation initials mistaken for chapter numbers, or a whole book collapsed into "one chapter"), and on failure ingest escalates — tune parameters → hand-author a text.struct.json sidecar → fix manifest.json directly — always as data in the book's own directory, never by editing the shared scripts.

Install / local testing

claude --plugin-dir /path/to/readaware
# then: /readaware:onboarding → /readaware:ingest → /readaware:read

A typical first run:

1. /readaware:onboarding — answer a short interview; it writes profile.md.
2. /readaware:ingest — point it at a .txt/.epub/.html; it builds text.txt + manifest.json, and you eyeball the parsed table of contents with --toc before committing.
3. /readaware:read — paste any passage from the book; it locates the part/chapter and reads it closely in your voice.

Roadmap