Setup guide

Pull your WhatsApp into your second brain

Text plus transcribed voice notes, from WhatsApp Desktop into your Obsidian vault. It runs entirely on your own Mac. Nothing uploads anywhere; transcription happens on your machine.

~45 min one-time setup Runs on your Mac 100% local Your account, your data

Fastest path

Let your Claude Code do it

Your Claude Code does all the software work: installs the tools, fetches the script, runs it, and writes into your vault. Do the two steps below first (only you can), then paste the prompt. If either is missing, Claude will notice and tell you exactly what to fix.

Your step 1

Install and link WhatsApp Desktop from the Mac App Store, scan the QR with your phone, and let it sync older history. Linking needs your phone, so Claude cannot do it.

Your step 2

Grant Full Disk Access to whatever runs your Claude Code (Terminal, or the Claude app) in System Settings > Privacy & Security, then quit and reopen it. Apple only lets a person flip this switch.

Paste into Claude Code

Loading…

Prefer to click through it yourself? The manual walkthrough is below.

Manual walkthrough

Setup progress 0 / 7 steps

Before you start, have ready

The full path to your Obsidian vault (the folder your notes live in). You will point the import at a WhatsApp subfolder inside it.
A short list of the chats you want to import. Start with 3 to 5 of your most valuable ones. Do not start with every chat.
Your phone nearby, to scan the QR when you link WhatsApp.

Install and sync WhatsApp Desktop

On your Mac, open the Mac App Store, search WhatsApp, install the official Meta app. Use the App Store version, not a downloaded one.

Open it. On your phone: WhatsApp > Settings > Linked Devices > Link a Device, and scan the QR. When it offers to sync older chat history, say yes and let it finish.

Only recently synced voice notes keep a live download link. For very old ones, scroll up in the chat and tap them so the app re-downloads. You capture what is live now and catch the rest over time.

Mark done

Grant Terminal Full Disk Access

The one step everyone forgets. The script reads WhatsApp's protected folder and cannot without this.

System Settings > Privacy & Security > Full Disk Access. Toggle Terminal on. If it is not listed, click + and add it from Applications > Utilities. Then fully quit and reopen Terminal, or the permission will not apply.

Mark done

Install the tools

Open Terminal and run these one block at a time. First, Homebrew (skip if brew --version already works):

Terminal

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then the audio and transcription tools plus the one Python library:

Terminal

brew install ffmpeg whisper-cpp
pip3 install cryptography

Confirm the transcriber is present (should print a path):

Terminal

which whisper-cli

Mark done

Download the model and place the script

Make a working folder and download the speech-to-text model (about 1 GB, accurate on accents and cross-talk):

Terminal

mkdir -p ~/whatsapp-brain && cd ~/whatsapp-brain
curl -L -o model.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin
export WHISPER_MODEL=~/whatsapp-brain/model.bin

For a faster, smaller option swap the filename for ggml-base.en.bin. Turbo is more accurate on accents and fast speech, which matters for voice notes.

Open a new file to hold the script:

Terminal

nano ~/whatsapp-brain/whatsapp_to_brain.py

Copy the full script below, paste into nano, then press Ctrl+O, Enter, Ctrl+X.

The script — whatsapp_to_brain.py

Python

Loading…

Mark done

List your chats and pick the ones to import

This prints every chat with its exact name and message count. Note the names you want, copied exactly.

Terminal

cd ~/whatsapp-brain
python3 whatsapp_to_brain.py --list

Mark done

Import the chosen chats into your vault

Replace the vault path with your real one and use your name as the owner label. Each chat becomes one markdown file with voice notes transcribed and dropped in at the moment they were sent.

Terminal

export WHISPER_MODEL=~/whatsapp-brain/model.bin
python3 whatsapp_to_brain.py \
  --owner "YOUR NAME" \
  --chat "Name 1" \
  --chat "Name 2" \
  --out "/Users/you/YourVault/WhatsApp"

Fast text-only first pass, no waiting on transcription:

Terminal

python3 whatsapp_to_brain.py --chat "Name 1" --no-voice --out "/Users/you/YourVault/WhatsApp"

Mark done

Confirm it landed in the brain

Open Obsidian on your Mac. The WhatsApp folder now holds the chat files. Open one, find a voice note line, confirm the transcript reads correctly. From here your normal brain workflow can digest these like any other note.

Mark done

A note on privacy

This can read your entire WhatsApp, personal and family chats included. Only the chats you name in Step 6 get imported, nothing else. Pick the business-relevant ones rather than everything, and keep in mind that group chats bring other people's messages into your notes. Your call, made on purpose.

If something breaks

Troubleshooting

"database not found" or "cannot open"Full Disk Access was not granted, or Terminal was not restarted after granting it. Redo Step 2.
"whisper-cli not found"The brew install did not finish, or the shell needs a restart. Re-run brew install whisper-cpp and reopen Terminal.
Voice notes mostly "unavailable"Their download links expired. Open the chat, scroll up and tap the older voice notes so WhatsApp re-downloads them, then re-run Step 6.
A chat name has quotes or emojiCopy a unique clean part of the name for --chat; it matches on any substring.

Keeping it fresh

Re-running the same Step 6 command re-exports those chats with the latest messages. Once the first run works, ask your Claude Code to add a small scheduled job that runs it each morning, so your brain stays current without you thinking about it.