happenin 0.2.0 → 0.4.0

package/README.md

@@ -5,10 +5,20 @@
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v3.0%20adopted-ff69b4.svg)](docs/CODE_OF_CONDUCT.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
 
-A macOS CLI that records Cursor and Claude Code agent events to a local SQLite database and serves a live browser dashboard.
+A CLI that records Cursor and Claude Code agent events to a local SQLite database and serves a live browser dashboard.
 
 ![happenin dashboard](docs/dashboard.gif)
 
+## Try it
+
+```bash
+npx -y happenin install   # add record hooks to Cursor and Claude Code
+npx -y happenin import    # import existing transcripts
+npx -y happenin dashboard # open the live dashboard
+```
+
+No global install needed: hooks installed this way run through `npx`. For a permanent setup, use the [global install](#install).
+
 ## Why
 
 Cursor and Claude Code can emit local hooks for each session, tool use, prompt, file edit, and lifecycle event. `happenin` adds `record` hooks to those agents, writes the payloads to a local SQLite database, and serves a live browser dashboard. Data never leaves your machine.
@@ -19,7 +29,7 @@ Cursor and Claude Code can emit local hooks for each session, tool use, prompt,
 
 ## Requirements
 
-- macOS
+- macOS, Linux, or Windows
 - Node.js `>= 22.13.0` (uses the built-in `node:sqlite` module, available since Node 22.13)
 - Zero runtime dependencies
 - The dashboard loads htmx and htmx-ext-sse from a CDN
@@ -58,7 +68,7 @@ The dashboard opens at `http://localhost:8765`. New events appear automatically.
 
 ### `happenin install [--cursor] [--claude]`
 
-Backs up and appends `happenin record` hooks to `~/.cursor/hooks.json` and `~/.claude/settings.json`. Backups are written to `~/.happenin/backups/`.
+Backs up and appends `happenin record` hooks to `~/.cursor/hooks.json` and `~/.claude/settings.json`. Backups are written to `~/.happenin/backups/`. Re-running `install` replaces the previous `happenin` hooks instead of duplicating them, and hooks installed through `npx -y happenin install` are written as `npx -y happenin` commands so they keep working without a global install.
 
 ```bash
 happenin install --cursor
@@ -79,15 +89,21 @@ echo '{"hook_event_name":"sessionStart","sessionId":"abc123"}' | happenin record
 echo '{"sessionId":"abc123"}' | happenin record claude SessionStart
 ```
 
-### `happenin import`
+### `happenin import [--force]`
 
 Imports existing transcripts:
 
-- Claude Code JSONL from `~/.claude/projects/<project>/<session>.jsonl`.
+- Claude Code JSONL from `~/.claude/projects/<project>/<session>.jsonl`. Each `tool_use` block in an
+  assistant message becomes its own event with `tool_name` set (and `file_path` for file-editing
+  tools, `skill_name` for `Skill` calls), so tool usage, skills used, and files touched are
+  queryable per session and show up on the dashboard.
 - Cursor `prompt_history.json` and `meta.json` from `~/.cursor/chats/<hash>/<session>/`.
 
 `store.db` is skipped because it is encrypted.
 
+Files are only re-parsed when their modification time changes; pass `--force` to clear that
+tracking and re-import everything from scratch (useful after upgrading `happenin`).
+
 ### `happenin query [options]`
 
 Query events from the local database and print them as JSON, JSONL, or a summary.
@@ -120,6 +136,30 @@ Starts a local HTTP server and opens the dashboard.
 - `--no-open` — do not open the browser.
 - `--silent` — alias for `--no-open`; used automatically by `npm start`.
 
+The main screen shows total sessions/events, average duration, and success rate for the selected
+date range, plus charts for the top 10 tools, top 10 skills, and top 10 markdown files touched.
+Clicking a tool, skill, or file jumps to a list of every session that used it. The markdown files
+chart can be scoped to one directory with the "md files directory" filter (the common path prefix
+is stripped from the dropdown labels, and paths under `/private` are excluded).
+
+The persistent filter bar also has multi-select "directories", "skills", and "integrations (MCP)"
+controls. Each lets you pick several values at once — matching sessions with _any_ of the selected
+values in that category (OR) — and the categories combine with every other filter, including each
+other, with AND (e.g. directory X or Y, AND skill A or B). The "integrations (MCP)" list is derived
+from the data itself: it parses the `mcp__<server>__<tool>` naming convention on recorded tool
+calls and lists every distinct MCP server actually seen, with no hardcoded set of servers.
+
+A context breakdown widget splits recorded payload size (and, for imported Claude sessions, token
+usage) into four buckets: MCP server calls, markdown file reads, bloatware (skill loads and
+lifecycle/hook noise), and actual value (real tool calls and conversation turns). It appears on the
+main dashboard for the current filter/date range, and again inside a session's detail view scoped
+to that session. This is a heuristic, not an exact accounting — Claude Code does not log its system
+prompt or tool schemas to the transcript, so there is no ground truth to bucket against.
+
+The "Recent Sessions" bar above the charts is collapsed by default — clicking it replaces the
+metrics/charts with the full session list; clicking it again (or picking a session) returns to the
+previous view.
+
 ```bash
 happenin dashboard --port 9000 --silent
 ```

package/assets/help.md

@@ -1,12 +1,15 @@
 # happenin
 
-A macOS CLI that records Cursor and Claude Code agent events to a local SQLite database and serves a live browser dashboard.
+A CLI that records Cursor and Claude Code agent events to a local SQLite database and serves a live browser dashboard.
 
 ## Commands
 
 ### `happenin install [--cursor] [--claude]`
 
 Backs up and appends `happenin record` hooks to your Cursor and Claude Code configuration files.
+Re-running install replaces previous happenin hooks instead of duplicating them. When happenin
+runs through npx, hooks are written as `npx -y happenin` commands so they keep working without a
+global install.
 
 - `--cursor` — install Cursor hooks only.
 - `--claude` — install Claude Code hooks only.
@@ -22,15 +25,19 @@ The hook target. Reads a JSON payload from stdin, writes it to `~/.happenin/happ
 
 This command is normally called by the agent hooks, not directly.
 
-### `happenin import`
+### `happenin import [--force]`
 
 Imports existing transcripts:
 
-- Claude Code JSONL from `~/.claude/projects/<project>/<session>.jsonl`.
+- Claude Code JSONL from `~/.claude/projects/<project>/<session>.jsonl`. Each `tool_use` block in an
+  assistant message becomes its own event with `tool_name` set (and `file_path` for file-editing
+  tools, `skill_name` for `Skill` calls).
 - Cursor `prompt_history.json` and `meta.json` from `~/.cursor/chats/<hash>/<session>/`.
 
 `store.db` is skipped because it is encrypted.
 
+- `--force` — clear import tracking and re-import every discovered file from scratch.
+
 ### `happenin query [options]`
 
 Query events from the local database and print them as JSON, JSONL, or a summary.