@superwhisper/pi

Superwhisper voice integration extension for Pi.

Get voice notifications when your AI coding tasks complete, and respond with your voice. Your voice response is sent back to Pi as the next prompt, creating a hands-free coding loop.

Requirements

• Pi (@mariozechner/pi-coding-agent) installed (npm i -g @mariozechner/pi-coding-agent)
• Superwhisper app for macOS

Installation

Install with pi's package manager. Pick whichever source you prefer — both work the same once installed.

From npm

pi install npm:@superwhisper/pi

From git

pi install git:github.com/superultrainc/pi-superwhisper

Pi clones into ~/.pi/agent/git/github.com/superultrainc/pi-superwhisper and runs npm install automatically. Pin a version with @<ref> (e.g. ...pi-superwhisper@v1.0.0).

From a local clone

git clone https://github.com/superultrainc/pi-superwhisper.git
pi install ./pi-superwhisper

Pi loads .ts extensions directly via jiti, so there's no build step.

Restart pi to activate.

How It Works

You speak → Pi works → Extension notifies Superwhisper → You speak back → loop

1. Task completes → Pi fires agent_end with stopReason: "stop"
2. Extension extracts the response → reads the last assistant text content
3. Extension notifies Superwhisper → writes message to temp file, opens deeplink
4. Superwhisper shows notification → displays summary with voice recording UI
5. You speak your response → Superwhisper transcribes and writes to response file
6. Extension reads response → polls the response file, sends back to Pi via pi.sendUserMessage
7. Pi continues → processes your voice input as the next instruction

Events

Pi Event	Superwhisper Status	Description
agent_end (stop)	completed	Task finished

Pi has no built-in permission popups or elicitation system, so only end-of-turn completions are surfaced today. If you wire up your own permission gate via tool_call blocking, file an issue and we'll plumb it through.

Controlling Superwhisper During a Session

You can ask the agent to enable or disable Superwhisper voice notifications at any time during a session. The extension exposes a superwhisper_toggle tool the agent will use automatically when instructed.

Disable Superwhisper for the current session:

"Disable Superwhisper" / "Turn off voice notifications" / "Stop Superwhisper"

Re-enable Superwhisper for the current session:

"Enable Superwhisper" / "Turn voice notifications back on" / "Re-enable Superwhisper"

The toggle is session-scoped — it only affects the current Pi session and resets when you start a new one.

Development

npm install
npm run typecheck

Local Testing

See From a local clone above for the standard pi install ./path flow. For tighter iteration on a single file, symlink it into pi's user extensions directory so edits are picked up on the next pi restart without re-running pi install:

mkdir -p ~/.pi/agent/extensions
ln -s "$PWD/extensions/superwhisper.ts" ~/.pi/agent/extensions/superwhisper.ts

Environment Variables

Variable	Default	Description
SUPERWHISPER_DEBUG	unset	Set to 1 to write debug logs to /tmp/superwhisper-agent/debug.log
SUPERWHISPER_SCHEME	auto	Override deeplink scheme (superwhisper vs superwhisper-debug)

Project Structure

extensions/
  superwhisper.ts  # Extension entry — pi loads this directly
  constants.ts     # Constants and shared types
  inbox.ts         # Inbox payload writes
  message.ts       # Pi AgentMessage helpers (extract text, summary, end-turn)
  poll.ts          # Response file polling

License

MIT