QUICKSTART.md

Her · हेर — Quickstart

हेर (Marathi for detective) reads your Claude Code session history and shows you what happened, why every tool fired, what it cost, and what to do next time — 100% on your machine. Nothing about your code or traces ever leaves your computer.

Run it

tar -xzf her-trace.tar.gz
cd her-trace
./her

That's it. The first run will:

1. find (or brew install) llama.cpp,
2. download the local AI model Qwen3.5-9B (~6 GB, one time, resumable),
3. start everything and open http://127.0.0.1:8765 in your browser.

First start takes a few minutes (mostly the model download). After that it's instant. Press Ctrl-C in the terminal to stop.

What you'll see

A welcome screen — click “Browse your sessions” and pick any of your own ~/.claude sessions. Her analyzes it live and gives you:

• Session graph — your queries as a journey, sized by cost, with a plain-English “what happened.”
• Per-turn view — the tool calls, with the proven cause→effect path highlighted.
• Ask Her — chat with your trace: “why was this so expensive?” She answers, cites the exact turns, and opens them. She suggests, never asserts.
• Project view — many sessions at once: a changelog across them, and “which session did X happen in?”
• Entities — every skill, sub-agent, and MCP server you used, traced back to where.

Requirements

• macOS (Apple Silicon recommended).
• python3 and curl — already on your Mac.
• Homebrew — used once to install llama.cpp (https://brew.sh).
• ~7 GB free disk for the model. No Node needed (the app is prebuilt).

Privacy

Her is local-first by design. The AI model runs on your machine (127.0.0.1); the server refuses any non-local connection for model calls. The only thing that ever goes out is the one-time model download from Hugging Face. Your sessions stay yours.

Troubleshooting

• “llama.cpp not found” → brew install llama.cpp, then ./her again.
• Model download interrupted → just re-run ./her; it resumes.
• Port in use → HER_PORT=8780 ./her (and/or HER_LLAMA_PORT=12790).
• Chat says “MODEL OFF” → the model is still loading; give it a minute and retry.

---

_{हेर — she watches the work, not you.}