Getting Started

Getting Started

Five minutes from clone to your first longhand recall returning a real answer from your past sessions.

Requirements

• Python 3.10 or higher — check with python3 --version
• Claude Code installed and used at least once (Longhand reads from ~/.claude/projects/)
• macOS or Linux — Windows users should use WSL2
• ~100 MB of disk for the index (scales with your history; ChromaDB + SQLite together)

If you've never run Claude Code, there's nothing for Longhand to ingest. Come back after you've had a few sessions.

---

Install

pip install longhand

Confirm the CLI is on your PATH:

longhand --version

To upgrade later, run pip install -U longhand.

Developer install (from source)

If you want to hack on Longhand itself, clone the repo and use editable mode:

git clone https://github.com/Wynelson94/longhand.git
cd longhand
pip install -e .

pip install -e . installs in editable mode so you can pull updates with git pull without reinstalling.

---

Setup

One command wires up everything:

longhand setup

This does six things in order:

1. Ingest — discovers every JSONL file in ~/.claude/projects/ and parses every event (user messages, assistant text, tool calls, tool results, thinking blocks) into SQLite and ChromaDB
2. Analyze — runs the extractors (errors, file references, topics, git operations) and the per-session analysis (project inference, episode extraction, segment clustering, outcome classification)
3. Install SessionEnd hook — adds a line to ~/.claude/settings.json so every future Claude Code session auto-ingests when it closes
4. Install UserPromptSubmit hook — adds an optional hook that auto-injects relevant past context before Claude sees your next prompt
5. Register MCP server — makes the 16 recall tools available to Claude Code agents mid-session
6. Doctor — verifies all components wired correctly

First-time ingest on a large history (100+ sessions) can take a few minutes because ChromaDB has to generate embeddings for every event. Subsequent ingests are incremental and fast.

---

Your first recall

Ask it something in plain English:

longhand recall "that time we fixed the auth middleware"

You'll get back matched projects, relevant problem→fix episodes with diffs, conversation segments, and a prebuilt markdown narrative you can read top-to-bottom.

Try a fuzzy time reference:

longhand recall "the bug I was stuck on a couple weeks ago"

The time parser handles "last week," "a couple months ago," "in March," and similar fuzzy phrases — no exact dates required.

---

Use it from inside Claude Code

Once the MCP server is registered, Claude can call recall tools during a live session. Try asking:

"Do you remember the stripe webhook bug I fixed? Show me the diff."

Claude will call recall with your question, pull the episode, show you the fix, and continue the conversation with full context. No more re-explaining.

See the MCP Tools Reference for every tool Claude has access to.

---

What if something didn't work

Run the built-in diagnostic:

longhand doctor

It reports the status of the database, the hooks, the MCP registration, and the index. Most first-run issues show up there with a clear fix.

If doctor looks clean but something still isn't working, see the Troubleshooting page.

---

Common first-run gotchas

• "No sessions found" on first ingest — confirm Claude Code has actually written to ~/.claude/projects/. If you're a brand-new Claude Code user with zero completed sessions, Longhand has nothing to read.
• MCP tools not showing up in Claude — restart Claude Code after longhand setup so it picks up the new MCP config.
• Slow first recall — ChromaDB lazy-loads its embedding model on first query. First call takes several seconds, subsequent calls are ~126ms.
• Hook didn't fire — longhand doctor will tell you if the hook is installed. Check that ~/.claude/settings.json contains a SessionEnd entry.

---

Next steps

• MCP Tools Reference — learn what Claude can call
• CLI Reference — browse the 29 commands
• Codex — using Codex too? Capture its threads into the same archive and search both from either client
• Configuration — tune hook behavior and relevance thresholds