Book Compressor

Book Compressor is a local-first EPUB compression tool.

Project identity (important)

This repository is the tailnet/self-hosted app for path-based deployment (/bookcompressor).

It is separate from any legacy/public-hosted deployment such as book-compressor.vercel.app. Do not mix code, runtime data, or release flow between those projects.

• Chat-first workflow (send EPUB to your AI gateway)
• Local permalink library for completed compressions (/<id>)
• Web upload fallback (drag/drop + file picker) for large/direct runs
• Generate chapter-by-chapter walkthroughs + final synthesis
• Export/import library JSON so users can share analyses without reprocessing EPUBs

Mini-app mode (Tailnet app)

This project is now structured to run as a local "hosted by you" app.

Default path:

• https://<device>.ts.net/bookcompressor

Default base path in this repo:

• /bookcompressor

You can override it at build/start time with:

• NEXT_PUBLIC_BASE_PATH
• or BOOK_COMPRESSOR_BASE_PATH

PWA note:

• Manifest id, start_url, and scope are scoped to this base path.
• This allows separate installs per app path on the same domain (for example /bookcompressor and /mindfeed).

Model access (no key field in UI)

The app no longer asks users to paste an API key in the form.

By default it uses the host's Hermes Agent model stack via:

• hermes chat -Q --ignore-rules -t safe

So if Hermes is already configured on the machine, users can run Book Compressor without adding a separate model key here.

Optional fallback mode:

• Set BOOK_COMPRESSOR_INFERENCE_PROVIDER=openrouter
• Then provide one of these env vars:
  • OPENROUTER_API_KEY (recommended)
  • OPENROUTER_KEY
  • OPENROUTER_API_TOKEN
  • AI_API_KEY
  • LLM_API_KEY

Core constraints

• No database
• No Supabase
• No persistent raw source-book storage by default
• Saved outputs are local JSON records on this machine (.runtime/books/*.json)

Local development

npm install
export NEXT_PUBLIC_BASE_PATH="/bookcompressor"
npm run dev -- --hostname 127.0.0.1 --port 3000

Prerequisite for default mode:

• Hermes Agent has a working model/provider on this machine

Open:

• http://localhost:3000/bookcompressor

Standard lifecycle scripts

# one-command guided setup (recommended)
./scripts/setup.sh

# prerequisite check (tailscale + Hermes + model smoke + port)
./scripts/prereq-check.sh

# install deps
./scripts/install.sh

# start in prod mode (build + next start)
./scripts/start.sh

# stop
./scripts/stop.sh

# status + recent logs
./scripts/status.sh

# configure tailscale path mapping
./scripts/serve-path.sh

# merge upstream main into your fork branch
./scripts/update-upstream.sh

Notes:

• install.sh runs prereq-check.sh automatically by default.
• To skip the check: BOOK_COMPRESSOR_SKIP_PREREQ_CHECK=1 ./scripts/install.sh
• prereq-check.sh now prints explicit safe fix hints when a requirement is missing and writes a report to .runtime/prereq-report.txt.

AI-guided resilient setup loop

If prerequisites are missing, use this loop:

1. Run ./scripts/prereq-check.sh
2. Fix one required issue from the script's "Suggested safe fixes"
3. Re-run ./scripts/prereq-check.sh
4. Repeat until all required checks pass
5. Run ./scripts/setup.sh

Safety rule: any sudo or package-manager command should be user-approved before running.

Optional runtime env vars:

• BOOK_COMPRESSOR_MODE=prod|dev (default prod)
• BOOK_COMPRESSOR_HOST=127.0.0.1 (default 127.0.0.1)
• BOOK_COMPRESSOR_PORT=3000 (default 3000)
• NEXT_PUBLIC_BASE_PATH=/bookcompressor (default /bookcompressor)
• BOOK_COMPRESSOR_INFERENCE_PROVIDER=hermes|openrouter (default hermes)
• BOOK_COMPRESSOR_HERMES_BIN=/path/to/hermes (optional explicit CLI path)
• BOOK_COMPRESSOR_AI_TIMEOUT_MS=300000 (default 300000)

API routes

With default base path /bookcompressor, the effective routes are:

• POST /bookcompressor/api/summarize-chapter
• POST /bookcompressor/api/synthesize-book
• GET /bookcompressor/api/health
• GET /bookcompressor/api/books (list local saved books)
• POST /bookcompressor/api/books (save a completed compression)
• DELETE /bookcompressor/api/books (clear all saved books)
• GET /bookcompressor/api/books/export (export full local library as JSON)
• POST /bookcompressor/api/books/import (import one/many books into local library)
• GET /bookcompressor/api/books/:id (load one saved book)
• DELETE /bookcompressor/api/books/:id (delete one saved book)
• GET /bookcompressor/api/books/:id/export (export one book as JSON)

Permalink pages:

• /bookcompressor/:id

Privacy model

Book processing runs on this machine.

By default:

• raw source-book content is not permanently stored by the app
• completed outputs (chapter summaries + synthesis + metadata) are saved locally in .runtime/books/
• no external database is used

Legal model

Users must have rights or permission to process uploaded content.

Fork + re-sync workflow

If you cloned this repo directly (no fork)

git pull --ff-only origin main
./scripts/start.sh

If you forked and customized

1. Add upstream once:

git remote add upstream https://github.com/humanitylabs-org/bookcompressor.git

2. Re-sync updates anytime:

./scripts/update-upstream.sh
./scripts/start.sh

Customization-safe practice:

• Keep your custom UI changes in your own branch/fork.
• Pull upstream regularly and resolve conflicts in your branch.
• Prefer env-based settings for deploy details (port, base path, provider) so updates stay low-friction.