Client setup runbook

Pull WhatsApp into the second brain

Text plus transcribed voice notes, from WhatsApp Desktop into Obsidian. Runs entirely on the client's own Mac. Nothing uploads anywhere; transcription happens locally.

~45 min first run Runs on his Mac Over screen share His account, his data

Fastest path

Hand it to his Claude Code

His Claude Code does all the software work: installs the tools, fetches the script, runs it, and writes into his vault. Do the two human steps first, then paste the prompt. If either is missing, Claude notices and tells him what to fix.

Human step 1

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

Human step 2

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

Paste into Claude Code

Loading…

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

Manual walkthrough

Setup progress 0 / 7 steps

Before the call, have ready

The exact Obsidian vault path from him. Confirm it live: there is a known split between StewartOS1 and a separate second-brain folder. Get the real one or you write into the wrong brain.
A short list of chats to import. Start with 3 to 5 high-value ones. Do not start with "all chats."
The script below (Step 4 has it embedded, ready to copy).

Install and sync WhatsApp Desktop

On his 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 his 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. Very old ones may need him to scroll up in the chat and tap them so the app re-downloads. We 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, which matters for his 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 his 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 his vault

Replace the vault path with his real one and use his 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 "Stewart" \
  --chat "Mo Asmal" \
  --chat "Monica" \
  --chat "Courtney" \
  --out "/Users/stewart/StewartOS1/WhatsApp"

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

Terminal

python3 whatsapp_to_brain.py --chat "Mo Asmal" --no-voice --out "/Users/stewart/StewartOS1/WhatsApp"

Mark done

Confirm it landed in the brain

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

Mark done

Say this to him, plainly

This reads his entire WhatsApp, personal and family chats included. Only the chats you name in Step 6 get imported. Recommend he chooses the business-relevant ones rather than everything, and note that group chats bring other people's messages into his brain. His informed call.

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. Have him 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 manual run is proven and the vault path is confirmed stable, we add a small scheduled job on his Mac that runs it each morning. Do that only after the first run works.