Skip to main content
Glama

Rabbithole

An infinite canvas for learning. Open a document, ask at any point, and follow each answer into a new document.

Rabbithole branching canvas demo

Open the web app · Explore the offline architecture tour

Rabbithole has two hosts and one canvas:

  • The static web app uses your chosen model endpoint or the coding-agent subscription already signed in on your machine.

  • The MCP server lets Claude Code, Codex, and other MCP clients answer while the canvas, storage, and local transport stay on your machine.

No account, telemetry, or hosted document store. Web documents live in your browser. MCP documents live under ~/.rabbithole/ unless RABBITHOLE_DIR overrides it.

Web

Visit rabbithole.ing, then paste a question or URL, drop Markdown or PDF, or import a Rabbithole file.

The web app supports OpenRouter, local and custom OpenAI-compatible endpoints, and the optional subscription bridge:

npx @shlokkhemani/rabbithole bridge

The bridge prints a private pairing link and connects the page to an installed, signed-in Claude Code or Codex CLI. It binds only to loopback.

Related MCP server: pdf-context

MCP quick start

Requires Node 18+ and a browser.

Claude Code:

claude mcp add rabbithole -- npx -y github:shlokkhemani/rabbithole

Codex:

codex mcp add rabbithole -- npx -y github:shlokkhemani/rabbithole

Then start a fresh agent session and say:

Open this document in Rabbithole.

The tool call stays pending while the agent listens for canvas asks. If a client enforces a short MCP tool timeout, raise that client's timeout; saved asks survive disconnects and resume.

Develop

git clone https://github.com/shlokkhemani/rabbithole.git
cd rabbithole
npm install
npm run build
npm test

Useful references:

The canvas and frozen snapshots remain self-contained HTML. Package tarballs include the browser bundles built during packaging, so registry installs need no consumer-side build.

License

MIT. See LICENSE.

Available Tools

4 tools
answer_branchA

Answer one pending branch request from an open Rabbithole. Called after open_rabbithole or answer_branch returns status='branch_request'. Write a focused, well-formatted markdown answer to the human's question about their selection - use selected_text, parent_node_title, and lineage for context (you already hold the documents you authored). If selected_text is empty, answer conversationally about the parent document as a whole. If the request has a 'lens', match that style.

Authoring vocabulary:

  • Base notation: GFM markdown, $...$/$$...$$ and (...)/[...] math, and highlighted language-tagged code fences.

  • If the answer is content fetched from a URL or repo, pass its document URL as base_url so relative images and links resolve.

  • If the answer uses a local image, pass assets: [{ name, file_path }] and reference it as alt; use this for screenshots, generated diagrams, and other non-web images.

  • Use ```show when a concept is spatial or structural: architecture, memory layout, relationships.

  • show dialect: HTML/CSS/inline-SVG only; no scripts. Scripts and unsafe attributes are stripped.

  • show craft: prefer HTML/CSS layout with flexbox/grid over absolute SVG coordinates.

  • Design visuals for about 380px card width; make them fluid and keep labels short.

  • Use theme tokens, never hardcoded colors, so visuals match light and dark themes: --fg, --fg-bold, --fg-dim, --fg-faint, --node-bg, --bar-bg, --border, --border-focus, --accent, --accent-contrast, --code-bg, --hl, --hl-strong, --warn, --font-ui, --font-doc, --font-mono.

  • Example show:

<style>.flow{display:grid;gap:8px}.box{border:1px solid var(--border);padding:8px;border-radius:6px}</style>
<div class='flow'><div class='box'>Parse</div><div class='box' style='background:var(--hl)'>Render</div></div>
  • Streaming choreography: send prose in 1-3 sentence chunks as usual.

  • Emit each visual fence contiguously, ideally in one chunk; readers see a placeholder until the fence closes.

  • Interleave prose -> visual -> prose when useful. Use a visual only when it genuinely carries the explanation.

Finish streaming by sending the remaining final chunk in a normal call with a short 'title'. Partial chunks concatenate verbatim: include your own spacing/newlines and never repeat text already sent. The final call blocks and returns the next event. If it returns status='keep_listening', immediately call open_rabbithole { hole_id }; if the host reports a tool timeout (e.g. timed out awaiting tools/call), do the same. Do not re-send content; asks are saved.

Inputs: content (required), request_id (required), session_id (required), title, +3 more.

ingest_pdfA

Extract a local PDF into Rabbithole image assets and per-page text. Produces 2x page render PNGs named page-001.png, page-002.png, etc. plus opportunistic embedded rasters named embed-p001-01.png when the PDF contains extractable images. The agent should compose markdown itself, using page renders as the dependable figure source and embedded rasters when they are cleaner, then call open_rabbithole with the returned ingest_id (or pass hole_id here to attach assets directly to an existing hole). For arXiv links, prefer fetching the HTML version and opening that markdown with base_url instead of ingesting the PDF.

Inputs: file_path (required), pages, hole_id, include_text.

list_rabbitholesA

List saved Rabbitholes (most recently updated first) so you can resume one by hole_id via open_rabbithole. Returns id, title, last-updated time, and node count for each.

Inputs: no named parameters.

open_rabbitholeA

Open a document on an infinite canvas so the human can read it and dive down rabbit holes. Start a NEW hole with { title, content } (or { title, file_path }), or RESUME a saved one with { hole_id } (use list_rabbitholes to find it). When opening content fetched from a URL or repo, pass the document's own URL as base_url so relative images and links resolve. For local images that are not on the web, pass assets and reference them as alt. For a PDF already processed with ingest_pdf, pass ingest_id when starting the new hole and reference the returned asset names as page. The canvas opens in the browser and this call BLOCKS until the human acts. It returns status='branch_request' when the human selects text and asks a question — answer it with answer_branch. A branch_request with EMPTY selected_text is a follow-up question about the parent document as a whole (a chat reply beneath it) — answer conversationally in that document's context. A branch_request may carry a 'lens' (explain | eli5 | example | deeper) — the question text spells out the style the human tapped; honor it. One marked saved=true was asked while no agent was listening — answer it like any other. On a resumed hole the first branch_request carries a 'rehydration' field with the whole tree (and any saved_asks); read it to reload your context. Long waits periodically return status='keep_listening' with hole_id; immediately call open_rabbithole { hole_id } to keep listening, and do not re-send content. If the host reports a tool timeout (e.g. timed out awaiting tools/call), also re-call open_rabbithole { hole_id }; nothing is lost and asks are saved. It returns status='session_closed' when the human clicks Done or closes the tab.

Inputs: title, assets, content, hole_id, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: opening/resuming rabbitholes, answering branch requests, ingesting PDFs, and listing saved ones. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow the `verb_noun` pattern (e.g., list_rabbitholes, open_rabbithole, answer_branch, ingest_pdf), providing a consistent and predictable interface.

    Tool Count5/5

    With 4 tools, the set is tightly scoped to the rabbithole interaction domain—opening, answering, ingesting, and listing. No tool feels redundant, and the number is appropriate for the focused purpose.

    Completeness4/5

    The tools cover core workflows well, but missing explicit update/delete functionality for rabbitholes. However, the blocking nature of open_rabbithole and the branch-answer loop cover most user interactions adequately.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local-first MCP server that ingests PDFs, extracts structure, and provides semantic search and sequential navigation tools for AI clients to query and learn from documents.
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local RAG over personal notes, PDFs, and documents, enabling plain-English querying and hybrid search with multi-hop context expansion.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for a self-hosted RAG system that enables AI tools to search and retrieve grounded answers from locally ingested documents via MCP tools, with local embeddings and no API key required.
      MIT