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

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:

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:

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:

process_book

parses EPUB/MOBI/PDF, extracts chapter structure, builds a navigable outlineget_latest_rss

, search_rss

crawl your feeds, find trends across sourcessearch_papers

, get_paper_info

query arXiv, fetch and contextualize researchget_youtube_transcript

extracts transcripts for segment-level discussionThe 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:

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.

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.

License: AGPL-3.0 — fully open source.

I'd love feedback on:

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