{"id":50742712,"url":"https://github.com/shuowu/pi-tree","last_synced_at":"2026-06-10T18:01:48.585Z","repository":{"id":363189696,"uuid":"1252906866","full_name":"shuowu/pi-tree","owner":"shuowu","description":"AI-assisted book reading with tree-structured conversations. Local-first, bring your own LLM.","archived":false,"fork":false,"pushed_at":"2026-06-09T01:19:30.000Z","size":1303,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-09T03:14:22.258Z","etag":null,"topics":["ai","ai-reading","book-reader","docker","ebook","epub","hono","llm","local-first","ollama","pi","pi-agent","pi-books","pi-extension","pi-sdk","react","reading-companion","self-hosted","tree-structure","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuowu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-29T01:46:35.000Z","updated_at":"2026-06-09T01:19:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shuowu/pi-tree","commit_stats":null,"previous_names":["shuowu/pi-books","shuowu/pi-tree"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/shuowu/pi-tree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuowu%2Fpi-tree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuowu%2Fpi-tree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuowu%2Fpi-tree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuowu%2Fpi-tree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuowu","download_url":"https://codeload.github.com/shuowu/pi-tree/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuowu%2Fpi-tree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34163252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-reading","book-reader","docker","ebook","epub","hono","llm","local-first","ollama","pi","pi-agent","pi-books","pi-extension","pi-sdk","react","reading-companion","self-hosted","tree-structure","typescript"],"created_at":"2026-06-10T18:01:47.866Z","updated_at":"2026-06-10T18:01:48.570Z","avatar_url":"https://github.com/shuowu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-tree\n\n**Turn any book into a conversation you can explore like a tree.**\n\nYou load your own books. An AI reads them *with* you — not as a flat Q\u0026A, but as a branching conversation that captures how you actually think about the material. Go deep on a concept, branch into a tangent, zoom back out. Your reading path is a navigable tree, not a disposable chat log.\n\n\u003e **Local-first, bring your own key.** Runs entirely on your machine. No cloud account, no subscription. Works with cloud APIs (DeepSeek, Gemini, Claude) or fully offline with [Ollama](https://ollama.com) / local models.\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"docs/images/library.png\" alt=\"Pi-books library view\" height=\"320\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003eBrowse your library — upload EPUBs, MOBIs, or PDFs\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"docs/images/reading-session.png\" alt=\"Pi-books reading session\" height=\"320\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003eBranching conversation with topic tree navigation\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## The Problem\n\nMost AI tools treat books the same way they treat any prompt: paste text in, get a summary out, conversation gone. There's no structure, no persistence, no sense of *journey* through the material.\n\nReading a non-fiction book isn't linear. You branch — *\"wait, how does this connect to X?\"* — then come back. You re-read a section with new context. You accumulate a personal vocabulary of terms and ideas. Flat chat threads can't capture any of this.\n\n**Pi-books fixes this.** Each book gets a tree-structured conversation where:\n\n- **Branches happen on semantic shifts** — go deeper, switch chapters, follow a tangent — each gets its own branch with full context preserved\n- **You can zoom in and out** — dive deep on a concept, then pull back with a summary without losing your place\n- **Every user gets their own tree** — multiple people can read the same book independently, each with their own conversation, glossary, and reading history\n- **The conversation IS the reading** — no separate \"reader\" and \"chat.\" The AI surfaces book content as quotes within the conversation\n- **Everything stays local** — your books, sessions, questions, and intellectual journey never leave your machine\n\n## Who Is This For\n\n- **Non-fiction readers** who want more than highlights and summaries — you want to *think through* a book\n- **Families and book clubs** — everyone gets their own conversation tree for the same book\n- **Privacy-conscious readers** who don't want their reading habits on someone else's server\n- **Self-hosters and tinkerers** who want full control over their tools\n\n## Getting Started\n\n### Prerequisites\n\n[Node.js](https://nodejs.org/) 22+, npm.\n\n### Local setup (no Docker)\n\n```bash\ncp .env.example .env   # edit with your API key and provider\nnpm install\nnpm run dev\n```\n\nDev server runs on `:3947`, client on `:5947`. Open http://localhost:5947.\n\n### Docker\n\nPre-built images are published to GitHub Container Registry on every release (linux/amd64 + linux/arm64):\n\n```bash\ndocker pull ghcr.io/shuowu/pi-tree:latest\n```\n\n**Quick start with the pre-built image:**\n\n```bash\ncp .env.example .env   # edit with your API key and paths\n\ndocker run -d --name pi-tree \\\n  --env-file .env \\\n  -p 3847:3847 \\\n  -v /path/to/your/books:/library:ro \\\n  -v pi-tree-data:/data \\\n  ghcr.io/shuowu/pi-tree:latest\n```\n\n**Or build from source:**\n\n```bash\ncp .env.example .env   # edit with your API key and ABSOLUTE paths\ndocker compose up --build\n```\n\nOpen http://localhost:3847 (serves both frontend and API).\n\n*Full env vars, volumes, custom skills → [docs/SELF-HOSTING.md](docs/SELF-HOSTING.md)*\n\n## Models\n\nPi-books doesn't need frontier-class models — book reading is more about context and conversation than raw reasoning. Smaller, faster models work well and keep costs low (or free with local inference).\n\n**Cloud APIs** (cheapest options that work well):\n\n| Provider | Model | Notes |\n|----------|-------|-------|\n| DeepSeek | `deepseek-v4-flash` | Very cheap, strong reading comprehension |\n| Google | `gemini-2.5-flash` | Fast, large context window |\n| Anthropic | `claude-haiku-4-20250514` | Fast, great quality-to-cost ratio |\n| Zhipu | `glm-5-turbo` | Good Chinese + English bilingual support |\n\n**Local models** — completely offline, no API costs. Use [Ollama](https://ollama.com/download) or [LM Studio](https://lmstudio.ai/) to run models locally. Gemma 4 (12B, 256K context) and Qwen 3.6 are good starting points — explore what works for your hardware and reading language.\n\nPoint pi-tree at your local server in `.env`:\n\n```bash\nPI_PROVIDER=openai                              # Ollama/LM Studio expose an OpenAI-compatible API\nPI_API_KEY=not-needed\nPI_BASE_URL=http://localhost:11434/v1            # Ollama default (LM Studio: http://localhost:1234/v1)\nPI_MODEL=gemma4:12b\n```\n\n**Multiple providers** — for advanced setups (e.g., Ollama for offline + DeepSeek for cloud), use Pi's native [`models.json`](https://pi.dev/docs/latest/models) config at `~/.pi/agent/models.json`. Env vars and `models.json` merge automatically — you can use both.\n\n\u003e [!TIP]\n\u003e You can also change models at runtime through the Settings UI — no restart needed.\n\n## Book Content\n\nPi-books is a **reading tool** — no book content is included in this repository.\n\nYou can add books in two ways:\n1. **Upload** via the Library UI (supports EPUB, MOBI, PDF)\n2. **Local folder** — set `LIBRARY_PATH` in `.env` to point at your book collection\n\n\u003e [!IMPORTANT]\n\u003e Users are responsible for ensuring they have the right to use any content loaded into pi-tree. This project does not distribute, host, or provide access to any copyrighted material.\n\n## How It Works\n\nBuilt on the [Pi SDK](https://pi.dev/docs/latest/sdk) — a minimalist AI agent with tree-structured conversations. The same `extension` package powers both the GUI and the [Pi terminal](https://pi.dev).\n\n```\npackages/\n  shared/      — TypeScript types shared between client and server\n  extension/   — Pi Package: skills, ebook parsers, Pi extensions (publishable)\n  server/      — Hono API server wrapping Pi SDK + tree manager\n  client/      — React + Vite frontend\n```\n\nKey architectural choices:\n- **Server is thin** — receives a message, passes it to a Pi SDK session with book context, streams the response back via SSE\n- **Skills shape behavior** — 11 built-in reading skills (markdown instruction files) control how the AI reads. Change a SKILL.md, change the behavior — no code changes needed\n- **Data separation** — Pi SDK owns conversation content (JSONL files); pi-tree owns metadata (SQLite: users, sessions, config, glossary)\n\n*Architecture deep dive → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)*\n\n## Extensions\n\nPi-books supports custom **skills** and **extensions**. Since it's built on [Pi](https://pi.dev), any Pi-compatible extension works here. One worth adding:\n\n```bash\npi install npm:pi-web-search    # gives the AI web search during reading sessions\n```\n\nThis lets the AI look up references, author background, or related concepts while you read — without leaving the conversation.\n\n\u003e [!NOTE]\n\u003e Extension documentation is a work in progress. See [docs/SELF-HOSTING.md](docs/SELF-HOSTING.md) for the current skill and extension format.\n\n## Design Philosophy\n\nMore on why pi-tree exists and the design decisions behind it → [docs/VISION.md](docs/VISION.md)\n\nThe short version: general-purpose AI chatbots can summarize a book, but they do it in a flat, sessionless way. Pi-books is a **reading companion** — every design decision (tree structure, branching conversations, zoom controls, per-book glossaries) serves that single purpose.\n\n## License\n\nThis project is licensed under the [GNU Affero General Public License v3.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuowu%2Fpi-tree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuowu%2Fpi-tree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuowu%2Fpi-tree/lists"}