I Built an AI Reading Companion with Tree-Structured Conversations

AI makes you productive where you already understand. It confuses you where you don't.

I've been reading non-fiction with AI assistants for a while, and I kept hitting the same wall: 30 messages into a conversation about a dense book chapter, the AI starts losing the thread. I'd branch into a tangent — "how does this connect to what Kahneman said about System 1?" — and suddenly the entire chat context is polluted. No way to get back to where I was.

So I built pi-tree — a self-hosted AI reading companion where the conversation is the reading experience. The key insight: conversations should be trees, not threads.

Why Trees?

When you think through complex material, your mind doesn't work linearly. You branch — "wait, how does this relate to X?" — explore for a bit, then come back. But every AI chat tool forces you into a flat thread where everything piles up.

Tree-structured conversations fix this at the architecture level:

• Focused context — Each branch carries only its path from root to current node. Less noise → more accurate responses.
• Token savings — A 50-message linear chat sends all 50 every turn. A tree with 5 branches of 10 sends only ~10. Lower cost, faster responses.
• Less hallucination — Context pollution is a primary cause of hallucination in long conversations. Isolated branches keep the model grounded.

Here's what a reading session looks like:

📖 Reading: Thinking, Fast and Slow (Kahneman)

Root
├── What is System 1 vs System 2?
│   ├── How does this relate to cognitive biases?
│   │   └── Anchoring bias deep-dive
│   └── Real-world examples in decision making
├── Chapter 3: The Lazy Controller
│   └── Why do we avoid effortful thinking?
└── Comparison with Nassim Taleb's ideas
    ├── Black Swan connection
    └── Antifragility and heuristics

And here's the actual UI — tree sidebar on the left, conversation in the center, table of contents on the right:

Agentic, Not RAG

Most "chat with your documents" tools use RAG — chunk your content into embeddings, then retrieve what seems relevant. The problem: retrieval is approximate. The AI gets semantically similar chunks, not necessarily the right context.

Pi-tree takes an agentic approach: the AI has tools that give it precise, on-demand access to your content — more like grep than vector search. It can look up a specific chapter, fetch a paper's methodology section, or scan today's RSS feeds. The context is exact, structural, and requested when needed — not pre-computed and hoped for.

Each source type gets purpose-built tools:

• Books → process_book parses EPUB/MOBI/PDF, extracts chapter structure, builds a navigable outline
• News feeds → get_latest_rss, search_rss crawl your feeds, find trends across sources
• Papers → search_papers, get_paper_info query arXiv, fetch and contextualize research
• YouTube → get_youtube_transcript extracts transcripts for segment-level discussion

The AI's behavior is then shaped by skills — markdown instruction files that define how to read, not just what to retrieve.

Here's a news session — the AI scanned RSS feeds and produced a digest with trends:

The Plugin System

Everything is customizable at three levels:

1. Skills (Markdown files) — Change how the AI reads by editing a .md file. No code.

2. Session Profiles (YAML) — Map source types to different skills, extensions, and models:

name: book.reading
skills:
  - interactive-reading
extensions:
  - book
exclude_tools:
  - bash
  - edit

3. Full Plugins (TypeScript) — Build new source types with the plugin SDK:

import { definePiTreeExtension } from "@pi-tree/plugin-sdk";

export default definePiTreeExtension((pi, services) => {
  pi.registerTool({
    name: "my_custom_tool",
    description: "Does something useful",
    execute: async (args) => {
      const source = await services.sources.get(args.sourceId);
      // your logic here
    }
  });
});

There's also an MCP bridge — connect external MCP servers (web search, academic databases, translation APIs) by dropping a JSON config file. Same format as Claude Desktop.

Quick Start (Docker)

cp .env.example .env   # add your API key

docker run -d --name pi-tree \
  --env-file .env \
  -p 3847:3847 \
  -v ~/.local/share/pi-tree:/data \
  ghcr.io/shuowu/pi-tree:latest

Open http://localhost:3847. That's it.

Works with any OpenAI-compatible API — cloud providers (DeepSeek, Gemini, Claude, OpenAI) or fully offline with Ollama / LM Studio. Reading doesn't need frontier models — a 12B parameter model works well.

How It Compares

Who Is This For?

• Nonfiction readers — you're reading a dense chapter and AI summaries skip the part you actually don't understand. Pi-tree stays in that gap with you until you do.
• Researchers & students — you're outside your subfield and every paper assumes background you lack. Branch into what you don't know, then return to the argument.
• News followers — you read the headline but can't evaluate the claim. Turn feeds into conversations where you build context over time.
• Developers — you're in an unfamiliar domain. Build custom plugins to explore anything conversationally.

Links

• 🌳 GitHub: github.com/shuowu/pi-tree
• 📖 Docs: shuowu.github.io/pi-tree
• 🧩 Plugin guide: Building extensions
• 📸 Feature tour: Screenshots & demo

License: AGPL-3.0 — fully open source.

I'd love feedback on:

• Does the tree-structured approach resonate with how you read/research?
• What source types would you want beyond books, news, papers, and YouTube?
• If you self-host LLMs, what models are working well for reading tasks?

Built on the Pi SDK for tree-structured agent sessions.