pi-harness-whatsapp 0.1.0 → 0.1.2

package/AGENT_INSTALL.md

@@ -1,6 +1,6 @@
-# Installing pi-harness-whatsapp: notes for AI agents
+# Installing (and uninstalling) pi-harness-whatsapp: notes for AI agents
 
-This file is for an AI agent (Pi, Claude Code, Codex, …) asked to install this extension for a user. Read it fully before changing anything.
+This file is for an AI agent (Pi, Claude Code, Codex, …) asked to install or remove this extension for a user. Read it fully before changing anything. **Asked to remove it?** Go to [Uninstalling](#uninstalling).
 
 ## What you can and can't do
 
@@ -22,8 +22,16 @@ Do these yourself before asking anything, so your questions can include the resu
   echo '{"type":"get_commands"}' | pi --mode rpc | grep '"get_commands"'
   ```
   If another package already registers `/whatsapp` (each entry shows its `source`), tell the user it has to be removed first, and ask before removing it. Other WhatsApp extensions that use different command names can stay.
-- **ffmpeg:** run `ffmpeg -version`. Without it, text still works, but voice notes don't. If it's missing, ask before installing it (it usually needs sudo: `sudo apt install ffmpeg`, `brew install ffmpeg`, …).
-- **Voice support on this machine:** voice notes need about **3.5 GB of free RAM** while they're processed (check with `free -m`) and **1.5 GB of disk** for the speech files. They work on Linux (x64 or ARM64), Windows (x64) and macOS on Apple Silicon, but not on Intel Macs or Windows on ARM. If the machine can't do voice, tell the user: text still works, and they should keep Reply type on text.
+- **ffmpeg** (only needed if the user wants voice): run `ffmpeg -version`. Without it, text, images and files still work, but voice notes don't. If it's missing and they want voice, ask before installing it (it usually needs sudo: `sudo apt install ffmpeg`, `brew install ffmpeg`, …), and **record what you install** (see [Record what you install](#record-what-you-install-outside-pi)).
+- **Voice support on this machine:** voice is optional and off by default. It works on Linux (x64 or ARM64), Windows (x64) and macOS on Apple Silicon, not on Intel Macs or Windows on ARM. What each part needs (check with `free -m` and `df -h ~`):
+
+  | Part | Disk | Free RAM while a voice note is handled |
+  |---|---|---|
+  | Understand voice notes (speech-to-text) | 1.0 GB | about 2 GB |
+  | Reply with voice notes (text-to-speech) | 0.6 GB | about 1.2 GB |
+  | Both | 1.4 GB | about 3.4 GB |
+
+  If the machine can't do voice, say so when you ask about it, and leave voice off.
 
 ## 2. Ask the basics
 
@@ -32,7 +40,8 @@ Ask these together, in one message, and wait for the answers:
 1. **Which WhatsApp number will Pi use?** Recommend a **second number**. The extension uses an unofficial WhatsApp Web client (Baileys), and WhatsApp may restrict numbers that use one. Using their own number also works: they then talk to Pi in the "Message yourself" chat.
 2. **Owner:** their own phone number, with country code. The owner is the only one who can change Pi from WhatsApp (`/model`, `/compact`, `/quit`, …). If they don't know it yet, skip it: the first person who messages the bot is offered as owner in the terminal.
 3. **Languages:** which languages they'll write and speak in. The default is English only. Supported: English, Turkish, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Russian, Ukrainian, Arabic, Hindi, Swedish and Finnish. Hindi voice notes are less accurate than the others (see the README's table). Adding languages downloads nothing extra.
-4. **Background service:** should Pi keep running without a terminal (see "Run in the background" in the README)? Don't set it up unless they say yes. If they do, ask which project folder Pi should work in.
+4. **Voice notes:** off (the default), understand voice notes, reply with voice notes, or both? Give them the disk and RAM from the table in step 1, and the result of your check. Off means a voice note gets "🎤 Voice notes are off. Please type your message."; they can switch voice on later in `/whatsapp` → Voice notes.
+5. **Background service:** should Pi keep running without a terminal (see "Run in the background" in the README)? Don't set it up unless they say yes. If they do, ask which project folder Pi should work in.
 
 ## 3. Offer the other settings
 
@@ -40,11 +49,11 @@ Then show the remaining settings in **one** message, with the default for each,
 
 | Setting (name in `/whatsapp`) | What it does | Default | Other choices |
 |---|---|---|---|
-| Reply type | How Pi answers | **mirror me**: a voice note gets a voice reply, text gets text | text only · voice note · voice note + text |
+| Reply type (only with "reply with voice notes") | How Pi answers | **mirror me**: a voice note gets a voice reply, text gets text | text only · voice note · voice note + text. With "reply" but not "understand", mirror me means text replies only, so suggest "voice note" if they want to hear Pi. |
 | Reply language | Which language Pi answers in | **mirror me**: the language they used | always one of their languages |
 | Fallback language | Used only when Pi can't tell the language (e.g. very short replies) | **the first language** they named | any of their languages |
-| Voice per language | Which voice speaks each language | **F1** (female) | F2–F5 (female), M1–M5 (male); the same 10 voices for every language |
-| Voice reply speed | How fast voice replies are spoken | **1.0** | 0.5–2.0 (0.9 slower, 1.2 faster) |
+| Voice per language (only with "reply with voice notes") | Which voice speaks each language | **F1** (female) | F2–F5 (female), M1–M5 (male); the same 10 voices for every language |
+| Voice reply speed (only with "reply with voice notes") | How fast voice replies are spoken | **1.0** | 0.5–2.0 (0.9 slower, 1.2 faster) |
 | Terminal answers | Also sends the owner Pi's answers to prompts typed in the terminal, as text | **off** | on |
 | Progress messages | Sends what Pi writes while it's still working | **off** | on |
 | Live tool log | One message, updated live, with the latest tool steps | **off** | on |
@@ -71,11 +80,12 @@ Settings live in `~/.pi/agent/pi-harness-whatsapp/config.json`. Unknown or inval
 
 Pi reads this file when a session starts, and saves it when a setting changes. If a Pi with this extension is already running, ask the user to quit it before you write the file, so it doesn't keep the old settings or save over yours.
 
-Example: English and Turkish, a male voice for Turkish, the owner set, stats on, a slightly faster voice:
+Example: English and Turkish, voice notes both ways, a male voice for Turkish, the owner set, stats on, a slightly faster voice:
 
 ```json
 {
   "version": 1,
+  "voice": { "understand": true, "reply": true },
   "languages": ["en", "tr"],
   "voices": { "tr": "M1" },
   "voiceMode": "mirror",
@@ -88,9 +98,10 @@ Example: English and Turkish, a male voice for Turkish, the owner set, stats on,
 
 | Field | Setting | Values |
 |---|---|---|
+| `voice` | Voice notes | `{ "understand": <bool>, "reply": <bool> }`, both `false` by default. Always write this field, even when both are `false`. |
 | `languages` | My languages, Fallback language | Language codes from the table below. The **first** one is the fallback language. |
 | `voices` | Voice per language | `{ "<code>": "<voice>" }` with a voice from `F1`–`F5`, `M1`–`M5`, for the languages whose voice should differ from the default (`F1`) |
-| `voiceMode` | Reply type | `mirror` (default) · `off` (text only) · `voice` · `voice+text` |
+| `voiceMode` | Reply type | `mirror` (default) · `off` (text only) · `voice` · `voice+text`. Only used while `voice.reply` is `true`. |
 | `replyLanguage` | Reply language | `mirror` (default) or one of `languages` |
 | `voiceSpeed` | Voice reply speed | 0.5–2.0 (default 1.0) |
 | `replies` | Terminal answers, Progress messages, Live tool log, Changed files, Stats | `{ "terminal", "interim", "toolActivity", "touchedFiles", "summary" }`, booleans, all `false` by default |
@@ -106,7 +117,46 @@ Language codes: `en` English · `tr` Turkish · `de` German · `fr` French · `e
 
 If the user can't decide on a voice, keep the default and tell them they can hear each one later: `/whatsapp` → Voice per language → a voice → "Send me a sample on WhatsApp".
 
-Speech files download by themselves when first needed. You don't have to fetch them.
+Speech files download by themselves when first needed: with voice switched on in the file, the first voice note (or the first spoken reply) waits for the download, and the chat is told. You don't have to fetch them. Tell the user. If they'd rather download right away, leave `voice` off in the file and have them tick the parts in `/whatsapp` → Voice notes after starting Pi: leaving that menu asks "Download now (recommended)" or "When first needed".
+
+## Record what you install outside Pi
+
+Anything you install on the computer for this extension (ffmpeg, and tmux for the background service) must be recorded in `setup.json` in the data folder (`~/.pi/agent/pi-harness-whatsapp/setup.json`, or the folder from `PI_HARNESS_WHATSAPP_DIR`). When the user later uninstalls, `/whatsapp` → Remove everything reads it, asks the user about each entry, and removes **exactly those packages** again. A program that was already installed is not recorded.
+
+Record every package the install added, not just the one you asked for: installing ffmpeg with apt pulls in about 100 libraries. List the packages before and after, and record the difference:
+
+```bash
+dpkg-query -W -f='${Package}\n' | sort > /tmp/phw-before.txt
+sudo apt-get install -y ffmpeg
+dpkg-query -W -f='${Package}\n' | sort > /tmp/phw-after.txt
+comm -13 /tmp/phw-before.txt /tmp/phw-after.txt   # these are the "packages"
+rm /tmp/phw-before.txt /tmp/phw-after.txt
+```
+
+Other package managers: list with `brew list --formula -1 | sort` (Homebrew), `rpm -qa --qf '%{NAME}\n' | sort` (dnf, zypper), `pacman -Qq` (pacman) or `apk info | sort` (apk), the same way. For winget, record the package id you installed.
+
+Then write (or add to) `setup.json`, and keep it private (`chmod 600`):
+
+```json
+{
+  "version": 1,
+  "installed": [
+    {
+      "what": "ffmpeg",
+      "manager": "apt",
+      "packages": ["ffmpeg", "libavcodec61", "libavformat61", "…every name from the comm output…"],
+      "at": "2026-10-15",
+      "by": "Claude Code"
+    }
+  ]
+}
+```
+
+- `manager` is one of `apt`, `dnf`, `pacman`, `zypper`, `apk`, `brew`, `winget`. Entries with anything else, or with package names that aren't plain names, are ignored.
+- `what` is the name the user will see ("ffmpeg", "tmux"); `at` and `by` are optional and shown to the user.
+- If the install added nothing (it was already there), don't add an entry.
+
+A background service isn't recorded here (Pi can't remove the service it runs in); tell the user about it, and see Uninstalling, step 3.
 
 ## 6. Hand over to the user
 
@@ -120,11 +170,15 @@ Tell the user:
 
 Then tell them, briefly:
 
-- Anything that isn't a command goes to Pi as a prompt. Voice notes, images and files work too.
+- Anything that isn't a command goes to Pi as a prompt. Images and files work too: Pi sees images, gets files saved for it to open, and can send images and files back when asked ("send me the screenshot").
+- Voice notes, if they turned them on: understanding and replying can each be switched on or off in `/whatsapp` → Voice notes; switching a part off deletes its files after asking. To stop voice replies without deleting anything, set Reply type to text.
+- To remove it later, the README's **Uninstall** section has the steps (in Pi: `/whatsapp` → Danger → Remove everything, or `/whatsapp remove`, then `pi uninstall`).
 - If they want Pi in a group: add the bot's number to the group, have someone write there, then allow it in `/whatsapp` → Allowed chats → Pick from recent chats. In the group, people @mention Pi or reply to its messages; Pi also sees the last 20 text messages before that for context. You can't allow a group for them in advance, because the group's id is only known once it appears in recent chats. Remind them that every member of an allowed group can prompt Pi.
 - From WhatsApp they can switch the model (`/model`), the reasoning level (`/think`), compact (`/compact`), stop a run (`/stop`), start a new session (`/new`) and change the reply type, language, speed and extras (`/voice`, `/lang`, `/speed`, `/replies`). Menus come as polls: tap an option.
 - Everything else, including on/off, allowed chats and voices, is in `/whatsapp` in the terminal.
 
+Finally, tell the user **everything you set up outside Pi**: for example "installed ffmpeg with apt (recorded in setup.json, so Remove everything can take it out again)", "created `~/.config/systemd/user/pi-whatsapp.service` and enabled lingering". If you have a memory or notes file for this user, write it there too.
+
 ## Check it worked
 
 - The footer of Pi shows `WA: connected as +<number> · <n> chats`.
@@ -138,6 +192,75 @@ Then tell them, briefly:
 - Don't set `commandAccess` to `allowed` unless the user asks.
 - Don't install the systemd service, or enable it at boot, without the user's yes.
 - Don't publish, fork or re-upload this package on the user's behalf.
+- Don't edit or delete Pi's session files (`~/.pi/agent/sessions/`), not even to remove WhatsApp traces; see [Uninstalling](#uninstalling).
+- When uninstalling, don't delete more than the steps say: no whole `PI_HARNESS_WHATSAPP_DIR` folder that holds other files, and no ffmpeg, tmux or npm cache without the user's yes.
+
+## Uninstalling
+
+Goal: **nothing left behind** on the user's computer, and Pi unlinked from their phone. Follow these steps in order. Don't improvise extra deletions.
+
+### What the extension leaves on a computer
+
+| What | Where | Removed by |
+|---|---|---|
+| The code | Pi's package folder, plus an entry in `~/.pi/agent/settings.json` | `pi uninstall` |
+| All its data: WhatsApp login (`auth/`), speech files (`models/`, ~1.5 GB), settings (`config.json`), recent chats, received files (`inbox/`), log (`log/`), lock, `setup.json` | `~/.pi/agent/pi-harness-whatsapp/` (or `$PI_HARNESS_WHATSAPP_DIR` if set; or `$PI_CODING_AGENT_DIR/pi-harness-whatsapp/` if that is set) | "Remove everything", or deleting the folder |
+| The linked device on the phone | WhatsApp → Settings → Linked devices | "Remove everything", or the user on their phone |
+| A background service, only if one was set up | a systemd unit (usually `~/.config/systemd/user/*.service` or `/etc/systemd/system/*.service`), maybe lingering and a tmux session | you, step 3 |
+| Copies of it and its npm packages | npm's download cache (`~/.npm/_cacache`) | "Remove everything" (only these entries) |
+| Programs installed for it, only if they were | `ffmpeg`, `tmux`; listed in `setup.json` when recorded | "Remove everything" asks about each; or you, step 6, with the user's yes |
+
+The extension writes nowhere else. It never edits shell profiles or creates files outside its data folder.
+
+### Steps
+
+1. **Look first, change nothing yet.**
+   - `pi list`: note the exact source (`npm:pi-harness-whatsapp`, or a `git:` source).
+   - The data folder: check `PI_HARNESS_WHATSAPP_DIR` and `PI_CODING_AGENT_DIR` in the environment; otherwise it's `~/.pi/agent/pi-harness-whatsapp/`.
+   - A service: `grep -rlE "pi-harness-whatsapp|PI_HARNESS_WHATSAPP|--whatsapp" ~/.config/systemd/user /etc/systemd/system 2>/dev/null`.
+   - Programs installed just for this: read `setup.json` in the data folder. If there's none, check your notes or ask the user.
+2. **Tell the user what will be removed and get a yes.** The WhatsApp login is deleted, so using it again means a new QR scan; the speech files would have to download again.
+3. **Stop the service, if there is one** (so it can't start Pi again): `systemctl --user disable --now <unit>` (system unit: `sudo systemctl disable --now <unit>`). Delete its unit file, then run `systemctl --user daemon-reload` (or `sudo systemctl daemon-reload`). Kill its tmux session if it's still there (`tmux ls`, then `tmux kill-session -t <name>`). If lingering was turned on only for this service (your notes, or ask), run `loginctl disable-linger`.
+4. **Clean up the data from inside Pi.** First ask the user to close every Pi window. Then either the user does it, or you do it through Pi's RPC mode.
+
+   **You, over RPC** (from the user's usual project folder, with no other Pi running): start `pi --mode rpc`, and send this line on its stdin:
+   ```json
+   {"id": "1", "type": "prompt", "message": "/whatsapp remove"}
+   ```
+   Pi then sends `extension_ui_request` records on stdout. For each one with `"method": "confirm"`, show the user its `title` and `message`, and answer with their decision, using the request's `id`:
+   ```json
+   {"type": "extension_ui_response", "id": "<the request's id>", "confirmed": true}
+   ```
+   The first question is "Remove everything?"; then one "Also remove …?" per program in `setup.json`. Records with `"method": "notify"` are progress and the result; the last one starts with `WhatsApp removed.` and lists what was done and any command left for you to run. Show it to the user, then close stdin so Pi quits. Read stdout as a stream and split records on `\n` only (see Pi's `docs/rpc.md`).
+
+   **Or the user**, in Pi:
+   1. run `/whatsapp` → **Danger** → **Remove everything (before uninstalling)…** (or type `/whatsapp remove`) and confirm. It unlinks the phone, deletes the data folder, removes this extension's entries from npm's cache, and asks about each program in `setup.json` (removing exactly the recorded packages, after an apt dry run that keeps everything if anything else would go too),
+   2. read you its summary (the last notice), then quit Pi.
+
+   **Already uninstalled?** The cleanest way is to install it again (`pi install npm:pi-harness-whatsapp`) and do the step above (over RPC, or the user); it then also cleans what the first uninstall left behind.
+
+   **By hand** (only if the user doesn't want that): read `setup.json` first (step 6 needs it). Make sure no Pi is running (the user quits them all; `connection.lock` in the data folder shows the pid of a Pi that holds WhatsApp), then delete the data folder: `rm -rf ~/.pi/agent/pi-harness-whatsapp`. **If `PI_HARNESS_WHATSAPP_DIR` points at a folder that also holds other things, delete only these entries in it:** `config.json*`, `recents.json*`, `auth/`, `models/`, `inbox/`, `log/`, `connection.lock`, `announce.json`, `setup.json`. This way, npm's cache keeps its copies: only "Remove everything" knows which entries are this extension's, and `npm cache clean --force` (only if the user asks) empties the whole cache. Then tell the user to unlink Pi on their phone: WhatsApp → Settings → Linked devices → tap the device that belongs to Pi → Log out.
+5. **Remove the code:** `pi uninstall <source from step 1>`, with Pi not running. npm leaves some empty folders behind (e.g. `@types`); remove only empty ones:
+   `find ~/.pi/agent/npm/node_modules ~/.pi/agent/git -mindepth 1 -type d -empty -delete 2>/dev/null`. Don't touch anything else in those folders; other Pi packages live there.
+6. **Programs:** "Remove everything" already asked about each `setup.json` entry; its summary says what was removed, and gives the command for anything it couldn't do (for example when `sudo` needs a password). Run those commands only if the user says yes. If you went the manual way, for each entry, with the user's yes: for apt, first run `apt-get -s remove --purge <packages>` and continue only if every line starting with `Remv` or `Purg` names a package from the entry; then `sudo apt-get remove --purge -y <packages>` and delete those packages' downloaded files, `/var/cache/apt/archives/<name>_*.deb`. Never remove a program that wasn't recorded or confirmed by the user; other programs may need it.
+7. **Verify, and show the user the output.** All of these must come back empty (or "No such file or directory"):
+   ```bash
+   pi list | grep -i whatsapp
+   ls -a ~/.pi/agent/pi-harness-whatsapp
+   find ~/.pi ~/.config/systemd /etc/systemd -iname "*pi-harness-whatsapp*" 2>/dev/null
+   find ~/.pi/agent/npm/node_modules ~/.pi/agent/git -mindepth 1 -type d -empty 2>/dev/null
+   grep -rlE "pi-harness-whatsapp|PI_HARNESS_WHATSAPP" ~/.config/systemd /etc/systemd ~/.bashrc ~/.profile ~/.zshrc 2>/dev/null
+   npm cache ls 2>/dev/null | grep -i "pi-harness-whatsapp"
+   ```
+   For each removed `setup.json` entry, `dpkg-query -W <packages>` (or your package manager's equivalent) must no longer show them as installed.
+8. **Report** what you removed, and what stays on purpose (below).
+
+### What stays, on purpose; don't delete it
+
+- **Pi's sessions** (`~/.pi/agent/sessions/`). Conversations with Pi from WhatsApp are normal Pi sessions and contain small `pi-harness-whatsapp/session` entries (WhatsApp on/off). Pi ignores them without the extension. **Never edit session files**: entries are linked to each other, and cutting some out breaks the session. If the user wants those conversations gone, they delete whole sessions in Pi.
+- **Other packages in npm's cache.** Only this extension's entries are removed. Emptying the whole cache (`npm cache clean --force`) is only for when the user asks for it.
+- **npm's own logs** (`~/.npm/_logs`, its last few runs) may mention the install; npm replaces them as it runs again.
+- **The package manager's history** (`/var/log/apt/history.log`, `/var/log/dpkg.log`, …) records installs and removals of every program. Never edit system logs.
 
 ## Troubleshooting
 

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.2 — 2026-10-16
+
+- **Fixed file permissions:** the data folder and the WhatsApp login in it were readable by other users on the same machine. Every folder the extension creates is now private (only your user can open it), and existing installs are fixed the next time Pi starts.
+
+## 0.1.1 — 2026-10-15
+
+- **Voice is optional, and off by default.** `/whatsapp` → Voice → **Voice notes** has two ticks: understand voice notes (speech-to-text, 1.0 GB) and reply with voice notes (text-to-speech, 0.6 GB), plus "Delete all speech files". Leaving the menu asks before deleting the files of a part you unticked ("You set speech-to-text for removal. 828 MB will be freed."; No puts the tick back) and offers to download a part you ticked (now, or when first needed). Nothing is downloaded while voice is off.
+- While understanding is off, a voice note gets "🎤 Voice notes are off. Please type your message." (in groups, only one that replies to Pi) and never reaches the model.
+- Reply type, the voices and the voice speed are greyed out until voice replies are on, and say which tick turns them on. `/voice` and `/speed` on WhatsApp say so instead of changing anything; `/help` and `/status` show both switches.
+- The panel has a VOICE section and a DANGER section (Remove everything, and where the log file is); the Speech files row is gone.
+- Existing setups keep the voice parts whose files are already on disk. Leftovers from older versions (Piper voices, older Whisper models, unfinished downloads nothing needs) are deleted on start.
+- README and AGENT_INSTALL: what voice costs in disk and RAM per part, the new settings, and an install question about voice.
+
+- **Uninstall without leftovers:** `/whatsapp` → Connection → **Remove everything (before uninstalling)**, or `/whatsapp remove`, unlinks Pi from the phone (connecting first if needed), stops running downloads, deletes every file the extension made, removes its copies (and its dependencies') from npm's download cache, and keeps Pi from writing any more until it quits. It refuses while another Pi holds WhatsApp. AI agents can run it over Pi's RPC mode.
+- **`setup.json`:** programs installed just for the extension (ffmpeg, tmux) are recorded with the exact packages that came with them; Remove everything asks about each and removes exactly those (apt: after a dry run that keeps everything if anything else would go too; Homebrew: `brew uninstall`; otherwise it shows the command). AGENT_INSTALL tells agents how to record them.
+- The README and AGENT_INSTALL describe the full uninstall, the background service, what stays on purpose and how to check that nothing is left.
+- A Pi that never turned WhatsApp on no longer creates a log or recent-chats file when it quits.
+- README: a section on sending and receiving images and files.
+- The examples in Pi's instructions for spoken replies are in English.
+
 ## 0.1.0 — 2026-10-15
 
 First release.

package/README.md

@@ -6,23 +6,36 @@
 
 Talk to the [Pi coding agent](https://pi.dev) from WhatsApp: text, voice notes, images and files. Pi answers automatically, and you can switch models, compact the context or stop a run from your phone.
 
-> 🤖 **AI agent installing this for someone?** Read [AGENT_INSTALL.md](AGENT_INSTALL.md) first: what to ask the user, how to configure, and what never to touch.
+> 🤖 **AI agent installing or removing this for someone?** Read [AGENT_INSTALL.md](AGENT_INSTALL.md) first: what to ask the user, how to configure, how to uninstall without leaving anything behind, and what never to touch.
 
 - **Scan a QR code once and you're in.** Pi runs as a linked device of a WhatsApp number. The login is saved, and Pi reconnects on its own.
 - **Replies are automatic.** Pi's final answer is always sent back. The model doesn't have to call a tool.
 - **You choose what else you get:** a summary line (`✅ 4/6 tool calls ok · ⏱ 2m 14s`), in-between messages, the list of touched files, and a live tool-activity message.
-- **Voice notes both ways, on your own CPU.** [Whisper](https://github.com/openai/whisper) turbo understands them and [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) speaks the replies, both through Intel's [OpenVINO](https://github.com/openvinotoolkit/openvino). No GPU or cloud service needed, in 15 languages.
+- **Optional voice notes, both ways, on your own CPU.** [Whisper](https://github.com/openai/whisper) turbo understands them and [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) speaks the replies, both through Intel's [OpenVINO](https://github.com/openvinotoolkit/openvino). No GPU or cloud service needed, in 15 languages. Off by default; see below for what it costs.
+- **Images and files both ways.** Send Pi a photo or screenshot and it sees it; send a file (PDF, log, zip, …) and it's saved for Pi to open. Ask Pi for an image or a file and it sends it to your chat, and screenshots its tools take can come automatically.
 - **Control Pi from WhatsApp** with commands and poll menus: `/model`, `/think`, `/compact`, `/stop`, `/new`, `/status`, …
 - **A real off switch.** Off means disconnected: nothing is read or sent, and the WhatsApp tools disappear from the model.
 
+> **Voice is optional and off by default.** Turn it on in `/whatsapp` → **Voice notes**, one part or both:
+>
+> | Part | Disk | RAM while a voice note is handled |
+> |---|---|---|
+> | Understand voice notes (speech-to-text) | 1.0 GB | about 2 GB |
+> | Reply with voice notes (text-to-speech) | 0.6 GB | about 1.2 GB |
+> | Both | 1.4 GB (they share a 202 MB engine) | about 3.4 GB |
+>
+> The files download only once you switch a part on, and switching it off deletes them again. The models are unloaded after 10 minutes without voice work, so idle RAM use is zero. Everything runs on the CPU; nothing goes to the cloud.
+
 > **Use a second number if you can.** This extension uses [Baileys](https://github.com/WhiskeySockets/Baileys), an unofficial WhatsApp Web client. WhatsApp can restrict numbers that use unofficial clients, so a spare number is the safe choice.
 
 ## Requirements
 
 - Pi 1.2 or newer
-- `ffmpeg` on the PATH (for voice notes): `sudo apt install ffmpeg`
-- For voice notes: Linux (x64 or ARM64), Windows (x64) or macOS on Apple Silicon. OpenVINO has no build for Intel Macs or Windows on ARM; text works there, voice notes don't.
-- For voice notes: about 3.5 GB of free RAM while they're being processed, and 1.5 GB of disk
+
+Only if you turn voice on:
+- `ffmpeg` on the PATH: `sudo apt install ffmpeg`
+- Linux (x64 or ARM64), Windows (x64) or macOS on Apple Silicon. OpenVINO has no build for Intel Macs or Windows on ARM; text, images and files work there, voice notes don't.
+- The disk and free RAM from the table above.
 
 ## Install
 
@@ -78,21 +91,23 @@ Every row opens a small menu with the choices and a short explanation. Nothing c
 | | Who can use commands | **Only me** (the owner) · all allowed chats. |
 | | Ask on/off at session start | On · **Off**. Asks whether WhatsApp should be on when a session opens. |
 | Replies | Final answer | Always on. |
-| | Reply type | **Mirror me** (voice note in → voice reply) · text · voice · voice + text. |
 | | Terminal answers | On · **Off**. Also sends the owner Pi's answers to prompts typed in the terminal, as text. |
 | | Progress messages | On · **Off**. What Pi writes while it's still working. |
 | | Live tool log | On · **Off**. One message, updated live, with the latest tool steps. |
 | | Changed files | On · **Off**. The files Pi wrote or edited. |
 | | Stats (tools · time) | On · **Off**. A line like `✅ 4/6 tool calls ok · ⏱ 2m 14s`. |
 | | Auto-send tool images | On · **Off**. Every image a tool makes while answering you (e.g. browser screenshots). You can always ask Pi to send a specific image instead. |
+| Voice | Voice notes | Two ticks, both **off**: **Understand voice notes** (1.0 GB) and **Reply with voice notes** (0.6 GB), plus **Delete all speech files**. See [Voice](#voice). |
+| | Reply type | **Mirror me** (voice note in → voice reply, text in → text reply) · text · voice · voice + text. Greyed out until "Reply with voice notes" is on. Without "Understand voice notes", mirror me answers everything with text (Pi gets no voice notes to mirror), so pick voice if you want spoken replies. |
+| | Voice per language | Which voice speaks each language: one of 10 voices, **F1**–F5 (female) and M1–M5 (male), the same list for every language. "Send me a sample" sends a short voice note to your WhatsApp first. Greyed out until "Reply with voice notes" is on. |
+| | Voice reply speed | 0.9 · **1.0** · 1.2 · custom (0.5–2.0). Greyed out until "Reply with voice notes" is on. |
 | Languages | Reply language | **Mirror me** (the language you used) or one of your languages. |
 | | My languages | Tick the languages you use (**English**). See [Voice](#voice) for the 15 languages. |
 | | Fallback language | Used only when Pi can't tell which language to use (**the first of your languages**). |
-| | Voice per language | Which voice speaks each language: one of 10 voices, **F1**–F5 (female) and M1–M5 (male), the same list for every language. "Send me a sample" sends a short voice note to your WhatsApp first. |
-| Technical | Voice reply speed | 0.9 · **1.0** · 1.2 · custom (0.5–2.0). |
-| | Speech files | Download what your settings need, or delete unused files (shown as a ticked list; untick what you want to keep). |
+| Danger | Remove everything (before uninstalling) | Unlinks Pi from your phone and deletes everything it made. Asks first. See [Uninstall](#uninstall). |
+| | Log file | Where the log is (shown, not a setting). |
 
-Speech files are never downloaded just because you look at a choice. When you close the panel and your new settings need files, Pi asks once: download now, or later when first needed.
+Greyed-out rows can still be selected: they say which tick in **Voice notes** turns them on.
 
 Settings are stored in `~/.pi/agent/pi-harness-whatsapp/config.json`.
 
@@ -103,13 +118,13 @@ Commands are handled by the extension and never reach the model. Send `/help` to
 | Command | What it does |
 |---|---|
 | `/help` | Commands and current settings |
-| `/status` | Connection, model, thinking level, context use, voice models |
+| `/status` | Connection, model, thinking level, context use, voice |
 | `/stop` | Stop what Pi is doing |
 | `/compact [focus]` | Compact the context, then report e.g. `✅ Compacted in 18s · 142k → 23k tokens (−84%) · context 89% free` |
 | `/autocompact [on\|off]` | Automatic compaction for this session (Pi still compacts if the context is completely full) |
 | `/model [name]` | Switch the model for this session; lists only models with a login or API key |
 | `/think [level]` | Reasoning level, limited to what the model supports |
-| `/voice [text\|voice\|both\|mirror]` · `/lang` · `/speed [x]` | Reply type, reply language, voice reply speed |
+| `/voice [text\|voice\|both\|mirror]` · `/lang` · `/speed [x]` | Reply type, reply language, voice reply speed. `/voice` and `/speed` work once voice replies are on; voice itself is switched on only in the terminal, since it downloads files. |
 | `/replies` | Switch the reply extras on and off (multi-choice poll) |
 | `/languages` | Show your languages (change them in the terminal) |
 | `/new` | Start a fresh Pi session (the old one stays saved) |
@@ -121,6 +136,18 @@ Commands are handled by the extension and never reach the model. Send `/help` to
 
 ## Voice
 
+Voice is optional and **off by default**. In `/whatsapp` → **Voice notes**, tick what you want:
+
+- **Understand voice notes** (speech-to-text, 1.0 GB): Pi transcribes the voice notes you send. While it's off, a voice note gets "🎤 Voice notes are off. Please type your message." and never reaches the model; in a group, only a voice note that replies to Pi gets that answer.
+- **Reply with voice notes** (text-to-speech, 0.6 GB): Pi can answer with voice notes; **Reply type**, the voices and the speed then become available. While it's off, Pi always answers with text.
+
+Downloads and deletions happen when you leave that menu:
+- **A part you ticked** whose files aren't there yet: Pi asks "Download now (recommended)" or "When first needed". "When first needed" downloads with the first voice note (the chat is told while it waits).
+- **A part you unticked:** Pi asks, e.g. "You set speech-to-text for removal. 828 MB will be freed." Yes deletes the files; No puts the tick back. The shared engine stays as long as the other part needs it.
+- **"Delete all speech files"** unticks both, and asks the same way.
+
+You don't have to untick anything to stop voice replies for a while: set **Reply type** to text.
+
 Voice notes are transcribed on your machine and given to Pi with a label, e.g. `[WhatsApp · Name · voice note · your reply is spoken to Name] …`. When the reply will be spoken, the model is told so, and writes plain speech. Long answers are read in full as several voice notes (up to ~10 minutes; anything longer also comes as text). Answers that are mostly code come as text too, since code can't be read aloud. With **Mirror me**, Pi answers in the language you used, and the voice reply uses that language's voice.
 
 Supported languages: **English, Turkish, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Russian, Ukrainian, Arabic, Hindi, Swedish and Finnish**. Pi understands and speaks all of them with the same two models, so adding a language downloads nothing.
@@ -131,7 +158,7 @@ Supported languages: **English, Turkish, German, French, Spanish, Italian, Portu
 | Speaking replies | [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) by Supertone (10 voices) | 401 MB |
 | Running both | Intel's OpenVINO for Node | 202 MB |
 
-Everything downloads the first time it's needed, and the chat is told while it waits. If you change languages, voices or the reply type in `/whatsapp`, Pi asks when you close the panel whether to download the new files now. Models are unloaded after 10 minutes without voice work, so idle RAM use is zero. While voice notes are being handled, Pi used about 3.4 GB of RAM in total in the test below.
+Models are unloaded after 10 minutes without voice work, so idle RAM use is zero. While a voice note is handled, Pi needed about 2 GB of RAM to understand it, about 1.2 GB to speak a reply, and about 3.4 GB with both, measured on the machine below.
 
 Measured on an Intel i5-13500, CPU only, on real recordings from Google's [FLEURS](https://huggingface.co/datasets/google/fleurs) dataset: 10 sentences per language, read by real people. Wrong words are counted against the dataset's transcript, ignoring punctuation and capitals; a number written as digits ("18") where the transcript spells it out counts as wrong. For the voice, Supertonic read a short sentence in each language and Whisper listened to it again.
 
@@ -153,18 +180,23 @@ Measured on an Intel i5-13500, CPU only, on real recordings from Google's [FLEUR
 | Swedish | 12 % | 2.9 s | ✓ |
 | Hindi | 31 % | 3.2 s | 1 word off |
 
-Supertonic makes speech about 10× faster than real time, so a 20-second reply is ready in about 2 seconds. Symbols and units are hard for any voice to read ("13°C" is not "13 derece"), so when a reply will be spoken, Pi is told to write everything out as it should be said.
+Supertonic makes speech about 10× faster than real time, so a 20-second reply is ready in about 2 seconds. Symbols and units are hard for any voice to read ("13°C" is not "13 degrees"), so when a reply will be spoken, Pi is told to write everything out as it should be said.
 
-Received files are saved in `~/.pi/agent/pi-harness-whatsapp/inbox/` (kept for 7 days), and Pi is told where they are.
+## Images and files
 
-## Tools for the model
+**To Pi:**
+- **Images** (photos, screenshots) go to the model with their caption, so you can ask "what's wrong in this screenshot?". In a group, an image counts when its caption @mentions Pi, or when you reply to an image and @mention Pi.
+- **Files** (PDFs, documents, logs, archives, videos; up to 50 MB) are saved in `~/.pi/agent/pi-harness-whatsapp/inbox/`, and Pi is told the name, type, size and where it is, so it can open it with its own tools. Received files are deleted after 7 days.
+- **Voice notes** are transcribed when **Understand voice notes** is on; see [Voice](#voice).
 
-These are optional; normal replies never need them. They are visible to the model only while WhatsApp is on, and they only send to allowed contacts.
+**From Pi:** ask for it ("send me the screenshot", "send me report.pdf") and Pi sends images and files from this computer to your chat, up to 60 MB. With **Auto-send tool images** on, every image a tool makes while answering you (e.g. a browser screenshot) is sent without asking.
 
-- `whatsapp_send_image(path, caption?, to?)`
-- `whatsapp_send_file(path, caption?, to?)`
+Pi does this with two tools that the model sees only while WhatsApp is on, and that send only to allowed chats:
 
-There's no voice tool on purpose: when your reply is spoken, Pi's answer itself becomes the voice note, so the model can't send the same thing twice.
+- `whatsapp_send_image(path, caption?, to?)`: a PNG, JPEG, WebP or GIF, shown as a photo
+- `whatsapp_send_file(path, caption?, to?)`: any file, sent as a document
+
+`to` is an allowed contact's name or number; without it, Pi sends to the chat it's answering (or the owner). Normal replies never need these tools. There's no voice tool on purpose: when your reply is spoken, Pi's answer itself becomes the voice note, so the model can't send the same thing twice.
 
 ## Run in the background
 
@@ -178,11 +210,68 @@ Everything lives in `~/.pi/agent/pi-harness-whatsapp/`:
 |---|---|
 | `config.json` | Settings |
 | `auth/` | The WhatsApp login. Keep it private; deleting it means scanning a new QR code. |
-| `models/` | Speech models and the OpenVINO engine that runs them |
+| `models/` | Speech models and the OpenVINO engine that runs them (only while voice is on) |
 | `inbox/` | Files people sent (kept 7 days) |
 | `recents.json` | Recent chat ids and names, for picking contacts (no message text) |
 | `connection.lock` | Which Pi process holds the connection right now |
-| `log/pi-harness-whatsapp.log` | Log: connection events and errors, no message text (unless debug logging is on) |
+| `announce.json` | For a moment around `/new` and `/restart`: which chat to tell that Pi is back |
+| `setup.json` | Only if the installer recorded it: programs installed just for the extension (see [Uninstall](#what-was-installed-for-it)) |
+| `log/pi-harness-whatsapp.log` | Log: connection events and errors, no message text (unless debug logging is on). Rotated at 5 MB into `.log.1`. |
+
+The folder is private: only your user can open it. If you set `PI_HARNESS_WHATSAPP_DIR`, everything is in that folder instead. The extension writes nothing anywhere else, apart from Pi's own files (your sessions and its package list).
+
+## Uninstall
+
+Do it in this order, so nothing is left behind.
+
+1. **Clean up from inside Pi.** Close every other Pi window first. Then run `/whatsapp` → **Danger** → **Remove everything (before uninstalling)…** (or type `/whatsapp remove`) and confirm. Pi:
+   - unlinks itself from your phone (WhatsApp → Settings → Linked devices),
+   - stops any speech-file download that's still running,
+   - deletes `~/.pi/agent/pi-harness-whatsapp/` with everything in it: the WhatsApp login, speech files, settings, allowed chats, recent chats, log and received files,
+   - deletes this extension's copies (and those of the packages it brought along) from npm's download cache, and nothing else there,
+   - asks about each program that was installed just for it, if the installer recorded one (see [What was installed for it](#what-was-installed-for-it)), and removes exactly the packages you say yes to,
+   - and writes nothing more until you quit, even if you keep using Pi.
+2. **If Pi runs as a background service, stop and remove it now** (see [Removing the background service](#removing-the-background-service)); otherwise systemd starts Pi again.
+3. **Quit Pi and remove the code:**
+   ```bash
+   pi uninstall npm:pi-harness-whatsapp
+   ```
+   If you installed it from GitHub, use the source that `pi list` shows (e.g. `pi uninstall git:github.com/mkemalemdar/pi-harness-whatsapp`).
+4. **Tidy up after npm.** npm removes every file, but leaves a few empty folders (like `@types`) in Pi's package folder. This deletes only folders that are empty:
+   ```bash
+   find ~/.pi/agent/npm/node_modules ~/.pi/agent/git -mindepth 1 -type d -empty -delete 2>/dev/null
+   ```
+
+**Check that it's gone:** `pi list` no longer shows it, and `ls ~/.pi/agent/pi-harness-whatsapp` says "No such file or directory".
+
+### Already uninstalled without step 1?
+
+The easiest clean way: install it again (`pi install npm:pi-harness-whatsapp`), start Pi, and do the steps above. "Remove everything" then also cleans up what the first uninstall left.
+
+By hand instead: make sure no Pi is running, and look at `~/.pi/agent/pi-harness-whatsapp/setup.json` first, if it's there, for programs installed for the extension. Then delete the folder: `rm -rf ~/.pi/agent/pi-harness-whatsapp` (if you set `PI_HARNESS_WHATSAPP_DIR` to a folder that holds other things too, delete only the entries listed under [Files](#files)). On your phone, remove Pi under WhatsApp → Settings → Linked devices.
+
+### Removing the background service
+
+Use your unit's name. For a system service, run the same with `sudo` and without `--user`; its file is in `/etc/systemd/system/`.
+```bash
+systemctl --user disable --now pi-whatsapp.service
+rm ~/.config/systemd/user/pi-whatsapp.service
+systemctl --user daemon-reload
+```
+If you turned on lingering only for this service, turn it off again with `loginctl disable-linger`. Remove the tmux session it used with `tmux kill-session -t <name>` if it's still running.
+
+### What was installed for it
+
+The extension itself never installs programs; you or an AI agent install `ffmpeg` (and `tmux` for the background service) when they're missing. Whoever does that can record it in `setup.json` in the data folder, and "Remove everything" then offers to remove it again. [AGENT_INSTALL.md](AGENT_INSTALL.md) has the format, and AI agents installing the extension write it for you.
+
+Removal is careful: with apt, it first does a dry run and keeps everything if removing those packages would also remove anything not on the list (like a program you installed later that needs them). It runs as root or with `sudo` that needs no password; otherwise it shows you the command. With Homebrew it runs `brew uninstall`; with other package managers it shows the command.
+
+### What isn't removed, on purpose
+
+- **Your Pi sessions** (`~/.pi/agent/sessions/`). Chats you had with Pi from WhatsApp are ordinary Pi sessions, and they contain small `pi-harness-whatsapp/session` entries (whether WhatsApp was on). Pi ignores those once the extension is gone; cutting them out would break the sessions. Delete whole sessions in Pi if you don't want them.
+- **Programs nobody recorded** in `setup.json`: if you installed `ffmpeg` or `tmux` yourself just for this, remove them with your package manager (e.g. `sudo apt remove --purge ffmpeg tmux`, then `sudo apt autoremove` for what came with them, after checking its list).
+- **npm's own logs** (`~/.npm/_logs`): npm keeps a log of its last few runs, which can mention the install. They're replaced as npm runs again.
+- **Your package manager's history** (e.g. `/var/log/apt/history.log`, `/var/log/dpkg.log`) notes every install and removal, like it does for every program.
 
 ## Troubleshooting
 
@@ -190,7 +279,8 @@ Everything lives in `~/.pi/agent/pi-harness-whatsapp/`:
 - **"needs a new QR scan":** WhatsApp logged the device out (for example, it was removed from Linked devices). Connection → Show a new QR code.
 - **"in use by Pi #…":** another Pi holds the connection; turn WhatsApp off there.
 - **Messages are ignored:** the sender isn't in Allowed chats. Pi shows a notice in the terminal the first time.
-- **Voice notes fail:** check that `ffmpeg -version` works. The first voice note waits for the speech files to download (about 1.4 GB); a download that stalls for a minute is given up and tried again with the next voice note. On Intel Macs and Windows on ARM, voice notes aren't available.
+- **"Voice notes are off":** tick **Understand voice notes** in `/whatsapp` → Voice notes.
+- **Voice notes fail:** check that `ffmpeg -version` works. With "When first needed", the first voice note waits for the download (up to 1.4 GB); a download that drops continues where it stopped, and one that stalls for a minute is given up and tried again with the next voice note. On Intel Macs and Windows on ARM, voice notes aren't available.
 - **More detail:** set `PI_HARNESS_WHATSAPP_DEBUG=1` before starting Pi, and check the log. Debug logging also writes WhatsApp's own internal messages, which can contain message content, so turn it off again afterwards.
 
 ## Development

package/index.ts

@@ -22,7 +22,7 @@ export default function piHarnessWhatsApp(pi: ExtensionAPI) {
 	controller.onToolsChanged = (on) => setToolsActive(pi, on);
 
 	pi.registerCommand("whatsapp", {
-		description: "WhatsApp settings: on/off, replies, voice, languages, contacts, connection",
+		description: "WhatsApp settings: on/off, replies, voice, languages, contacts, connection. /whatsapp remove: remove everything before uninstalling",
 		handler: async (args, ctx) => {
 			// Internal: "/new" from WhatsApp dispatches this so Pi gives us a real command context.
 			if (args.trim() === NEW_SESSION_ARG) {
@@ -30,6 +30,11 @@ export default function piHarnessWhatsApp(pi: ExtensionAPI) {
 				await ctx.newSession();
 				return;
 			}
+			// Same as Connection → Remove everything; works without the panel (e.g. for an AI agent over RPC).
+			if (args.trim() === "remove") {
+				await controller.removeEverything(ctx);
+				return;
+			}
 			await controller.openSettings(ctx);
 		},
 	});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-harness-whatsapp",
-  "version": "0.1.0",
-  "description": "Talk to the Pi coding agent from WhatsApp: QR pairing, automatic replies, voice notes in and out (local Whisper + Supertonic on OpenVINO), group chats, poll menus to control Pi.",
+  "version": "0.1.2",
+  "description": "Talk to Pi from WhatsApp: images, files and optional voice notes in and out, automatic replies, group chats, poll menus to control Pi.",
   "type": "module",
   "license": "MIT",
   "author": "mkemalemdar",

package/src/bridge.ts

@@ -12,7 +12,7 @@ import { contactLabel } from "./contacts-flow.ts";
 import { languageLabel } from "./languages.ts";
 import { createLogger } from "./log.ts";
 import { formatActivity, formatTouchedFiles, RunReport } from "./run-report.ts";
-import { type Contact, MIRROR, type SettingsStore } from "./settings.ts";
+import { type Contact, MIRROR, replyMode, type SettingsStore } from "./settings.ts";
 import type { WhatsAppConnection } from "./wa/connection.ts";
 import { type Access, addressedToSelf, checkAccess, type InboundMessage, parseMessage, SeenIds, senderIdentity } from "./wa/inbound.ts";
 import { contactJid, isLidJid, jidUser, phoneJid } from "./wa/jid.ts";
@@ -33,6 +33,8 @@ const BUSY_POLL_MS = 500;
 /** Group messages not meant for Pi that are kept as context for when it is addressed. */
 const GROUP_CONTEXT_MESSAGES = 20;
 const CUT_OFF_NOTICE = "⚠️ The model hit its output limit before writing an answer. Try again, or raise the model's output limit.";
+/** The answer to a voice note while "Understand voice notes" is off. */
+export const VOICE_OFF_NOTICE = "🎤 Voice notes are off. Please type your message.";
 
 type PromptContent = string | Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
 
@@ -214,9 +216,18 @@ export class Bridge {
 			return;
 		}
 
+		// Voice notes while "Understand voice notes" is off: nothing reaches the model and nothing downloads.
+		const voiceOff = message.kind === "audio" && !this.deps.settings.get().voice.understand;
 		if (message.isGroup) {
 			// WhatsApp writes a mention as "@<number>"; the model reads "@Pi" better.
 			message.text = this.namePi(message.text);
+			if (voiceOff) {
+				// In a group, only a voice note that replies to Pi gets the answer; others are just context.
+				const { repliedTo } = addressedToSelf(message, this.deps.connection.selfIds(), (id) => this.deps.connection.isOwnMessage(id));
+				if (repliedTo) await this.deps.queue.sendText(message.chatJid, VOICE_OFF_NOTICE);
+				else this.rememberGroupMessage(message);
+				return;
+			}
 			if (!this.isForPi(message)) {
 				// Not meant for Pi: keep it as context for the next time Pi is addressed.
 				this.rememberGroupMessage(message);
@@ -230,6 +241,13 @@ export class Bridge {
 		await this.forwardToPi(message, access);
 	}
 
+	/** Voice notes while "Understand voice notes" is off get a short answer instead of reaching Pi. */
+	private async answeredVoiceOff(message: InboundMessage): Promise<boolean> {
+		if (message.kind !== "audio" || this.deps.settings.get().voice.understand) return false;
+		await this.deps.queue.sendText(message.chatJid, VOICE_OFF_NOTICE);
+		return true;
+	}
+
 	/** In a group: does this message ask Pi something (per "In groups, answer")? Commands and menu answers always do. */
 	private isForPi(message: InboundMessage): boolean {
 		const mode = this.deps.settings.get().groupReplies;
@@ -391,7 +409,7 @@ export class Bridge {
 		const from = message.isGroup ? `WhatsApp group "${access.contact?.name ?? "group"}" · ${sender}` : `WhatsApp · ${sender}`;
 		const to = message.isGroup ? "the group" : sender;
 		return (voiceTag) => {
-			const mode = this.deps.settings.get().voiceMode;
+			const mode = replyMode(this.deps.settings.get());
 			const spoken = mode === "voice" || mode === "voice+text" || (mode === "mirror" && !!voiceTag);
 			return `[${[from, voiceTag, spoken ? `your reply is spoken to ${to}` : `your reply goes to ${to}`].filter(Boolean).join(" · ")}]`;
 		};
@@ -399,6 +417,7 @@ export class Bridge {
 
 	private async forwardToPi(message: InboundMessage, access: Access): Promise<void> {
 		if (!this.deps.getCtx()) return;
+		if (await this.answeredVoiceOff(message)) return;
 		void this.deps.connection.presence(message.chatJid, "composing");
 		const header = this.header(message, access);
 		const context = message.isGroup ? this.takeGroupContext(message, access) : undefined;
@@ -482,8 +501,14 @@ export class Bridge {
 			"- Name is talking to you directly from their phone. Answer Name directly, as \"you\" — don't describe their message to someone else or ask what to reply to them.",
 			"- Your final answer is sent to them automatically. Don't use a tool just to reply.",
 			"- Keep answers short and chat-friendly. Summarize long code, and write files to disk instead.",
-			"- Voice notes arrive already transcribed, e.g. `[WhatsApp · Name · voice note · your reply is spoken to Name]`. Transcripts can contain misheard words.",
-			"- When the label says \"your reply is spoken\", your answer becomes voice notes automatically (long answers are split into parts). Write it exactly as it should be said: no symbols, units or abbreviations (\"13 derece\", not \"13°C\"; \"yüzde 40\", not \"%40\"; \"25 kilometers\", not \"25 km\"), and no code, tables, links or emoji.",
+			...(settings.voice.understand
+				? ["- Voice notes arrive already transcribed, e.g. `[WhatsApp · Name · voice note · your reply goes to Name]`. Transcripts can contain misheard words."]
+				: []),
+			...(settings.voice.reply
+				? [
+						"- When the label says \"your reply is spoken\", your answer becomes voice notes automatically (long answers are split into parts). Write it exactly as it should be said: no symbols, units or abbreviations (\"13 degrees\", not \"13°C\"; \"40 percent\", not \"40%\"; \"25 kilometers\", not \"25 km\"), and no code, tables, links or emoji.",
+					]
+				: []),
 			"- Group labels look like `[WhatsApp group \"Team\" · Name · your reply goes to the group]`: answer the group. You only get group messages that mention or reply to you; the ones before it may come first as `earlier messages, for context`. Use them to understand the question, but answer only the last message.",
 			`- ${language}`,
 		].join("\n");