System Integration¶

Set up system-wide hotkeys and integrations for seamless voice-powered workflows.

Overview¶

Agent CLI is designed to work with system-wide hotkeys, allowing you to trigger voice commands from any application. This page covers setup for different platforms.

macOS Setup¶

Automated Setup (Recommended)¶

agent-cli install-hotkeys

This automatically installs all dependencies (skhd, terminal-notifier) and creates a default configuration with common hotkeys.

Accessibility Permission Required

After installation, grant Accessibility permissions to skhd: System Settings → Privacy & Security → Accessibility → enable "skhd"

Manual skhd Configuration¶

Create or edit ~/.config/skhd/skhdrc:

# Transcribe to clipboard (toggle recording)
cmd + shift + r : /path/to/agent-cli transcribe --toggle --input-device-index 1

# Autocorrect clipboard
cmd + shift + a : /path/to/agent-cli autocorrect

# Voice edit clipboard
cmd + shift + v : /path/to/agent-cli voice-edit --toggle --input-device-index 1

# Speak clipboard
cmd + shift + s : /path/to/agent-cli speak

Reload skhd:

skhd --reload

Notifications¶

The install-hotkeys command automatically installs terminal-notifier for visual feedback.

Configure notifications in System Settings: 1. Settings → Notifications → terminal-notifier 2. Enable "Allow Notifications" 3. Set Alert style to Persistent for recording indicators

Linux Setup¶

Hyprland¶

Add to ~/.config/hypr/hyprland.conf:

# Transcribe to clipboard
bind = SUPER SHIFT, R, exec, agent-cli transcribe --toggle --input-device-index 1

# Autocorrect clipboard
bind = SUPER SHIFT, A, exec, agent-cli autocorrect

# Voice edit clipboard
bind = SUPER SHIFT, V, exec, agent-cli voice-edit --toggle --input-device-index 1

# Speak clipboard
bind = SUPER SHIFT, S, exec, agent-cli speak

i3/Sway¶

Add to ~/.config/i3/config or ~/.config/sway/config:

# Transcribe to clipboard
bindsym $mod+Shift+r exec agent-cli transcribe --toggle --input-device-index 1

# Autocorrect clipboard
bindsym $mod+Shift+a exec agent-cli autocorrect

# Voice edit clipboard
bindsym $mod+Shift+v exec agent-cli voice-edit --toggle --input-device-index 1

GNOME¶

Use gsettings or GNOME Settings → Keyboard → Custom Shortcuts:

gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings \
  "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/']"

gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  name 'Transcribe'
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  command 'agent-cli transcribe --toggle --input-device-index 1'
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ \
  binding '<Super><Shift>r'

KDE Plasma¶

System Settings → Shortcuts → Custom Shortcuts
Edit → New → Global Shortcut → Command/URL
Set trigger (e.g., Super+Shift+R)
Set command: agent-cli transcribe --toggle --input-device-index 1

Windows Setup (WSL2)¶

AutoHotkey¶

Install AutoHotkey and create a script:

; Transcribe to clipboard
#+r::Run, wsl agent-cli transcribe --toggle --input-device-index 1

; Autocorrect clipboard
#+a::Run, wsl agent-cli autocorrect

PowerToys¶

Use PowerToys Run or Keyboard Manager to create custom shortcuts.

NixOS Setup¶

See the NixOS installation guide for declarative hotkey configuration.

Recommended Hotkey Layout¶

Hotkey	Command	Description
`Cmd/Super + Shift + R`	`transcribe --toggle`	Record voice → clipboard
`Cmd/Super + Shift + A`	`autocorrect`	Fix clipboard text
`Cmd/Super + Shift + V`	`voice-edit --toggle`	Edit clipboard with voice
`Cmd/Super + Shift + S`	`speak`	Read clipboard aloud

Finding Your Audio Device¶

Before setting up hotkeys, find your microphone's device index:

agent-cli transcribe --list-devices

Look for your microphone and note its index number.

Workflow Tips¶

Typical Voice-to-LLM Workflow¶

Copy context (email, code, document)
Press transcribe hotkey → start speaking
Press hotkey again → text copied to clipboard
Paste into your LLM chat

Voice Editing Workflow¶

Copy draft text
Press voice-edit hotkey → "make this more formal"
Press hotkey again → edited text in clipboard
Paste the improved version

Autocorrect Workflow¶

Type quickly (with typos)
Select and copy
Press autocorrect hotkey
Paste corrected text

Troubleshooting¶

Hotkey Not Working¶

# Check if agent-cli is in PATH
which agent-cli

# Test command directly
agent-cli transcribe --list-devices

# Check hotkey daemon is running (macOS)
brew services list | grep skhd

Audio Device Issues¶

# List devices
agent-cli transcribe --list-devices

# Test with specific device
agent-cli transcribe --input-device-index 1

Permission Issues (macOS)¶

System Settings → Privacy & Security → Microphone
Add your terminal app (Terminal, iTerm2, Alacritty, etc.)
Restart the terminal