Flat Chat Threads Suck for Reading Books. So I Built a Local-First AI Tree Companion.

I was reading books with Pi in the terminal — a minimalist AI agent with tree-structured conversations — and it was genuinely the best way I'd ever read non-fiction. Branch into a tangent, explore it deeply, jump back without losing context. Every session was a map of how I actually thought about the material.

But it was a terminal tool. My wife reads more books than I do. My kids are curious about everything but need something they can click around in. My parents would never open a terminal. The gap between "this is incredible" and "nobody else can use it" felt like a problem worth solving.

So I built pi-books — an open-source, local-first reading companion that turns any book into a conversation you navigate like a tree.

The Problem with Flat Chat

Most AI tools treat books the same way they treat any prompt: paste text in, get an answer, context gone. You go on a tangent — "wait, how does this connect to X?" — and now your entire thread is polluted. There's no structure, no persistence, no sense of journey through the material.

The Solution: Tree-Structured Conversations

Instead of one long flat thread, pi-books structures your reading as a topic tree.

• Branches on semantic shifts — go deeper, switch chapters, follow a tangent. Each gets its own branch with full context preserved. Jump back to the main branch anytime, zero contamination.
• The chat IS the reader — no separate reader and chat window. The AI surfaces book content as quotes directly in the conversation.
• Zoom in and out — dive deep on a concept, then pull back to a summary without losing your place.
• Every user gets their own tree — multiple people (family, book club) can read the same book independently, each with their own conversation tree, glossary, and reading history.
• Clickable navigation — side-by-side Table of Contents and Topic Tree. Click any node to jump back in time and context.

🔒 100% Local-First & Private

Everything runs on your machine — books, sessions, conversations, glossaries. No cloud account, no subscription.

• Cloud APIs: DeepSeek, Gemini, Claude — cheap and fast.
• Fully offline: Point it at Ollama or LM Studio. Zero cost, nothing leaves your network.

Book reading doesn't need frontier-class models. Smaller, faster models work great — see the README for recommendations.

🛠️ The Stack

packages/
  shared/      — Shared TypeScript types
  extension/   — Pi SDK skills, ebook parsers, plugins
  server/      — Hono API server (tree manager + SQLite/Drizzle)
  client/      — React + Vite frontend

Built on the Pi SDK for tree-structured agent conversations, Hono for a lightweight server (Electron-friendly), and SQLite with Drizzle ORM for metadata.

One thing I'm particularly proud of: AI behavior is controlled entirely by Markdown files. Each reading "skill" (summarize, deep-dive, quiz, etc.) is just a .md file in the extension/skills/ folder. Want to change how the AI reads? Edit a markdown file. No code changes, no redeployment. This makes it very hackable — you can create your own reading skills in minutes.

🚀 Getting Started

Docker (one command):

docker run -d --name pi-books \
  --env-file .env \
  -p 3847:3847 \
  -v /path/to/your/books:/library:ro \
  -v pi-books-data:/data \
  ghcr.io/shuowu/pi-books:latest

Local dev:

git clone https://github.com/shuowu/pi-books.git
cd pi-books
cp .env.example .env   # add your model config / API key
npm install && npm run dev

💬 Looking for Feedback!

This is early-stage and I'd love your input:

1. What's your current workflow for reading books/papers with AI? What's broken?
2. What custom reading "skills" would you build?
3. Would you use this? What's missing?

⭐ github.com/shuowu/pi-books — star it, try it, tell me what you think!