Skip to content
Documentation
Examples

Examples

Looking for a quick overview? Start with the Use Cases section for narrative walkthroughs, then come back here for detailed setup and configuration.

Voxclip ships with ready-made scripts for voice-prompt workflows with terminal coding agents and system-wide voice-to-text. All processing runs locally — no cloud APIs, no data leaves your machine.

The full script sources live in the examples/ directory.

Coding Agents

Use your voice to prompt terminal coding agents like claude, aider, codex, opencode, or crush.

Interactive mode (vprompt_interactive)

Record in a split pane or tab, then paste the transcript into your agent session.

source examples/vprompt-interactive.sh

vprompt_interactive
# Recording starts immediately — speak, then press Enter when done.
# Transcript is copied to your clipboard.
# Paste with Cmd+V (macOS) or Ctrl+Shift+V (terminal).

To load automatically, add to your ~/.bashrc or ~/.zshrc:

source /path/to/voxclip/examples/vprompt-interactive.sh

Example mixed text + voice flow:

  1. Type context in the agent prompt.
  2. Capture a voice chunk with vprompt_interactive in another pane/tab.
  3. Paste transcript into the agent prompt.
  4. Type final constraints and submit.

One-shot invocation (vprompt)

Use command substitution to pass a voice prompt directly:

source examples/vprompt.sh

claude "$(vprompt)"
aider --message "$(vprompt)"

Recording lasts for a fixed duration (default 10s, configurable via VPROMPT_DURATION). No TTY is required, so it works inside $(...) where stdin is not a terminal.

export VPROMPT_DURATION=15s

Auto-paste hotkey (vpaste.sh)

Record your voice for a fixed duration, transcribe locally, and simulate a paste keystroke into whatever window was active. Fully hands-free — no terminal window opens, no prompts appear.

What happens:

  1. Press a global keyboard shortcut.
  2. Your microphone records for N seconds (default 8s).
  3. Voxclip transcribes the audio locally.
  4. The transcript is copied to your clipboard and pasted automatically.
  1. Open Shortcuts.app and create a new shortcut named “Voice Prompt”.
  2. Add the action Run Shell Script, set shell to /bin/zsh, and paste the contents of vpaste.sh.
  3. Go to System Settings > Keyboard > Keyboard Shortcuts > Services and assign a key combination (for example Ctrl+Alt+Cmd+V).

Avoid Ctrl+Shift+V and Cmd+Shift+V on macOS where editors and terminals often intercept those combos.

macOS permissions (required for both hotkey scripts)

vpaste.sh and vpaste-toggle.sh rely on macOS privacy permissions for recording and simulated paste.

  1. Run the shortcut once from Shortcuts.app (click the Play button) to trigger permission prompts.
  2. Allow Microphone access for Shortcuts.
  3. Enable Accessibility for Shortcuts so osascript can send Cmd+V.
  4. Enable Automation for Shortcuts to control System Events.

If you test from Terminal/iTerm instead of Shortcuts, grant the same permissions to that terminal app.

Configuration:

export VPROMPT_DURATION=12s

Requirements:

  • macOS: osascript is built-in and voxclip copies via pbcopy; grant Microphone + Accessibility + Automation permissions as described above.
  • Linux X11: xclip for clipboard writes and xdotool for simulating the paste keystroke (apt install xclip xdotool / dnf install xclip xdotool).
  • Linux Wayland: wl-copy for clipboard writes and wtype for simulating the paste keystroke (apt install wl-clipboard wtype).

Why both steps are needed: these hotkey scripts only simulate the paste keypress; they do not place text on the clipboard themselves. voxclip performs the copy operation, then the script triggers paste into the active window.

General Use Cases

System-wide voice-to-text shortcut

Use vpaste.sh or vpaste-toggle.sh as a global hotkey to dictate into any application — browser, email, chat, notes — without cloud APIs. All processing runs locally on your machine.

Toggle-style hotkey (vpaste-toggle.sh)

Press the hotkey once to start recording, press it again to stop. No fixed duration needed.

How it works:

  1. First press: starts voxclip --pid-file ... which begins recording and blocks.
  2. Second press: detects the running instance via the PID file, sends SIGUSR1, and exits immediately.
  3. The first instance stops recording, transcribes, copies to clipboard, and simulates a paste keystroke.
  1. Open Shortcuts.app and create a new shortcut.
  2. Add the action Run Shell Script, set shell to /bin/zsh, and paste the contents of vpaste-toggle.sh.
  3. Assign a keyboard shortcut in System Settings > Keyboard > Keyboard Shortcuts > Services.

Before binding a silent hotkey, pre-download the model once so first use does not block on background download:

voxclip setup --model tiny

Configuration:

Edit your local vpaste-toggle copy and adjust the voxclip flags directly (for example --model, --language, or --input).

Requirements: same as vpaste.sh above.

Troubleshooting hotkey scripts

Run from Terminal to surface hidden errors while iterating:

~/.local/bin/vpaste
~/.local/bin/vpaste-toggle

Common failure modes:

  • System Events got an error ... not allowed to send keystrokes (1002) -> enable macOS Accessibility permission.
  • Transcript copies but does not paste on Linux -> install xdotool (X11) or wtype (Wayland).
  • Wrong microphone -> run voxclip devices and pass --input in your local script copy.
  • Toggle script appears stuck after interrupted run -> remove stale PID file: rm -f /tmp/voxclip-toggle.pid.

Voice notes (vnote.sh)

Append timestamped transcriptions to a file:

sh examples/vnote.sh

Each note is appended as a single line:

2026-02-25 14:30  Refactor the download package to use context timeouts.
2026-02-25 15:12  Check if the silence gate threshold needs adjusting for USB mics.

Configuration:

export VNOTE_FILE=~/project-notes.txt   # default: ~/voice-notes.txt
export VNOTE_DURATION=20s               # default: 15s
Troubleshooting