Understand

Type any concept. Get an explanation built for memory and comprehension — visual, drillable, opinionated about clarity.

Backed by your local claude CLI (Claude Max subscription, no API key, no per-token billing). Single Rust binary. Designed to be slick out of the box.

What it does

You enter a concept — BM25, the Treaty of Westphalia, vector embeddings, photosynthesis, Goodhart's Law — and get back an explanation engineered around how human memory actually works.

Every result includes:

• Hook — a curiosity-gap question to prime your brain (generation effect)
• Visual — Claude generates an inline SVG diagram of the concept (dual coding → ~2× retention)
• TL;DR — one-sentence anyone-gets-it summary
• Memory hook — short mnemonic phrase
• Why it matters — the so-what
• How it works — plain-language prose with clickable underlined terms that drill into deeper explanations inline
• Analogy — concrete mapping when one fits
• Examples — specific scenarios, never generic
• Misconceptions — common myths surfaced and refuted (refutation texts retain better)
• Sources — what Claude grounded the answer in
• Explore next — related concepts you can jump to with one click
• Difficulty pill + Markdown export + History sidebar

Click any underlined term and the drill-down opens inline beneath it. Drill into drill-downs. As deep as you want.

Why it's different

Most "explain anything" tools dump a wall of paragraphs. This one composes the result around evidence-backed cognitive techniques:

Technique	Where it shows up
Dual coding	SVG visual paired with prose
Generation effect	Curiosity-gap hook before content
Concretisation	Specific examples beat abstract definitions
Refutation	Misconceptions section explicitly contrasts wrong vs right
Elaborative encoding	Mnemonic memory hook
Chunking	Short paragraphs, never wall-of-text
Schema activation	Personalised analogies grounded in your vault/notes
Spaced revisit	History sidebar lets you re-open any past concept

It also runs on your claude CLI, so it can Read/Grep files in your home directory — analogies are tuned to what you already know, not generic textbook framings.

Run

Requirements: macOS or Linux, Rust, and the Claude CLI logged in (claude /login).

git clone https://github.com/JoshuaBearup/understand
cd understand
cargo run --release
# open http://127.0.0.1:8787

Configure

Env var	Default	Purpose
PORT	8787	HTTP listen port
RUST_LOG	understand=debug,tower_http=info	Tracing filter

Tool allowlist for the spawned claude is read-only: Read,Grep,Glob,WebSearch,WebFetch. No Bash, no Edit, no Write — the explainer cannot mutate your filesystem. Hardcoded in src/claude/runner.rs if you want to widen or narrow it.

The spawned session also gets --add-dir ~/Developer/Claude so Claude can ground analogies in your local notes/vault. Edit that constant for your own setup.

Tailscale (optional)

Reach it from any device on your tailnet over HTTPS:

tailscale serve --bg --https=443 http://localhost:8787
# https://<your-machine>.<your-tailnet>.ts.net/

The tailnet is the perimeter — there is no extra auth layer on this app.

Keyboard

Key	Action
/ or Cmd+K	Focus the concept input
Esc	Close all open drill-downs

Architecture

┌─────────────┐   POST /explain           ┌─────────────────────────┐
│  Browser    │  ───────────────────────► │  Axum (Rust)            │
│  (htmx)     │                           │  ─ cache check (SQLite) │
│             │  ◄── streamed HTML ─── ── │  ─ spawn `claude -p`    │
└─────────────┘                           │  ─ parse + sanitise     │
                                          │  ─ render Askama tmpl   │
                                          └────────────┬────────────┘
                                                       │
                                          ┌────────────▼────────────┐
                                          │  claude CLI subprocess  │
                                          │  Max-subscription auth  │
                                          │  Tools: Read/Grep/Glob  │
                                          │         WebSearch/Fetch │
                                          └─────────────────────────┘

Layer	Purpose
src/claude/runner.rs	Spawns claude -p --output-format json, parses envelope, returns typed result
src/claude/prompts.rs	System prompts for explain + drill (visualisation rules, clarity rules, output schema)
src/claude/schema.rs	Typed ExplainResult, DrillResult, Block, Visual, Misconception
src/cache/mod.rs	SQLite cache, key = sha256(kind:normalised:prompt_version)
src/sanitise.rs	Strips <script>, on*= handlers, javascript: URLs from Claude-generated visual HTML
src/routes/explain.rs	POST /explain — main entry
src/routes/drill.rs	GET /drill?id=&term=&parent= — inline drill expansion
src/routes/history.rs	GET /history — recent cached concepts
src/routes/random.rs	GET /random — random seed concept
src/routes/export.rs	GET /export?concept= — markdown export

Bump PROMPT_VERSION in src/claude/schema.rs to invalidate the entire cache (after editing prompts).

Roadmap

• Streaming render (sections appear as Claude emits them)
• Vault FTS5 MCP server for faster context lookup
• Spaced-repetition reminder ("you learned X 14 days ago — quick check?")
• Concept relationship graph view of explored concepts
• Embed mode for blogging / docs
• Native desktop wrapper (Tauri)

License

MIT.