Usage¶

Start vupai inside a project, open a few agent panes, and drive them by voice. The push-to-talk daemon runs in the background, so you stay in tmux and just hold a key to talk. Launch (or re-attach to) a session with:

vupai                 # attach-or-create the session named after the cwd
vupai attach backend  # attach to "backend" (create it if absent)
vupai new backend     # create "backend" (error if it already exists)
vupai kill backend    # kill the "backend" session

Note

vupai runs on its own tmux server, so it never touches your existing tmux setup. The trade-off: its sessions don't show in a plain tmux ls; reach them with vupai attach. (Set tmux_socket = "" to share your default server.)

It's still tmux

The voice layer sits on top; every normal tmux binding keeps working. Detach with <prefix> d, split panes by hand, switch with <prefix>-arrow, scroll/copy-mode, resize, your own custom keybindings: all unchanged. Use voice when it's faster, the prefix key when it's not. (Your ~/.tmux.conf is sourced too, with the few exceptions noted in tmux tips.)

Push-to-talk keys¶

Once attached, you talk to vupai with two push-to-talk keys:

Key	Config	Default	Hold and speak to…
Dictation key	`hotkey`	Right-Option	Type your words into the focused pane.
System key	`command_hotkey`	Right-Command	Run a voice command. The key is the signal, so there is no spoken control word; vupai acts on the panes instead of typing.

Both defaults are customizable: set hotkey / command_hotkey in the config (each takes a list, so you can bind several keys to one action).

Tip

vupai only listens for keyboard keys. To use a mouse button or other input as a push-to-talk key, remap it to a keyboard key (e.g. F13) with a tool like Karabiner-Elements or BetterTouchTool, then bind that key here.

Commands¶

Run vupai --help for the full command list (and vupai <command> --help for a specific one). The everyday ones are above.

The push-to-talk daemon runs as a detached background process under your terminal app (not inside tmux; that's required for the global hotkey to work). It logs to ~/.config/vupai/daemon.log and survives detach/reattach.