@matheusbbarni/pi-handy

A microphone button in Pi that triggers Handy transcription.

A compact control sits above the editor. The mic toggles recording. The model name opens Handy's tray-style menu: copy last transcript, then recent transcripts.

🎤  Canary 180M Flash
⏺ Recording

Features

• Adds a microphone widget above the editor
• Shows the selected Handy model next to the mic
• Click the mic in the fullscreen TUI; Cmd/Ctrl-click it in the inline TUI
• Click the model name for Copy last transcript and history
• /handy and Ctrl+Shift+M toggle from the keyboard
• Talks to a running Handy instance with --toggle-transcription
• Launches Handy hidden if it is not already running, then waits for a second click to record
• Reads transcripts from Handy's local history database
• Leaves paste and auto-submit to Handy

Install

Handy itself has to be installed and granted microphone plus accessibility permissions.

pi install npm:@matheusbbarni/pi-handy

From this repo:

pi -e ./pi-handy

Or as a local package:

pi install ./pi-handy

[!TIP] If Pi is already open, run /reload.

Usage

| Action | Result | | --- | --- | | Click 🎤 | Toggle Handy recording | | Click the model name | Open Copy last transcript and history | | Ctrl+Shift+M | Toggle recording | | /handy | Toggle recording | | /handy start | Start recording if idle | | /handy stop | Stop recording if active | | /handy cancel | Cancel the current Handy operation | | /handy post-process | Toggle recording with Handy post-processing | | /handy copy | Copy the last transcript | | /handy history | Pick a transcript to copy | | /handy menu | Same menu as clicking the model name | | /handy status | Show idle/recording and the selected model |

Handy's own shortcut still works. On this Mac that is Option+Space.

The widget only tracks toggles that went through Pi. If you start or stop Handy from the global shortcut, the button can be stale until the next Pi toggle.

Handy binary

The extension looks for Handy in this order:

1. HANDY_BIN
2. handy on PATH
3. /Applications/Handy.app/Contents/MacOS/handy
4. ~/Applications/Handy.app/Contents/MacOS/handy

export HANDY_BIN=/Applications/Handy.app/Contents/MacOS/handy

Handy must already have a model installed. This package does not download models or open the microphone itself.

How it works

Pi does not record audio. It asks the running Handy app to toggle transcription, the same way the Raycast Handy extension and Linux custom shortcuts do.

When Handy finishes, it pastes into the focused window. Keep Pi focused if you want the transcript in the editor.

Copy last transcript and the history menu read Handy's local history.db. Picking an item copies that text to the clipboard.

Development

npm install
npm test
npm run typecheck