meeting-helper 0.1.4

AI meeting assistant for macOS — auto-record, live transcription, Claude-powered answers

Meeting Helper

AI meeting assistant for macOS. Automatically detects when a meeting starts, records and transcribes in real-time, and lets you ask Claude questions about what's being discussed — using your codebase and knowledge base as context.

Features

• Auto-detection — starts recording automatically when any app activates your microphone (Zoom, Meet, Teams, etc.)
• Real-time transcription — local Whisper (free, no API key needed) or Deepgram Nova-3 streaming
• Invisible overlay — native macOS window hidden from screen share via NSWindow.setSharingType_(0)
• Ask Claude — hotkey or type a question during the meeting; Claude answers using the transcript + your repos + knowledge docs
• Per-meeting context — select which repos and knowledge folders to load per meeting, so Claude only gets relevant context
• Post-meeting — full transcription + structured summary saved alongside the MP3 recording

Requirements

• macOS 13+ (Ventura or later)
• Python 3.11+
• Microphone + Screen Recording + Accessibility permissions (prompted on first run)

---

Installation

Option A — pipx (recommended)

# Install pipx if you don't have it
brew install pipx && pipx ensurepath

# Install meeting-helper
pipx install meeting-helper

Option B — from source

git clone <repo-url> meeting-helper
cd meeting-helper
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

---

First Run Setup

1. Download the Whisper model

Whisper is used for local transcription (no API key needed). The model needs to be downloaded once before your first meeting:

python3 -c "from faster_whisper import WhisperModel; WhisperModel('tiny', device='cpu', compute_type='int8')"

This downloads ~75MB to ~/.cache/huggingface/. It only happens once.

Optional — better accuracy: Use the small model (~244MB) instead of tiny:

python3 -c "from faster_whisper import WhisperModel; WhisperModel('small', device='cpu', compute_type='int8')"

Then in meeting-helper setup, set the Whisper model to small.

2. Run the setup wizard

meeting-helper setup

You'll be prompted for:

1. Anthropic API key — get one at console.anthropic.com/settings/keys
2. Deepgram API key (optional) — get one at console.deepgram.com for lower-latency streaming transcription. Leave blank to use local Whisper.
3. Recordings directory — where to save MP3s and transcripts (default: ~/meetings)
4. Repos (optional) — paths to your code repos for Claude context
5. Knowledge folder (optional) — a folder of .md/.txt files organized by topic

3. Grant macOS permissions

On first run, macOS will prompt for:

• Microphone — to capture your voice
• Screen Recording — to capture system audio (meeting participants' voices)
• Accessibility — for global hotkeys (2×Cmd, 2×ESC)

After granting each permission, run meeting-helper start again if it stops.

---

Usage

meeting-helper start    # start the background daemon
meeting-helper gui      # open the main window
meeting-helper stop     # stop the daemon
meeting-helper status   # show daemon and meeting status
meeting-helper logs     # tail the daemon log
meeting-helper version  # check for updates

Once the daemon is running:

1. Start a Zoom/Meet/Teams call → recording starts automatically
2. Speak → transcript appears in the overlay and GUI dashboard
3. Ask Claude → press 2×Cmd (hotkey) or type in the "Ask Claude" box in the GUI
4. End the call → recording stops, MP3 + live transcript saved

Hotkeys

Combo	Action
2× Cmd	Trigger Claude query (uses last 5 transcript sentences)
2× ESC	Toggle overlay show/hide
ESC + → / ESC + ←	Scroll response down/up
ESC + ] / ESC + [	Navigate previous/next response
Cmd + ↑ / Cmd + ↓	Font size up/down in overlay

---

Per-Meeting Context

By default, no repos or knowledge docs are loaded into Claude's context — loading everything would dilute accuracy. Instead, use the Context Selector in the Dashboard during a meeting:

1. Chips show your configured repos — click to select
2. Tree shows your knowledge base folders — check what's relevant
3. Click Load Context — Claude now has access to only what you selected
4. Ask questions — Claude answers using that specific context

---

Post-Meeting

Open the Recordings screen in the GUI to:

• Play back the MP3
• Run full transcription (faster-whisper, timestamped)
• Generate a structured summary with Claude (key points, decisions, action items)

---

Configuration

Config is saved to ~/.config/meeting-helper/config.json. Run meeting-helper setup to reconfigure.

Whisper model quality vs speed

Model	Size	Speed	Accuracy
tiny	75MB	Fastest	Good for real-time
small	244MB	Fast	Better accuracy
base	142MB	Medium	Balanced

Default is tiny for real-time transcription. Post-meeting transcription always uses small for better quality.

---

Check for Updates

meeting-helper version

Checks PyPI and upgrades automatically via pipx if a newer version is available.

---

Troubleshooting

Daemon not detecting meetings

• Make sure Screen Recording permission is granted in System Settings → Privacy & Security
• Try meeting-helper logs to see what's happening

No transcription appearing

• If using Deepgram: check your API key with meeting-helper status
• If using local Whisper: ensure the model was downloaded (see First Run Setup above)
• Check meeting-helper logs for errors

Overlay not visible

• Press 2×ESC to show/hide
• The overlay is intentionally invisible to screen share — check your physical display, not a recording

Permission denied errors

• Go to System Settings → Privacy & Security → Microphone / Screen Recording / Accessibility
• Remove and re-add the terminal app or meeting-helper entry