Running itConfiguration reference
Configuration
~/.config/vendetta/config.toml holds every setting; the chooser, vendetta tui, reads its [tui] table each time it opens and says there what is wrong with it. Missing fields use defaults. config.example.toml
lists the settings. Use --config PATH, before any subcommand, for another file.
XDG_CONFIG_HOME and XDG_STATE_HOME move the config and state directories.
The worker applies the file about a second after you save it. A plugin turned on or
off starts or stops; a plugin whose table changed restarts, except for a change to the
keys of a host or [plugins.shortcuts], which they bind again themselves, and a change to [master]
or icons restarts every plugin. Everything else applies without a restart, except a
new [plugins.host-tmux] socket or [person]: the worker then restarts itself and
says so in its log. A file with an error changes nothing: the worker keeps the last
good config, logs the error, and sends you an alert.
vendetta config check # parse and validate the file without applying it
vendetta config reload # apply it now and print what changedicons = "auto" # auto, nerd, text; shared with the HUD
[tui]
view = "agents" # all, agents, codex, omp, claude, opencode, gemini, aider
focus = "tree" # tree (the projects, in the projects view) or history (--focus overrides)
expand = "tabs" # sessions, tabs, panes
sort = "activity" # activity, name, status
confirm_jumps = true # hints select; Enter opens
relative_jumps = true # hints count from the selection
large_openai_icon = true # two-column badges via Kitty graphics
large_pi_icon = true
refresh_ms = 1000
[tui.compact]
mode = "auto" # auto, always, never
width_threshold = 100
height_threshold = 24
[tui.preview]
enabled = true # v shows or hides it
fps = 30 # 1–60
min_width = 120 # hidden on narrower terminals
[tui.layout]
columns = [
{ width = 45, panels = ["projects 40%", "agents"] },
{ panels = ["history 40%", "preview"] },
][tui.layout] places and sizes the chooser’s panels; see Layout.
[auto_delete] deletes stopped conversations after a while, except those you keep;
see Auto-delete.
[teams] remind_after (default "15m") reminds a manager, once, of a member’s
finished turn, question, or error it was told of in a team update and has not acted
on since: no prompt, answer, rename, release, or deletion of that member from it, and
no prompt from you. Each level of nested teams is reminded the same way. Use a
duration such as "15m", "1h", or "30s"; "off" or "0" turns reminders off.
[machines] runs listed projects’ agents in containers; see Machines.
icons = "auto" checks the installed fonts per glyph. Use nerd or text when
your terminal runs on another machine.
[launch] host chooses where agents go, and each host’s keys table which keys open
things in your terminals. [plugins.<name>] tables turn on plugins, whose guides list their settings.
Custom shortcuts
Section titled “Custom shortcuts”Every action can be rebound under [tui.keys]. A binding replaces that action’s whole
list, and [] unbinds it, except that preview_exit must keep a key. A key already
bound to another tree action is refused. Help and the footer show your bindings. The
overview’s own keys may reuse a key only the tree takes, never one the overview
also takes.
Key names:
- literal characters;
Space,Enter,Esc,Tab,Backspace,Delete,Insert,Menu;- arrows,
Home,End,PageUp,PageDown,F1–F24; - any of these with
Ctrl+,Alt+, orShift+.
[tui.keys]
jump_digits = "0123456789"
jump_alphabet = "abcdefghijklmnopqrstuvwxyz"
down = ["Down", "j"]
up = ["Up", "k"]
collapse = ["Left", "h"]
expand = ["Right", "l"]
confirm = ["Enter"]
cancel = ["Esc"]
backspace = ["Backspace"]
next_project = ["Tab"]
previous_project = ["Shift+Tab"]
page_down = ["PageDown"]
page_up = ["PageUp"]
first = ["Home"]
last = ["End", "G"]
focus_history = ["g"]
expand_all = ["+", "="]
collapse_all = ["-"]
toggle_branch = ["Space"]
search = ["/"]
jump = ["f"]
help = ["?"]
preview = ["v"]
preview_enter = ["Shift+Enter"]
preview_exit = ["Alt+q"]
preview_up = ["Alt+Up"]
preview_down = ["Alt+Down"]
preview_left = ["Alt+Left"]
preview_right = ["Alt+Right"]
preview_follow = ["V"]
cycle_view = ["c"]
attention = ["!"]
exited = ["e"]
sort = ["O"]
reverse = ["r"]
tag = ["t"]
tag_all = ["T"]
clear_tags = ["Ctrl+t"]
clear_input = ["Ctrl+u"]
overview = ["w", "Alt+w"]
close = ["x"]
close_tagged = ["X"]
stop = ["S"]
rename = ["R"]
absorb = ["m"]
release = ["M"]
mute = ["d"]
keep = ["P"]
team_choice = ["E"]
trust = ["A"]
native = ["b"]
schedule = ["s"]
tasks = ["p"]
calendar = ["C"]
new_agent = ["n"]
new_session = ["N"]
focus_master = ["Alt+A"]
quit = ["q"]
abort = ["Ctrl+c"]
# The overview's own
prompt = ["i"]
project_color = ["c"]
actions = ["a", "Menu", "Shift+F10"]
interrupt = []
filter = ["f"]How status is detected
Section titled “How status is detected”- Discovery: agents are found among your processes by provider. Process ancestry
places each in its tmux pane; agents outside tmux are grouped by git project,
unless their
XDG_STATE_HOMEorHOMEnames another Vendetta state directory. - Status: integrations write small status records to
~/.local/state/vendetta. A record counts only while its process is alive with the same provider and start time, so a reused PID never inherits stale state. - Codex fallback: without hooks, Codex status comes from its rollout files.
- Quiet agents: an agent never becomes idle just because it has gone quiet.
vendetta snapshot prints the tmux panes and their agents as JSON. Its source field
shows where each state came from: hook, extension, plugin, transcript, or
process.
If an agent stays unknown, check that its hooks are trusted or its extension or
plugin is loaded. If a title looks wrong, compare it with
tmux list-panes -a -F '#{pane_id} #{pane_title}'. Agents outside tmux take their
title from the conversation, or else their project name.