Running itTerminals: tmux, Kitty
Terminals
Vendetta works in three setups, with any supported terminal and multiplexer. The chooser, its keys, the overview, and the apps are the same in all of them.
| Setup | What shows the chooser | Where agents run | Over SSH |
|---|---|---|---|
| tmux | tmux’s popup, in any terminal | tmux panes, which outlive the terminal | Works, with the same keys |
| Kitty | A floating Kitty panel | Kitty windows, which close with Kitty | Run vendetta tui by hand; preview and type only |
| Both | Kitty on the desktop, tmux over SSH | Your choice | Works, with the same keys |
Agents you start by hand stay where you started them, in any terminal. With no supported terminal at all, Vendetta still lists them and controls them through their native channels; see Without a host.
Shortcuts
Section titled “Shortcuts”No key is bound until you name it in a host’s keys table. The keys below are the
suggested ones:
| Key | Action |
|---|---|
| Alt+S | Chooser |
| Alt+D | Chooser on its history |
| Alt+W | Overview |
| Alt+Shift+A | Open the Master |
| Alt+Shift+D | Previous agent |
| Alt+A | This project’s Agents |
| Alt+Z | This project’s Agents side by side, or the one in focus alone |
In a project’s Agents tab, Alt+Z shows every agent side by side, focus staying on the one you were on, and again shows the one in focus alone: that one, or the one you moved to. From another tab of the project it shows the Agents tab side by side. tmux zooms and unzooms the pane; Kitty switches the tab between its stack layout and the one before.
Each host binds the keys its keys table names in its terminal, and binds them again
whenever you change it, with no restart:
[plugins.host-tmux.keys]
chooser = "alt+s"
history = "alt+d"
overview = "alt+w"
master = "alt+shift+a"
previous = "alt+shift+d"
agents = "" # empty leaves it unbound
layout = "alt+z"
[plugins.host-kitty.keys]
chooser = "alt+s" # and the same actionsUse the same key for an action in both if you run tmux inside Kitty or over SSH from it: Kitty passes a key it does not handle to the tmux in front of it.
# ~/.config/vendetta/config.toml
[plugins.host-tmux]
# socket = "/tmp/tmux-1000/default" # the tmux server; default: tmux's own
# tab_labels = true # title windows after the agents in them
# tab_label_width = 42 # longest title in a label, in columnsThe worker runs vendetta-host-tmux, so tmux works while the worker runs. Without the table, or with
enabled = false, Vendetta sees no tmux. It uses one tmux server, the one in socket.
The host writes the bindings to ~/.local/state/vendetta/tmux/vendetta.conf and has the
server read it, again whenever the keys change or the server restarts; your tmux.conf
needs nothing. Leave Vendetta’s keys out of it, or a reload of it brings back old ones.
While a key is bound, the host also sets the server’s extended-keys to on with the
csi-u format, so apps can tell Shift+Enter from Enter, and hooks that record recently
focused panes for the previous-agent key. With no key bound it changes nothing in the
server.
See tmux setup for recommended terminal settings.
With tab_labels, a window holding agents is titled after them, with their provider and
state icons. Show the label in your theme’s window format, as
integrations/tmux-tabs.conf does.
# ~/.config/vendetta/config.toml
[launch]
host = "kitty" # where agents go when nothing says otherwise
# For Kitty alone, leave out [plugins.host-tmux].
[plugins.host-kitty]
# tab_labels = true # title tabs after the agents in them, until the plugin stops
# popup = "auto" # "panel" or "overlay"
# sockets = ["unix:/tmp/kitty.sock"] # found automatically on Linux; required on macOSThe host writes the bindings to
~/.local/state/vendetta/kitty/vendetta.conf, adds a line including it at the end of
kitty.conf if none does, and has every running Kitty reload its config whenever the keys
change. The file sets allow_remote_control socket-only. The plugin also needs a socket:
set listen_on in kitty.conf unless it does, and restart Kitty once.
A project is a Kitty session, and its agents share an Agents tab in it. To show only the current project’s tabs:
tab_bar_filter session:~ or session:^$What differs from tmux:
- Agents end when Kitty closes. History can restore their conversations, but not the processes. Nothing can detach from or attach to a Kitty window.
- Launches need a desktop. If Kitty isn’t running, a schedule or the Master starts it. With no display, the launch fails and says so.
- Over SSH, run
vendetta tuiby hand. Shift+Enter types into a Kitty agent’s preview; Enter can’t bring a desktop window to you. - Sessions keep their names.
Rrenames tabs and windows, not sessions. - The chooser floats on Hyprland and other compositors with layer-shell panels. On GNOME, and where panels don’t work, it opens as an overlay on the current window, which is small in a split.
- Idle shutdown treats a focused window as in use, since Kitty doesn’t report typing.
Kitty and tmux
Section titled “Kitty and tmux”Enable both as above, and pick where agents go:
[launch]
host = "tmux" # keeps unattended agents alive, and reachable over SSH
[plugins.host-tmux]
[plugins.host-kitty]Generate both sets of bindings. Then:
- On the desktop, Kitty handles the keys, whether a window shows a shell, an agent, or tmux. The chooser floats over it without switching tabs.
- Enter shows the agent wherever it runs: through the tmux client in that window, else through another window’s client, which comes forward, else in a new tab attached to tmux.
- In an SSH session, Kitty passes the keys through to the remote machine.
- From a phone or any other terminal, tmux handles the keys as usual.
nstarts an agent in whichever host you opened the chooser through. Schedules, messaging, and the Master use[launch] host.
The tree groups by project, so one project can show tmux panes and Kitty windows together.
Anywhere on the desktop
Section titled “Anywhere on the desktop”On Hyprland and macOS, the shortcuts plugin gives keys across the desktop to actions. Vendetta and its plugins offer actions by name, and the table names the ones you want, with their keys:
[plugins.shortcuts]
[plugins.shortcuts.keys]
"vendetta:chooser" = "alt+s"
"vendetta:history" = "alt+d"
"vendetta:overview" = "alt+w"
"vendetta:master" = "alt+shift+a"
"vendetta:previous" = "alt+shift+d"
"vendetta:agents" = "alt+a"
"vendetta:layout" = "alt+z"
"dictation:toggle" = "super+d"| Actions | Offered by | What they do |
|---|---|---|
vendetta:chooser, history, overview, master, previous, agents, layout |
Vendetta | Act where you are |
kitty: and the same seven |
The Kitty host | Always in Kitty |
dictation:toggle, master, cancel, retry |
Dictation | cancel only while recording, retry while a failed dictation is kept |
hud-kitty:toggle, start, stop |
Kitty HUD | Show or close the panel |
A vendetta: key does what the focused window would do with it. In a Kitty with its host
plugin, it is Kitty’s own key: the chooser opens over the terminal, and a connection to
another machine or an open chooser gets the key. In another terminal running tmux, it
opens tmux’s popup on that client. Anywhere else, the chooser floats over the focused
window, and the agent you open comes forward wherever it runs. A kitty: key acts in the
focused Kitty, else floats the chooser through Kitty or opens in the Kitty you used last.
A key is bound only while its action is offered, so dictation:cancel takes Escape only
during a recording; a name nothing offers is noted in the worker’s log. A key set for two
actions is refused, keeping the keys as they were. The desktop takes these keys from every
window, so terminals no longer see them. A change applies within a second, and the keys end
with the plugin: Hyprland drops them if it dies.
The plugin also brings windows forward for the rest of Vendetta: a HUD click, a
vendetta:// link, or the chooser opening an agent outside tmux and Kitty. Without it,
those still switch the terminal to the agent, but leave its window where it is.
On Linux the keys need Hyprland with its Lua config (hl.bind), as in 0.57. On any other
desktop, or while no Hyprland runs, vendetta notify status shows the plugin as
unavailable and the worker’s log says why; the keys are bound once Hyprland starts.
On macOS the Vendetta app holds the keys as global
hotkeys while it runs, and tells the plugin which app was in front as one was pressed. The
chooser floats through Kitty’s panel, so a key outside a terminal needs Kitty running.
platform = "macos" or "hyprland" names the desktop; it is found on its own.
Other terminals
Section titled “Other terminals”| Terminal | Status |
|---|---|
| tmux, Kitty | Supported |
| Zellij, WezTerm | Not yet; their command lines offer what a host needs |
| Ghostty, Alacritty, foot, others | Run tmux inside them, or use [launch] terminal |
A new terminal or multiplexer is a program named vendetta-host-NAME. See
Writing a host.