Skip to content
Docs0.9GitHubInstall

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.

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 actions

Use 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 columns

The 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 macOS

The 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 tui by hand. Shift+Enter types into a Kitty agent’s preview; Enter can’t bring a desktop window to you.
  • Sessions keep their names. R renames 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.

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.
  • n starts 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.

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.

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.