QUICKSTART.md

<p align="center"><img src="ui/public/her-logo.png" alt="Her · हेर" height="90" /></p>

# 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

```bash
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.

---
<p align="center"><sub>हेर — she watches the work, not you.</sub></p>