Tutorial
Your first analysis
In about ten minutes you'll go from a folder of recordings to a report you can click through. We'll use a sample so it works the first time, every time.
Everything here runs on your machine. Nothing is uploaded — the sample recordings never leave your laptop.
1. Get the sample folder
Download sample-interviews.zip and unzip it anywhere. Inside are three short recordings and their transcripts.
2. Point Bristlenose at the folder
Drop the folder onto the Bristlenose app, or from a terminal run:
bristlenose sample-interviews/
Bristlenose transcribes, finds quotes, and groups them into themes. The first run takes a few minutes — you'll see each step tick by.
3. Open the report
When it finishes, the report opens in your browser. You're looking at the Quotes page: every notable thing a participant said, grouped into sections.
4. Try one thing
Click the star on any quote. That's how you mark findings worth keeping — you'll use stars later to export just the quotes that matter.
Stuck on a step? Every page in Bristlenose has a ? for the in-app help, and this site has the full guides.
What you just did
You ran the whole pipeline, opened a report, and made your first finding. That's the loop — point at a folder, read the analysis, mark what matters.
How-to guide
Set up Claude
Connect Bristlenose to Claude so it can analyse your interviews.
Before you start: a Claude account with billing enabled — your API key is created at console.anthropic.com.
macOS
- Open Settings (⌘,) and choose AI Providers.
- Select Claude and paste a key from
console.anthropic.com.
- Bristlenose checks the key and saves it in your macOS Keychain. Done.
CLI
- Get a key from
console.anthropic.com.
- Run
bristlenose configure claude and paste the key when prompted.
- It validates the key and stores it in your system credential store. Done.
Open or close either section — they're independent, and your choice is remembered across guides.
Troubleshooting
| Symptom | Fix |
|---|
| "Invalid API key" | Re-copy the key from console.anthropic.com/settings/keys — they can't be viewed twice. |
| Run fails with a billing error | Claude needs billing enabled even for small usage. Add a payment method in the console. |
See also: How your data stays on your laptop · Configuration reference
How-to guide
Export video clips
Cut a short video clip for each starred quote, to drop into a deck or share with your team.
Same steps in the app and in your browser.
- In the report, star the quotes you want as clips.
- Open Export → Extract video clips.
- Choose a folder. Bristlenose cuts one clip per starred quote, named by participant and timecode.
Clips contain the original audio and video — including any names spoken aloud. Anonymisation doesn't apply to clips. Share them as carefully as the recordings themselves.
Clips need ffmpeg. The desktop app already bundles it; on the CLI, install it once (brew install ffmpeg) — bristlenose doctor will tell you if it's missing.
Reference
Configuration
Every setting Bristlenose reads, in precedence order: command-line flag, then environment variable, then .env file, then the default.
Environment variables
| Variable | Default | Description |
|---|
BRISTLENOSE_LLM_PROVIDER | claude | Which AI provider to use: claude, chatgpt, azure, gemini, local. |
BRISTLENOSE_ANTHROPIC_API_KEY | none | API key for Claude. Read from the system credential store if unset. |
BRISTLENOSE_OPENAI_API_KEY | none | API key for ChatGPT. |
BRISTLENOSE_LOCAL_URL | localhost:11434 | Ollama server address for local models. |
BRISTLENOSE_LOCAL_MODEL | llama3.2 | Which local model to run. |
BRISTLENOSE_WHISPER_MODEL | large-v3-turbo | Transcription model size. Smaller is faster and less accurate. |
BRISTLENOSE_LOG_LEVEL | INFO | Log file verbosity. Independent of terminal -v. |
This page describes the settings. To set a key, follow Set up Claude (or the guide for your provider).
Explanation
How your data stays on your laptop
Bristlenose is local-first by design. This is what that means in practice — and where the one exception is.
When you analyse a folder, the recordings, the transcripts, and the finished report all live on your machine. Transcription runs locally. The only thing that ever leaves your laptop is the text Bristlenose sends to an AI provider to extract quotes and themes — and only if you've chosen a cloud provider.
What's sent, and what isn't
With a cloud provider (Claude, ChatGPT, Gemini), Bristlenose sends the transcript text for analysis. It does not send the audio or video, and the provider doesn't use your data for training. Participant names in the transcript are sent as-is unless you turn on redaction.
The fully-local option
If even the transcript text shouldn't leave the machine, run a local model with Ollama. Then nothing is uploaded at all — the trade-off is that local models are slower and, in 2026, less sharp than the cloud ones. It's the right choice for sensitive studies.
This page explains the why. For the steps, see Set up Claude or the Ollama guide; for the exact boundary, see the security reference.
Why we drew the line here
Sending the transcript (and nothing heavier) is the smallest amount of data that still lets a capable model do the analysis. We could send less and accept worse results, or send more and gain little. Transcript-only is the point where quality and privacy are both well served — and the local option exists for when "well served" isn't enough.