README.md

---
title: Her · हेर
emoji: 🕵️
colorFrom: gray
colorTo: indigo
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
python_version: "3.10.13"
pinned: false
short_description: A detective for your Claude Code sessions
startup_duration_timeout: 1h
tags:
  - track:backyard
  - sponsor:nvidia
  - achievement:offgrid
  - achievement:offbrand
  - achievement:fieldnotes
---

<!-- ↑ Hugging Face Space config (Gradio SDK + ZeroGPU). The app entrypoint is app.py
     (Gradio Server mode); ZeroGPU hardware is set on the Space, not in this header.
     This README is the Space card — it describes the HOSTED, upload-based version.
     The fully-local product (`./her`, no upload) lives in the same repo; see the foot. -->

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

<h1 align="center">Her · हेर</h1>
<p align="center"><em>हेर — Marathi for “detective.”</em><br/>
A detective for your coding-agent sessions. Drop a Claude Code session export and Her
reads the whole trace — so you can see what actually happened, and what to do better
next time.</p>

---

## What this Space does

Upload your Claude Code session exports (`.jsonl`) and Her investigates them:

- **The journey.** Every query as a node, sized by cost, the heaviest glowing — with a
  plain-English **“what happened”** on top and the deterministic cost-shape below.
- **The dataflow.** The tool calls along each turn, with the **proven value-flow** path
  highlighted on focus (a value that reappeared *verbatim* from an earlier result) —
  proven (solid) vs. hypothesis (dotted), always kept separate.
- **Risky moves, surfaced.** Deploys, production & config changes, secrets — the actions
  worth a second look, each traceable to the turn it happened in.
- **What to do better.** Tips grounded in Anthropic’s and the community’s best practices.
  Her **suggests, never asserts** — and stays silent unless a named, fixable pattern fires.
- **Ask Her.** A chat bound to your trace. *“Why was this turn so expensive?”* → she
  answers from the trace, **cites the turns**, and opens the exact tool call.

## How to use it

**One or a few sessions — drag & drop.** Find a session file under
`~/.claude/projects/<encoded-folder>/<session-id>.jsonl`, then drop it onto the page
(or click **Upload .jsonl**). One file opens a **session view**; drop several to build a
**project view** across them.

**All your projects at once — the uploader script.** Grab `scripts/her_upload.py` from
this Space’s **Files** tab (or `hf download <owner>/<space> scripts/her_upload.py
--repo-type space --local-dir .`) and run it:

```bash
python scripts/her_upload.py
```

It **copies** the sessions you pick into a staging folder, **scrubs likely secrets**, and
**uploads** them — each step waits for your approval — then prints a link that opens your
**Projects view** here. A project groups many sessions under one working directory, with a
plain-English **changelog across sessions** and **Ask Her about the project**
(*“when did we add column X?”* → names the exact session).

## Your data & privacy

This is the hosted version, so your sessions **are** uploaded to analyze them — but they
stay yours and don’t stick around:

- **Private to your browser.** Each browser gets a random token (`crypto.randomUUID()`);
  your uploads land in a namespace keyed to it, so **you only ever see your own sessions**.
- **Temporary by default.** A background sweeper deletes anything older than **24 hours**;
  **“clear my data”** wipes your namespace immediately, and the tab-close does a best-effort
  clear too.
- **Scrubbed on the way in.** The uploader redacts likely secrets before anything leaves
  your machine (best-effort — review the staged copies if unsure).
- **No trace content ever leaves the Space.** The optional “share learnings” path (bare,
  scrubbed *tool names* only — never commands, paths, code, or JSONL) is **off** here.
- **Guardrails.** Up to **70 MB** per session file, **50 sessions** per project, **50
  projects** per browser — enough for real work, capped so no one can flood the box.

## What makes her trustworthy

- **Deterministic core, model for prose only.** Value-flow edges, token sums, loop &
  re-read detection, heavy-turn ranking, entity & binary extraction, risk scanning —
  **pure code, no model.** A model is used *only* to write the English and to *propose*
  (never assert) findings. The numbers don’t move when the model changes.
- **Proven vs. hypothesis is always separated.** A verbatim value reappearance is asserted;
  temporal proximity is a hypothesis you judge.
- **Cost alone is never advice.** “Expensive but clean” is a valid, important output.

## The model

Narration — the plain-English summaries, advice prose, and chat — runs **on the Space**
on **`nvidia/Nemotron-Mini-4B-Instruct`** via **ZeroGPU**. The first narration after a cold
start can take a few seconds while the GPU spins up. Swap the model with the
**`SPACE_MODEL_REPO`** Space variable — no code change. (Tool/binary identification here
is the **bundled offline registry** — top Homebrew/npm/PyPI tools shipped with the Space;
the live registry enricher is **off** here, see `HER_ENRICH` below.)

## How it’s built

ZeroGPU is Gradio-SDK-only and its GPU quota needs the HF iframe auth headers forwarded,
so the app runs in **Gradio Server mode** (`app.py`):

```
upload ─▶ /data/<your-namespace>/…  ─▶ engine (deterministic) ─▶ narrator (ZeroGPU) ─▶ UI
            (HF storage bucket)          pure code, no model      Nemotron, prose only
```

- **Deterministic engine endpoints** (`/api/health|sessions|upload|analyze|project|clear`)
  are plain FastAPI routes the React UI calls with `fetch`.
- **GPU narration** (`overview · advice · chat · project_chat · project_narrative`) are
  Gradio API endpoints the browser calls via `@gradio/client` (auth forwards for quota).
- **Storage** is an HF **bucket** mounted at `/data`, namespaced per browser; the React UI
  (`ui/dist`) is served from `/`. The deterministic engine is the same one the local
  product uses — only the transport and the model backend differ.

## Prefer to keep everything local?

The same repo ships a **fully-local** product: `./her` finds llama.cpp, downloads a local
GGUF model, and runs the whole thing on `127.0.0.1` with **no upload and no egress** —
it reads `~/.claude` directly. Use that if you’d rather nothing leave your machine.

## Self-host this Space

```bash
python scripts/deploy.py --space <owner>/<name> --create
```

Creates the Space + a private storage bucket, mounts the volume, uploads the app, and
requests ZeroGPU. **ZeroGPU needs a paid plan**: a personal **PRO** account for a
`<you>/<name>` Space, or a **Team/Enterprise** org for an `<org>/<name>` Space. See
`DEPLOY.md` for the full mechanics (bucket mount, factory reboot, env vars).

---

#backyard-ai
Blog: https://huggingface.co/blog/build-small-hackathon/her-blog
Social Media Post: https://www.linkedin.com/posts/ashishchalke_buildsmallhackathon-huggingface-gradio-ugcPost-7469368911361204224-IENm/?utm_source=share&utm_medium=member_ios&rcm=ACoAAAbqZTcBi7SuPZ07c89T6iyjc2PEJKICvE4
Demo: https://build-small-hackathon-her.hf.space/api/demo-video

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