Transforms
Relevant source files
The following files were used as context for generating this wiki page:
Transforms are a system-wide feature in MacParakeet that allows users to perform LLM-powered text rewrites on selected text within any macOS application. By using global hotkeys, the system captures the current text selection, processes it through a configured Large Language Model (LLM) provider, and replaces the original selection with the transformed output in-place. This feature is designed to provide high-performance text manipulation—such as polishing, distilling, or deciding—without requiring the user to leave their active application.
Sources: spec/adr/022-transforms-system-wide-rewrite.md:9-14, plans/completed/2026-05-transforms-phase-2-productize.md:21-25
Architecture and Components
The Transforms system is built as a vertical slice across the application, utilizing accessibility (AX) APIs and clipboard fallbacks for text manipulation. The architecture is centered around a dedicated executor and a hotkey registry that manages the lifecycle of a transform operation.
Core Components
- TransformExecutor: Manages the end-to-end execution flow, including selection capture, LLM streaming, and replacement. It handles cooperative cancellation and ensures state restoration (like clipboard contents) if a process is abandoned.
- TransformsHotkeyRegistry: An actor that manages a process-wide event tap to monitor global keyboard shortcuts. It maintains a dispatch table mapping
KeyboardShortcutobjects to specificPrompt.IDs. - SelectionCaptureService: Responsible for retrieving text from the active application. It prioritizes macOS Accessibility (AX) APIs but falls back to a 250ms clipboard "hijack" with snapshot/restore capabilities if AX is unavailable.
- SelectionReplacementService: Writes the transformed text back to the host application using AX-write or simulated
Cmd+Vpaste-back if necessary.
Sources: plans/completed/2026-05-transforms-phase-2-productize.md:46-56, spec/adr/022-transforms-system-wide-rewrite.md:84-100
Execution Flow
The following sequence diagram illustrates the lifecycle of a Transform operation from the moment a hotkey is pressed until the text is replaced.
Data Model and Persistence
Transforms are persisted within the existing prompts table in the application database, specifically identified by the category == .transform attribute. This allows Transforms to share the management infrastructure used by transcript summaries while maintaining specific metadata for hotkey triggers.
Table Extensions
The following columns were added to the prompts table to support the productized Transforms feature:
| Column | Type | Description |
|---|---|---|
keyboardShortcut | TEXT (JSON) | Encodes the modifiers, keyCode, and display label for the trigger shortcut. |
runningLabel | TEXT | Optional custom label for the progress pill (e.g., "Polishing..."). |
Sources: spec/adr/022-transforms-system-wide-rewrite.md:38-45, plans/completed/2026-05-transforms-phase-2-productize.md:154-162
Built-in Transforms
The system ships with three default transforms designed for high-frequency workflows:
| Name | Default Shortcut | Purpose |
|---|---|---|
| Polish | ⌃⌥ + 1 | Tone-preserving clarity and conciseness. |
| Distill | ⌃⌥ + 2 | Compressing rambling text while preserving actionable meaning. |
| Decide | ⌃⌥ + 3 | Rewriting discussion into decision-ready notes. |
Sources: plans/completed/2026-05-transforms-phase-2-productize.md:183-195, spec/adr/022-transforms-system-wide-rewrite.md:105-115
Capture and Replacement Logic
The system employs a multi-tiered approach to interact with host applications, ensuring compatibility even when Accessibility support is limited.
Capture Strategy
- AX-First: Queries
AXUIElementCreateSystemWideforkAXFocusedUIElementAttribute. - Clipboard Fallback: If AX fails, the system snapshots the current clipboard, simulates
Cmd+C, and polls for changes for up to 250ms. - Restoration: After the operation completes or if it is cancelled, the original clipboard content is restored.
Sources: spec/adr/022-transforms-system-wide-rewrite.md:65-80, plans/completed/2026-05-transforms-phase-2-productize.md:46-50
Replacement Logic
The logic for writing text back follows a similar hierarchy:
Hotkey Registry and Collision Management
The TransformsHotkeyRegistry serves as the gatekeeper for all transform triggers. It implements strict validation to prevent conflicts with system functions or other MacParakeet features.
- Modifier Requirement: All shortcuts must include at least one modifier key (e.g., Option, Control).
- Conflict Prevention: The registry explicitly blocks collisions with the Dictation hotkey and the Meeting-toggle hotkey.
- Dead-Key Protection: macOS "dead-key" combinations (e.g.,
Opt+e,Opt+u) are blocked to prevent interference with character input. - Single Event Tap: A single process-wide event tap is used to monitor keys, ensuring that at most one Transform runs at a time.
Sources: spec/adr/022-transforms-system-wide-rewrite.md:118-130, plans/completed/2026-05-transforms-phase-2-productize.md:204-215
Command Line Interface (CLI)
Transforms are exposed through the macparakeet-cli as a first-class subcommand tree. This allows for headless execution, testing, and provisioning by automation agents.
| Subcommand | Purpose |
|---|---|
list | Lists all transforms with ID, name, and hotkey. |
run <id> | Runs a transform against a provided file or stdin. |
create | Provision a new transform with custom prompts and shortcuts. |
delete | Remove a non-built-in transform. |
Sources: plans/completed/2026-05-transforms-phase-2-productize.md:223-242, spec/adr/022-transforms-system-wide-rewrite.md:148-160
User Interface and Progress
The UI for Transforms consists of a dedicated sidebar tab and a floating progress pill.
- Transforms Tab: A management surface for viewing, editing, and creating transforms. It includes a "Hero card" for onboarding and a grid view of bound shortcuts.
- Progress Pill: A bottom-anchored capsule containing a "rhodonea" (5-petal rose) loader. It provides visual feedback during LLM generation and surfaces a "Still polishing..." label if the process exceeds a 5-second threshold.
- Escape Hatch: MacParakeet relies on the standard macOS
Cmd+Z(Undo) as the primary escape hatch for reversing unwanted text replacements.
Sources: plans/completed/2026-05-transforms-phase-2-productize.md:102-130, spec/adr/022-transforms-system-wide-rewrite.md:200-205
Summary
The Transforms system represents a high-performance, system-wide implementation of LLM-assisted text editing. By leveraging a robust combination of AX APIs and clipboard fallbacks, it provides a seamless user experience for rewriting text across the macOS environment. Managed through the Prompt Library and a centralized Hotkey Registry, it balances user customization with enterprise-grade reliability and performance.