First-launch Setup Wizard

The first time you open Gistlist, the Setup Wizard walks you through seven steps. You can skip most of them and run with defaults; nothing here is permanent. Re-open Settings any time to change a choice.

1. Welcome

A short overview. No input.

2. Your name (optional)

Enter the name you want the AI to use when summarizing meetings for you. This value is substituted into the default summary.md prompt wherever {{user_name}} appears, so the AI knows who is being summarized for.

• First name is fine — the prompt uses it in places like “Treat the speaker labeled ‘Me’ as Jesse” and “Jesse: Send shortlist…”. Anything works (full name, nickname, role); only you see this.
• Optional — you can leave it blank and click Next. Empty falls back to a generic “the user” in the prompt.
• Editable later — change it in Settings → Other → Your name.

Privacy: when a prompt runs on Claude or OpenAI, your name is sent as part of the prompt to that provider. With Ollama it stays on your machine. Each prompt can specify its own model in frontmatter, so the relevant question is what model the prompt runs on, not just your default LLM provider.

3. Obsidian (optional)

Toggle whether you use Obsidian. If you do, pick a vault — Gistlist auto-detects vaults already on your machine.

If you pick a vault, the wizard uses a Gistlist folder inside that vault as the default meetings folder. You can change that on the next step. If you skip Obsidian, Gistlist still works; notes go into a normal folder on disk.

4. Where to store meetings

Pick a folder. The default is ~/Documents/Gistlist.

Pick an audio retention policy:

• Never (default) — keep the audio forever.
• 7 days — delete audio after a week.
• 30 days — delete audio after a month.
• Custom — pick any number of days.

Retention deletes the audio/ directory inside each meeting folder. Your notes, transcripts, and prompt outputs stay.

5. Providers and keys

Pick an LLM provider. Local Ollama is the default for new installs, so you can finish setup without a Claude or OpenAI key:

• Claude (cloud, fastest, costs API credits)
• OpenAI (cloud, costs API credits)
• Ollama (fully local, free, slower)

Pick a transcription provider:

• Parakeet (local, Apple Silicon only)
• OpenAI Whisper (cloud)

On Intel Macs the wizard hides Parakeet entirely — MLX (the engine Parakeet runs on) does not support x86_64. The wizard steers Intel users to OpenAI Whisper instead.

whisper.cpp is not offered in the current signed macOS build. If an older config already points at it, Settings keeps the value visible so you can switch away from it.

If you stay on Ollama, the wizard picks a local chat model sized to your machine’s RAM — qwen3.5:0.8b below 8 GB, qwen3.5:2b on 8-15 GB, qwen3.5:4b on 16-23 GB, and qwen3.5:9b on 24 GB or more. Heavier models (gemma4:e4b) are only suggested at the top tier so the app stays responsive on smaller machines. If you already have chat models installed, the picker prefers an installed chat model. Embedding-only tags such as nomic-embed-text are not offered as summary models.

Enter the API keys your choices need. Keys go into the macOS Keychain under the service name gistlist. Local-only setups don’t need any keys; add a Claude or OpenAI key only if you switch the LLM provider to one of those cloud services.

You can also opt into semantic search for Claude Desktop. Semantic search uses local Ollama embeddings (nomic-embed-text) even if your LLM provider is Claude or OpenAI.

See providers for a fuller comparison.

6. Permissions

A dedicated step for OS permissions. The wizard never opens an OS dialog without your click.

• Microphone — required to record. Click Grant microphone access; macOS shows the permission dialog. Once granted, the Next button enables. If you denied earlier and want to fix it in System Settings, use Open Settings then click Re-check microphone permission to refresh the wizard’s state.
• System audio (optional, macOS 14.2+) — captures other participants. Two-stage flow: click Test system audio to start the OS dialog, then click Verify once you’ve clicked Allow. The first probe’s result is intentionally discarded so you don’t see a stale “denied” badge while the dialog is still open. If you previously granted, the test passes immediately. Mic-only recording works without it.

7. Dependencies

The final step installs whatever your choices require — no Terminal, no Homebrew, no system Python. Everything lives under ~/Library/Application Support/Gistlist/bin/.

This step is a single chain-install loading screen. Missing items appear as a vertical checklist with size estimates; one Install all (~X MB) button at the bottom kicks off a sequential install of every missing dependency in dependency order. Already-installed items render as Ready and are skipped.

The dependency order is:

• ffmpeg and ffprobe for media import, conversion, and audio processing. Apple Silicon gets a native arm64 build from osxexperts.net (GPL, ad-hoc signed); Intel Macs get the LGPL static build from evermeet.cx. Both are SHA-256 verified. ~50 MB.
• Parakeet (if you picked Parakeet for transcription) — installs an app-managed Python runtime (CPython 3.12, Apple Silicon only) and builds the ~/.gistlist/parakeet-venv/ against it. About 1 GB total (runtime + venv + ~600 MB of model weights). First run downloads model weights lazily during the smoke test, which can take a few minutes.
• Ollama (if you picked Ollama for summaries OR turned on semantic search for Claude Desktop). ~130 MB. Runs as a bundled-spawned daemon.
• Embedding model nomic-embed-text (if you turned on semantic search). Pulled via Ollama. ~274 MB.
• Local LLM model (if you picked Ollama for summaries). Size depends on the model you selected (typically 2–9 GB).

While the chain is running, the active row shows inline progress (bytes / MB/s / ETA when the installer reports byte counts, percent otherwise). A collapsed Activity log below the checklist exposes the raw install stream.

If a step fails, the chain pauses on the failed row with an inline error message and a Retry button (in the row and the footer); the rest of the chain stays pending. Retry resumes from the failed row. Cancel triggers a graceful break — Parakeet aborts directly, others finish their current operation then stop. Use Resume install to pick back up.

You can re-run any of these from Settings later. To rebuild the Parakeet venv from scratch (e.g. recover from corruption), delete ~/.gistlist/parakeet-venv/ and re-run the install — the chain repopulates it on next click.

After the wizard

Gistlist writes its config to ~/.gistlist/config.yaml. It creates your meetings folder with Runs/, Dashboard.md, and Templates/notes-template.md. If you chose Obsidian and kept the default folder, those files live at <vault>/Gistlist/.

Prompt templates are separate from meeting notes. The Prompt Library lives under ~/.gistlist/prompts/.

Open Home and use Start recording to capture your first meeting, or use Prepare for later to create a draft workspace.

Re-running the wizard

If something’s broken — a microphone permission needs re-granting, ffmpeg got removed, you want to switch ASR providers — open Settings → Other → Setup and click Run setup again. The wizard relaunches with every step pre-filled from your existing config, so just clicking through doesn’t change anything. Adjust what you need, finish, or Cancel to back out without writing.