Skip to content

docs: tighten README #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aicayzer merged 1 commit into from
May 12, 2026
Merged

docs: tighten README #51

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 19 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,67 +2,57 @@

A local Mac desktop app for browsing your SuperWhisper recording history. Reads your recordings from disk, never sends them anywhere. No telemetry. No accounts.

**Personal project, not affiliated with SuperWhisper.** Shared in case it’s useful to anyone else.
Built because I dictate constantly with [SuperWhisper](https://superwhisper.com) and wanted a way to look at my own usage data. **Personal project, not affiliated with SuperWhisper.** Shared in case it's useful to anyone else.

![App Screenshots](docs/screenshots/app-screenshots.png)

## Why this exists

I dictate constantly with [SuperWhisper](https://superwhisper.com). I've tried Wispr Flow, Handy, and a handful of other dictation tools — SuperWhisper consistently wins for me. It's fast, it's local-first, and the modes system is genuinely useful. I wanted to look at the data behind my own usage, and to ship something back to the community in return.

If you just want simple local transcription without the broader feature set, [Aiko](https://sindresorhus.com/aiko) by [Sindre Sorhus](https://sindresorhus.com) is excellent too.

## Install

### Download a packaged `.dmg`

Grab the latest `.dmg` from the [GitHub Releases page](https://github.com/aicayzer/superwhisper-analytics/releases/latest), open it, and drag `SuperWhisper Analytics.app` into `/Applications`. The release `.dmg` is signed with an Apple Developer ID and notarised, so macOS opens it without the Gatekeeper warning.
Grab the `.dmg` from the [latest release](https://github.com/aicayzer/superwhisper-analytics/releases/latest), open it, and drag `SuperWhisper Analytics.app` into `/Applications`. The release is signed with an Apple Developer ID and notarised, so macOS opens it without the Gatekeeper warning.

### Or build from source
### Build from source

```bash
pnpm install
pnpm build:mac
```

The build drops a `.dmg` into `dist/`. Open it and drag `SuperWhisper Analytics.app` into `/Applications`. A source build is unsigned, so macOS will flag it on first launch — either right-click the app in Finder and select **Open**, or run:
The build drops a `.dmg` into `dist/`. A source build is unsigned, so macOS flags it on first launch — right-click the app in Finder and select **Open**, or run:

```bash
xattr -d com.apple.quarantine "/Applications/SuperWhisper Analytics.app"
```

### First launch

The app asks for your SuperWhisper recordings folder. It tries to auto-detect the default location:
The app asks for your SuperWhisper recordings folder and tries to auto-detect the default location:

```
~/Library/Application Support/com.superduper.superwhisper/recordings
```

If yours lives elsewhere (custom install, external drive, etc.) point the picker at it. If neither default is found, the folder-picker modal will let you choose manually.

### macOS Files & Folders permission

The first time the app reads a path under `~/Library/Application Support`, macOS will show a Files-and-Folders permission dialog. Allow it. If you point the app at `~/Documents` or `~/Downloads`, you'll get a similar prompt for that location.
If yours lives elsewhere (custom install, external drive), point the picker at it. The first time the app reads anything under `~/Library/Application Support`, macOS shows a Files-and-Folders permission dialog — allow it.

## What it shows

- **Overview** — totals, KPIs, when-you-record heatmap, daily activity over a configurable range.
- **Usage** — by-hour-of-day clock, mode share, words-per-minute by mode.
- **Overview** — totals, KPIs, when-you-record heatmap, daily activity.
- **Usage** — by-hour clock, mode share, words-per-minute by mode.
- **Language** — top words, filler words, speaking pace, sentence-length distribution, vocabulary growth.
- **Transcripts** — paginated list of every recording with click-through to a detail view (audio playback, segment-clickable transcript, hover-to-highlight word frequency).
- **Transcripts** — every recording with click-through to a detail view (audio playback, segment-clickable transcript, hover-to-highlight word frequency).

All views are scoped to the date range pill in the navbar.
All views are scoped to the date-range pill in the navbar.

## Where it stores data

A single config file at:

```
~/Library/Application Support/me.cyzr.superwhisper-analytics/config.json
```

Single file holding your picked path, filler-phrase dictionary, and a couple of toggles. The recordings themselves stay in your SuperWhisper folder; this app reads them on launch and re-reads when you click **Reindex** in Settings.
Holds the recordings-folder path, your filler-phrase dictionary, and a few toggles. The recordings themselves stay in your SuperWhisper folder; the app reads them on launch and re-reads when you click **Reindex** in Settings.

No network calls except the **View on GitHub** link in Settings.
No network calls except the **View on GitHub** link.

## Develop

Expand All @@ -78,6 +68,10 @@ pnpm build:mac # full packaged .app + .dmg via electron-builder

See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

## Stack

Electron + Vite + React 19 + TypeScript (strict). Tailwind v4 + ShadCN/UI for the design system, Recharts for charts, Zustand for state, React Router (HashRouter) for routing. pnpm for package management. macOS only — no Windows/Linux build paths.

## Architecture

Briefly:
Expand All @@ -88,27 +82,10 @@ Briefly:
- **Aggregates** are pure functions over the parsed `Recording[]`.
- **`sw://` custom protocol** streams `output.wav` files to the renderer's `<audio>` element — the renderer never touches `file://` directly.

## Future Additions

- [ ] **Group transcripts by session** — collapse the Transcripts list into sessions defined by ≥30 minutes of silence either side. Sessions are named by their time range and expand to reveal the underlying transcripts.
- [ ] **Custom Variables** — bring more numbers under user control via Settings and a shared constants module.
- [ ] **Tests**
- [ ] Unit tests for shared aggregates (pure functions, fixture-driven)
- [ ] Unit tests for the scanner (fixture `meta.json` files, derived metric verification)
- [ ] Integration tests for IPC + dataStore hydration
- [ ] Playwright smoke test (app boots, all screens render without console errors)
- [ ] **Explore tab** — word / phrase usage exploration with full-text transcript search.
- [ ] **Period comparison view** — compare two date ranges side-by-side.
- [ ] **Non-SuperWhisper data adapter** — a skill or CLI that points at arbitrary transcript data and converts it into a SuperWhisper-compatible folder structure for this app to read.

## Acknowledgements

Thanks to the team behind [SuperWhisper](https://superwhisper.com) for building the app this one is built around. The data model, the modes system, and the clean on-disk format are what made this side project possible.

## Intellectual property and contact

This project doesn't intend to infringe upon SuperWhisper's intellectual property. If anyone at SuperWhisper has concerns, please email **hello@cyzr.me** — I'm happy to do whatever you ask.

## License

[MIT](LICENSE).
[MIT](LICENSE). This project doesn't intend to infringe upon SuperWhisper's intellectual property — if anyone at SuperWhisper has concerns, email **hello@cyzr.me** and I'll do whatever you ask.
Loading