Skip to content
Docs0.9GitHubInstall

Using itHUD and tab labels

Floating panels and tab labels

The desktop HUD: agent and notification cards

A tmux status bar with agent titles and status icons in its tabs

These are plugins of the notification worker (vendetta notify start). They follow the tmux server in [plugins.host-tmux] socket, or tmux’s default server.

The Kitty panel's agent list

A small non-focusable panel in the top-right corner of your active terminal lists running agents first, then recent ones, with team tags. It hides while the chooser is open, when you switch apps, or when the terminal is too small. Your tmux layout and status bar are untouched.

[plugins.hud-kitty]
enabled = true
max_agents = 5   # 1–20
width_px = 640   # 160–1600
margin_px = 12
min_width = 100  # hide below this terminal size
min_height = 24
# font_family / font_size default to Kitty's own settings
vendetta-hud-kitty start   # also: stop, toggle

It stays on until you stop it. The plugin also offers hud-kitty:toggle, start, and stop for desktop keys:

[plugins.shortcuts.keys]
"hud-kitty:toggle" = "super+h"

To start it automatically from tmux, add these hooks. Slot 100 keeps other hooks intact.

set-hook -g session-created[100] { run-shell -b '"$HOME/.local/bin/vendetta-hud-kitty" start' }
set-hook -g client-attached[100] { run-shell -b '"$HOME/.local/bin/vendetta-hud-kitty" start' }

It works only on a local Hyprland desktop: it places itself over the focused window when a terminal of Vendetta’s hosts (tmux or Kitty) shows in it, and shows nothing over other windows or on other desktops. It needs kitten panel. Enabling the plugin is not enough: run vendetta-hud-kitty start (or the hooks above) to show the panel. If you run several desktops, set HYPRLAND_INSTANCE_SIGNATURE to pick one. Settings reload while it runs.

The desktop HUD runs on Hyprland and, through the Vendetta app, on macOS. Other Linux desktops are not supported. On Hyprland its colors come from Noctalia’s theme (~/.config/noctalia) when there is one.

Cards stack in one column in the top-right corner of the focused monitor, above normal windows (layer = "overlay" also covers fullscreen ones), in Noctalia’s colors. Each card is a section: agents, running first, with team tags, your Personal Hub to-dos, overdue first, the worker’s notifications, and anything a program of yours prints. A notification names the project and the agent in bold, says what happened, and shows what the agent said or asks, its Markdown formatted, up to a few lines; click it to open that agent. It shows in its card for a few seconds, over a bar that runs out with it, so several at once stay readable as each times out; hover the card, or keep it open with +, to scroll back through the newest ones. While you dictate, the recording shows in a card above them all, or where sections places it, and a failed one says it was kept to send again; a card that appears pushes the ones below it down. The HUD never takes the keyboard, and clicks outside the cards reach the windows beneath. Click an agent to open it: in the focused terminal, else in the one used last, which comes forward; an agent outside tmux and Kitty brings its own terminal forward. Bringing a window forward needs the shortcuts plugin. − minimizes a card to its header. With collapse = "hover", cards show only their headers, a card shows its rows while the pointer is over it, and + keeps it open. Drag any header to move the whole column; it stays there across restarts, and a double click on a header returns it to the corner.

On macOS, the Vendetta app draws the cards from the same settings: vendetta-hud serves them on a private socket, and the app’s dictation is the first card while it records, unless sections places it. An agent click opens it in the terminal used most recently, which the app brings forward for the shortcuts plugin.

[plugins.hud]
# platform = "auto"  # "hyprland" or "macos" when auto picks wrong
# width_px = 380     # 200–1200
# font_size = 15     # rows' text, 6–36; titles and notes follow it
# opacity = 0.75     # the cards' background, 0–1; text stays solid
# monitor = "DP-2"   # default: the focused monitor
# layer = "top"      # "overlay" also covers fullscreen windows
# collapse = "manual" # "hover": headers only, rows while hovered; + keeps a card open

# Sections, top to bottom; the default is agents, then notifications. A running
# dictation's card goes first unless a { type = "dictation" } entry places it.
[[plugins.hud.sections]]
type = "agents"
# max = 8            # rows, 1–50

[[plugins.hud.sections]]
type = "todo"        # needs a plugin serving tasks, such as personal-hub
# max = 10

[[plugins.hud.sections]]
type = "notifications" # the worker's alerts; with agents, the default
# seconds = 10       # how long each shows while the card is folded, 1–3600
# max = 50           # how many the history keeps, 1–100
# visible = 8        # history rows before the rest scroll, 1–50
# lines = 6          # lines of what each agent said, 1–50
# font_size = 17     # its own text size, 6–36; the HUD's by default

[[plugins.hud.sections]]
type = "command"     # your own; see docs/hud-sections.md
name = "disk"
command = ["/home/you/bin/disk-hud"]
interval_seconds = 60

A command section’s program prints its section as JSON lines: a title, a summary, and rows with icons, colors, and a command to run on click. See hud-sections.md. The HUD takes up to 20 sections, with unique names, and interval_seconds defaults to 30.

./install.sh builds it when GTK 4 and gtk4-layer-shell are installed; restart the worker after enabling it. The to-do section lists unfinished tasks that are not snoozed and refreshes when the hub changes. To minimize from a key:

hl.bind("SUPER + A", hl.dsp.exec_cmd("vendetta-hud toggle"))              -- every section
hl.bind("SUPER + SHIFT + A", hl.dsp.exec_cmd("vendetta-hud toggle todo"))

minimize and restore take a section too, and reset returns a dragged column to the corner.

With tab_labels in the tmux host’s table, and the worker restarted, the tmux host publishes @vendetta-tab-label on each window that holds an agent. The label has provider and status icons plus the title; several agents in one tab appear in pane order, and a window of managed agents reads Agents. It works over SSH and leaves window names untouched.

[plugins.host-tmux]
tab_labels = true
tab_label_width = 42   # title width in columns, 8–200

Show the label in your window format:

set -g window-status-format '#I #{?@vendetta-tab-label,#{@vendetta-tab-label},#W}'
set -g window-status-current-format '#I #{?@vendetta-tab-label,#{@vendetta-tab-label},#W}'

integrations/tmux-tabs.conf has this setup. For Catppuccin, set its window text before loading the theme instead:

set -g @catppuccin_window_text ' #{?@vendetta-tab-label,#{@vendetta-tab-label},#{=/42/...:#{window_name} #{b:pane_current_path}}}'
set -g @catppuccin_window_current_text ' #{?@vendetta-tab-label,#{@vendetta-tab-label},#{=/42/...:#{window_name} #{b:pane_current_path}}}'

Stopping the worker, or tab_labels = false and a worker restart, clears the labels.