Push-to-talk voice chat

You talk with the user out loud. Each turn: write your line to a scratch file, then run the bundled ptt tool to speak it and (optionally) capture the user's spoken reply.

Running a turn

The tool is ptt — on PATH after scripts/install.sh. (In a Claude Code plugin install it also lives at ${CLAUDE_PLUGIN_ROOT}/bin/ptt; use that absolute path if plain ptt isn't found.) Three subcommands:

• speak <sayfile> — speak the text in <sayfile>. No microphone. No special permissions.
• listen — push-to-talk capture → prints the transcript to stdout.
• chat <sayfile> — speak then listen (one full back-and-forth turn).

listen and chat read the keyboard directly (evdev), so they MUST run under the input group:

sg input -c 'ptt chat /abs/path/to/say.txt'

speak does not need sg:

ptt speak /abs/path/to/say.txt

Step by step

1. Write your spoken line to a scratch file using your file-write tool (this avoids all shell-escaping of quotes/newlines). Use a temp path you control, e.g. the session scratchpad, or /tmp/ptt-say.txt. Pass that path as the <sayfile> argument. Do NOT try to inline the text on the command line.
2. To speak AND get a reply, run chat under sg input. To just make a statement and keep working (no reply expected), run speak (no sg).
3. Give the shell call a long timeout (e.g. 10 minutes) — the user may take a while to respond, and TTS has startup latency.

Push-to-talk, tell the user once

• Hold the PTT key (default Right Alt) and speak; release to send.
• Tell them to keep holding through pauses — releasing mid-thought cuts them off.
• They do NOT hold the key while you're talking, so there's no echo.

Style for spoken lines

• Keep lines conversational and moderate length — this is speech, not a document. Split a long update into a few speak calls rather than one wall of text. TTS can have noticeable startup latency per line.
• Spell out things TTS mangles (URLs, code) phonetically: "example dot com", "H T M L".
• No markdown, bullets, or emoji in the say-file — it's read aloud verbatim.

Exit codes (from the tool, on stderr)

• 3 — no readable keyboard: the user isn't in the input group. Tell them to run sudo usermod -aG input $USER (then relogin, or you re-run under sg).
• 4 — no key press within the timeout: the user didn't hold the key. Just try the turn again, or ask if they're there.

First-run

If the tool errors about missing modules/endpoints, the plugin may not be set up. Run scripts/install.sh from the repo root (in Claude Code: the setup skill, /push-to-talk:setup), and make sure ~/.config/claude-ptt/config.env has the user's TTS/STT URLs.