View source for Talon Voice Control

= Talon Voice Control Setup =

Custom voice control configuration for macOS using [https://talonvoice.com/ Talon].

'''Source code''': [https://github.com/ejfox/dotfiles/tree/main/talon-overrides github.com/ejfox/dotfiles/talon-overrides]

== Daily Drivers ==

The commands worth memorizing. Everything else is in the [[#Full Command Reference|full reference]] below.

{| class="wikitable"
|-
! Category !! Say !! Does
|-
| '''Mode''' || cmd / talk || Switch between command and dictation
|-
| '''Enter''' || go ahead / send it || Press Enter
|-
| '''tmux''' || mux one thru mux nine || Jump to window N
|-
| '''tmux''' || mux left / right / up / down || Navigate panes
|-
| '''tmux''' || mux zoom || Toggle pane fullscreen
|-
| '''tmux''' || mux split right / down || Split pane
|-
| '''tmux''' || mux close pane || Close current pane
|-
| '''tmux''' || mux new || New window
|-
| '''tmux''' || mux sessions || Session picker
|-
| '''Terminal''' || wipe || Clear current line
|-
| '''Terminal''' || cancel || Ctrl-C
|-
| '''Terminal''' || again || Re-run last command
|-
| '''Terminal''' || edit || Open nvim
|-
| '''Terminal''' || lazy || Open lazygit
|-
| '''Terminal''' || files || Open yazi
|-
| '''Terminal''' || run claude || Launch Claude Code
|-
| '''Nav''' || go code / go home / go dotfiles || cd to directory
|-
| '''Git''' || git status / push / pull / diff || Git commands
|-
| '''Apps''' || open ghosty / chrome / obsidian / slack || Switch apps
|-
| '''Windows''' || snap left / right / full || Window positioning
|}

'''Tip''': Voice command usage is logged to <code>~/.local/share/usage-logs/talon/</code> — run <code>usage-analyze</code> after a week to see what you actually use most.

== Overview ==

Voice-driven workflow for terminal (Ghostty + tmux), macOS app switching, and window management. All config lives in <code>~/.dotfiles/talon-overrides/</code> (symlinked to <code>~/.talon/user/ejfox-overrides/</code>).

The TTS feedback script (<code>claude-say</code>) lives at [https://github.com/ejfox/dotfiles/blob/main/bin/claude-say github.com/ejfox/dotfiles/bin/claude-say] and the symlink setup is in [https://github.com/ejfox/dotfiles/blob/main/sync-dotfiles.sh sync-dotfiles.sh].

== Architecture ==

* '''Community scripts''': <code>~/.talon/user/community/</code> (talonhub/community clone)
* '''Custom overrides''': <code>~/.talon/user/ejfox-overrides/</code> ([https://github.com/ejfox/dotfiles/tree/main/talon-overrides dotfiles-tracked])
* '''Speech engine''': Conformer (Talon's built-in, downloaded via Talon menu)

== Files ==

{| class="wikitable"
|-
! File !! Purpose !! Source
|-
| <code>settings.talon</code> || Global settings (tmux prefix, subtitle config) || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/settings.talon github]
|-
| <code>custom_keys.talon</code> || Mode switching (cmd/talk) and Enter aliases || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/custom_keys.talon github]
|-
| <code>tmux.talon</code> || ~30 tmux voice commands (windows, panes, sessions) || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/tmux.talon github]
|-
| <code>terminal_commands.talon</code> || Ghostty-specific: line editing, nav, git, launchers || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/terminal_commands.talon github]
|-
| <code>macos_nav.talon</code> || App switching, Rectangle Pro, Spaces, general macOS || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/macos_nav.talon github]
|-
| <code>ghostty.talon</code> || Ghostty terminal detection (too new for community) || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/ghostty.talon github]
|-
| <code>cursor.talon</code> || Cursor IDE detection || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/cursor.talon github]
|-
| <code>apps.py</code> || App definitions for newer apps not in community || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/apps.py github]
|-
| <code>nato_alphabet.py</code> || NATO phonetic alphabet override (Python Context) || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/nato_alphabet.py github]
|-
| <code>mode_line.py</code> || 2px colored bar at screen bottom showing current mode || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/mode_line.py github]
|-
| <code>ejfox_subtitles.py</code> || Right-aligned subtitles below sketchybar || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/ejfox_subtitles.py github]
|-
| <code>usage_logging.py</code> || JSONL command logger for usage analysis || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/usage_logging.py github]
|-
| <code>vocabulary.talon-list</code> || ~250 custom vocabulary terms || [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/vocabulary.talon-list github]
|}

== Key Design Decisions ==

=== NATO Alphabet via Python Override ===

The community <code>.talon-list</code> file takes priority over user overrides. The only reliable way to replace the letter list is a Python Context override.

=== tmux Prefix Timing ===

tmux needs <code>sleep(100ms)</code> between the prefix key and the command key. Without it, the command fires before tmux registers the prefix.

=== Anchored Rules for Dictation Mode ===

Commands must use <code>^...$</code> anchors to work in dictation mode. Without anchors, the prose capture engine swallows the command and types it as text.

=== Custom Subtitles ===

Community subtitles plugin is center-aligned with no horizontal position setting. Custom <code>[https://github.com/ejfox/dotfiles/blob/main/talon-overrides/ejfox_subtitles.py ejfox_subtitles.py]</code> renders right-aligned text below sketchybar (38px from top).

=== Mode Line ===

2px colored line at screen bottom replacing default circle indicator:
* '''Pink''' (<code>#e60067</code>): Command mode
* '''Teal''' (<code>#6eedf7</code>): Dictation mode
* '''Muted''' (<code>#735865</code>): Sleep mode

=== Usage Logging ===

Every recognized phrase is logged to <code>~/.local/share/usage-logs/talon/YYYY-MM-DD.jsonl</code> with timestamp, phrase text, word count, and active app. Same format as shell and tmux usage logs — analyze with <code>usage-analyze</code> or <code>jq</code>.

== Full Command Reference ==

=== Mode Switching ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/custom_keys.talon custom_keys.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| cmd || Switch to command mode
|-
| talk || Switch to dictation mode
|-
| go ahead / go head / send it || Press Enter
|}

=== tmux Windows ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/tmux.talon tmux.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| mux one thru mux nine || Jump to window N
|-
| mux next / mux previous || Next/prev window
|-
| mux last || Last used window
|-
| mux new || New window
|-
| mux rename || Rename window
|-
| mux close || Close window
|-
| mux alert / mux newest || Jump to window with bell
|-
| mux workspace || Session/window picker
|}

=== tmux Panes ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/tmux.talon tmux.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| mux left / right / up / down || Navigate panes
|-
| mux move left / right / up / down || Move pane in direction
|-
| mux next pane || Cycle panes
|-
| mux split right / down || Split pane
|-
| mux pane right / down / left / up || Split + auto-focus new pane
|-
| mux close pane || Close current pane
|-
| mux zoom || Toggle pane fullscreen
|-
| mux sessions || Session picker
|-
| mux scroll || Enter scroll mode
|-
| mux detach || Detach from session
|}

=== Terminal ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/terminal_commands.talon terminal_commands.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| wipe || Clear line (ctrl-u)
|-
| wipe word || Delete last word (ctrl-w)
|-
| cancel / nope / bail || Ctrl-C
|-
| again || Re-run last command
|-
| clear || Clear terminal
|-
| edit / run neovim || Open nvim
|-
| lazy / run lazygit || Open lazygit
|-
| files / run yazi || Open yazi
|-
| run btop || Open btop
|-
| run claude || Launch Claude Code
|-
| run claude skip || Launch Claude Code (skip hooks)
|-
| run codex || Launch Codex CLI
|-
| tips || Search tips with fzf
|-
| refresh || Source .zshrc
|-
| list files || <code>ls</code>
|-
| list all || <code>ls -la</code>
|-
| note <text> || Quick note to Obsidian daily
|}

=== Directory Navigation ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/terminal_commands.talon terminal_commands.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| go home || <code>cd ~</code>
|-
| go code || <code>cd ~/code</code>
|-
| go smallweb || <code>cd ~/smallweb</code>
|-
| go clients || <code>cd ~/clients</code>
|-
| go dotfiles || <code>cd ~/.dotfiles</code>
|-
| go back || <code>cd -</code>
|-
| go up || <code>cd ..</code>
|-
| go paperclip / website / coach / connectology / vulpes / subway / newswell / gem / ddhq || Project directories
|}

=== Git ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/terminal_commands.talon terminal_commands.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| git status / push / pull / log / diff || Standard git commands
|-
| git add all || <code>git add -A</code>
|-
| git stash / git pop || Stash and pop
|}

=== Dev ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/terminal_commands.talon terminal_commands.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| dev server || <code>npm run dev</code>
|-
| yarn dev || <code>yarn dev</code>
|-
| install || <code>npm install</code>
|-
| connect VPS / connect || SSH to VPS
|}

=== App Switching ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/macos_nav.talon macos_nav.talon]''

<code>open ghosty</code>, <code>open chrome</code>, <code>open safari</code>, <code>open messages</code>, <code>open slack</code>, <code>open discord</code>, <code>open signal</code>, <code>open obsidian</code>, <code>open claude</code>, <code>open figma</code>, <code>open finder</code>, <code>open music</code>, <code>open OBS</code>

=== Window Management ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/macos_nav.talon macos_nav.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| snap left / right || Half screen
|-
| snap up / snap full || Fullscreen
|-
| snap down / snap bottom || Bottom half
|-
| window bigger / smaller || Resize
|-
| window grid || Grid overlay (F1)
|-
| window cascade || Cascade (F12)
|-
| space left / space right || Switch Spaces
|}

=== General macOS ===
''Source: [https://github.com/ejfox/dotfiles/blob/main/talon-overrides/macos_nav.talon macos_nav.talon]''

{| class="wikitable"
|-
! Say !! Does
|-
| hide this / hide others || Hide apps
|-
| quit this || Quit (cmd-q)
|-
| close window / close tab || Close (cmd-w)
|-
| new tab / new window || New tab/window
|-
| next tab / previous tab || Switch tabs
|-
| spotlight || cmd-space
|-
| undo / redo || cmd-z / cmd-shift-z
|-
| save || cmd-s
|-
| select all / copy / paste / cut / find || Standard shortcuts
|-
| screenshot / screen record || cmd-shift-4 / cmd-shift-5
|}

== claude-say (TTS) ==

Script at [https://github.com/ejfox/dotfiles/blob/main/bin/claude-say <code>~/bin/claude-say</code>] lets [[Claude Code]] speak responses aloud:

* Mutes mic input before speaking (prevents Talon feedback loop)
* Restores mic volume after speaking
* Prefixes with tmux window number for voice navigation
* Uses macOS <code>say -v Samantha</code>

== Lessons Learned ==

# <code>.talon-list</code> overrides don't reliably replace community lists — use Python Context overrides
# Ghostty is too new for community scripts — need custom app detection
# <code>sleep(100ms)</code> between tmux prefix and command key is essential
# <code>^...$</code> anchors required for commands to work in dictation mode
# Built-in Talon subtitle controlled by <code>speech._subtitles</code> setting (undocumented)
# Community subtitles are a separate plugin with their own settings
# macOS <code>say</code> triggers Talon — must mute mic first via <code>claude-say</code> wrapper

== See Also ==

* [[Dotfiles]] — full dotfiles setup
* [[CLI]] — terminal workflow
* [[Nvim]] — editor configuration
* [[tmux]] — multiplexer setup

[[Category:Tools]]
[[Category:Voice]]
[[Category:Configuration]]