git:20260908.a505983 to git:20260908.0f63dc1

21 added, 8 removed. Audit A to A.

---

name: voice-notes

description: Handle a voice note or audio attachment the hermit cannot read, and set up transcription when the operator wants it. Activates when a channel message carries an audio attachment (Telegram voice message, Discord voice-message.ogg), or on "can you understand voice notes", "transcribe my voice message", "set up voice notes".

---

# Voice Notes

- The channel plugin downloads an audio attachment on its own; the model cannot read audio. Transcription is an operator choice, not a shipped default: it needs a speech-to-text tool where the hermit runs, and possibly a provider key. The recipe lives in `docs/voice-notes.md` beside this plugin; this skill routes, it does not repeat it.

+ The channel plugin downloads the audio; the model cannot read it. Transcription is an operator choice, not a shipped default. The recipe lives in `${CLAUDE_PLUGIN_ROOT}/docs/voice-notes.md`; route to it, do not repeat it.

+ ## Step 0 — Channel reply

+ If this skill was invoked from a channel-arrived message (the inbound prompt contains a `<channel source="...">` tag), reply via that channel's reply tool. Otherwise emit to conversation. On a channel-tagged turn, step 1's bounded ask also queues a durable micro-proposal entry via `proposal.ts queue-micro` (see `channel-responder` § Channel-safe ask bridge), so the answer re-enters this skill in a later turn instead of stranding the setup half-done.

## An audio attachment arrives

- With no standing role covering it, reply in channel voice: you received a voice note, you cannot listen to it yet, and you can set that up if they want. Do not guess at the content or ask them to retype it unless they decline setup.

+ With no standing role covering it, reply: you received a voice note, you cannot listen to it yet, and you can set that up if they want. Do not guess at the content or ask them to retype it unless they decline setup.

## The operator asks to set it up

- Walk them through `docs/voice-notes.md` from chat:

+ Read `.claude-code-hermit/config.json`: no channel with `enabled !== false` means no audio ever arrives (the Claude app transcribes before sending), so say so and stop.

- 1. Settle one thing over the reply tool, then continue when the answer arrives: should the audio stay on this machine, or is uploading it to a transcription provider acceptable? Self-hosted is the default. Then read only the matching section of the doc, self-hosted or hosted, plus step 2.

- 2. Install: in Docker, delegate to `/claude-code-hermit:docker-customize` with the tool the doc names. On tmux the hermit runs on the host, so name the host install for the operator rather than running it yourself. A hosted provider needs its key in `.env`; never put a key in the role text or `config.json`.

- 3. Role: once the tool is in place, save the standing role from the doc through the ordinary "remember" path, substituting the command they ended up with. Offer "for this channel" if they only want it in one chat.

- 4. Verify: ask them to send a voice note and confirm the reply addresses what they said.

+ Otherwise walk them through the doc from chat:

- On a prompting permission mode, mention the allow rule from the doc after the first run raises an approval.

+ 1. Settle one thing: should the audio stay on this machine, or is uploading it to a transcription provider acceptable? Self-hosted is the default. Then read only the matching doc section, self-hosted or hosted, plus its step 2.

+ **Channel-tagged turn:** send the question via the reply tool, queue the bridge entry below, and stop. The answer comes back as a `--answer self-hosted` / `--answer hosted` re-entry, which skips the ask and resumes here.

+ ```bash

+ bun ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.ts queue-micro .claude-code-hermit <<'HERMIT_MP'

+ {"tier":1,"question":"Voice notes: should the audio stay on this machine, or is sending it to a transcription provider acceptable?","options":["self-hosted","hosted"],"on_resolve":"/claude-code-hermit:voice-notes setup --answer {answer}"}

+ HERMIT_MP

+ ```

+ 2. Install: read `runtime_mode` from `.claude-code-hermit/state/runtime.json`. On `docker`, delegate to `/claude-code-hermit:docker-customize` with the tool the doc names; otherwise name the host install for the operator rather than running it yourself. A hosted provider needs its key in `.env`, never in the role text or `config.json`.

+ 3. Role: save the standing role from the doc through the ordinary "remember" path, substituting the command they ended up with. Offer "for this channel" if they only want it in one chat.

+ 4. Verify: have them send a voice note and confirm the reply addresses what they said.

+ On a prompting permission mode, mention the doc's allow rules after the first run raises an approval.