Add transcription hook

[AlexanderYastrebov]

Before Submitting This PR

Please confirm you have done the following:

• I have searched existing issues and pull requests (including closed ones) to ensure this isn't a duplicate
• I have read CONTRIBUTING.md

If this is a feature or change that was previously closed/rejected:

• I have explained in the description below why this should be reconsidered
• I have gathered community feedback (link to discussion below)

Human Written Description

Add support for transcription hook - an executable script in app's data directory.

If transcription_hook file exists, Handy runs it passing transcription text via stdin and
uses script stdout as a transcription result.

This approach is a flexible extension point for advanced users
(which nowadays means with access to coding LLM) akin to git hooks.

Here are some possible scenarios:

• simple transcription modifications
• a pipeline involving LLM processing, language detection and translation
• custom paste method (as Handy does nothing if transcription is empty)
• conditional processing based on the active application waiting for the input
• quote clipboard content and append transcription

Related Issues/Discussions

See related:

• Transcript post-processing #168
• Idea: Support mapping pre-defined phrases to snippets of text #162
• Feature: Interleave clipboard context with transcription output #916
• Feature Request: "Plugin" menu to improve adaptability and reduce PR bloat #911
• Add an "Append Newline" option to advanced settings. #834
• Integrated local LLM support for post-processing — reduce latency #847
• Period-Option #833
• Regarding Punctuation and Formatting #662
• Custom Phrases #601
• Checkbox to disable capitalization #335
• Add general stdin/stdout command filter for transcription post-processing #739
• Add "external script" paste method #638
• feat: add text replacements feature #455
• [FR] Simple text post-processing with regexes #157

Community Feedback

Testing

Build and ran Handy with both example scripts.

Screenshots/Videos (if applicable)

AI Assistance

• No AI was used in this PR
• AI was used (please describe below)

If AI was used:

• Tools used: Copilot with Claude Sonnet 4.5
• How extensively: Handle Command stdin in Rust and compose hook example that uses Apple Script.

[AlexanderYastrebov]

A couple more examples from discussions to keep README small:

Example quoting clipboard content and appending transcription:

#!/bin/bash
clipboard=$(pbpaste)
if [ -n "$clipboard" ]; then
    echo "> $clipboard"
    echo
fi
cat

Example expanding voice commands to actual commands and emoji shortcuts:

#!/usr/bin/env python3
import sys

text = sys.stdin.read()

# Command expansions and emoji shortcuts
replacements = {
    # Commands
    "run unit tests": "pnpm run tests",
    "run tests": "pnpm run tests",
    "run dev": "pnpm run dev",
    "run build": "pnpm run build",
    "git status": "git status",
    "git commit": "git commit",
    # Emojis
    "grin emoji": ":grin:",
    "smile emoji": ":smile:",
    "thumbs up emoji": ":thumbsup:",
    "heart emoji": ":heart:",
    "fire emoji": ":fire:",
    "rocket emoji": ":rocket:",
    "eyes emoji": ":eyes:",
    "party emoji": ":tada:",
}

# Strip punctuation for lookup
lookup_text = text.strip().lower().rstrip('.,!?;:')
sys.stdout.write(replacements.get(lookup_text, text))

[AlexanderYastrebov]

As a possible future extension I have the following idea: Handy supports multiple hotkeys and the hotkey used to capture transcription is passed to the script via environment variable or an argument - this way script may perform different actions based on the hotkey.

[AlexanderYastrebov]

If this is moving forward it might be better to reserve dedicated folder hooks/post_transcription