StartInstall
Install
Requires Linux or macOS and a stable Rust toolchain. The rest depends on what you use:
| For | You need |
|---|---|
| Building on Linux | A C toolchain, pkg-config, clang, and the ALSA and PipeWire development files (dictation links them) |
| tmux panes, previews, and managed agents | tmux 3.3+; 3.5+ for the recommended extended-keys-format. Tested with 3.5a and 3.8. |
| The web client | Bun, Rust’s wasm32-unknown-unknown target, and wasm-bindgen-cli at the version crates/kit/Cargo.toml pins, at install time; binaryen’s wasm-opt makes it smaller |
| The Hyprland HUD and dictation frontend | GTK 4.20+ and gtk4-layer-shell |
| Icons | A Nerd Font, optional; every glyph has a text fallback |
git clone https://github.com/vendetta-sh/vendetta.git
cd vendetta
bash install.shinstall.sh puts these in ~/.local/bin:
vendetta,vendetta-app,vendetta-telegram,vendetta-discord,vendetta-host-tmux,vendetta-host-kitty,vendetta-hud-kitty, andvendetta-dictation, with thevendetta-aiderandclaude-masterlaunchers;vendetta-hud, on macOS and on Linux with GTK layer shell, andvendetta-dictation-hyprlandon the latter.
It also:
- creates
~/.config/vendetta/config.tomlandmaster-prompt.mdif they are absent; - installs each provider’s integration, keeps your existing settings, and backs up any provider file it replaces; a provider that is missing or too old is skipped with a note, and you can install it later with the commands below;
- builds the web client if Bun is installed;
- installs the
vendetta,vendetta-pages, andvendetta-alertsagent skills into~/.agents/skills, linked from~/.claude/skillsand~/.codex/skillswhen those exist (Claude’svendettaskill is its Mod’s folder); - runs the scheduler as a systemd user service on Linux, and the worker and scheduler as launchd agents on macOS.
The vendetta skill tells an agent what reaches you away from the terminal: images,
questions, voice and quoted messages, which apps show pages, alerts, and timers, and
follow-ups it schedules for itself. Claude’s Mod and the omp extension add one line
to each session’s system prompt pointing at it.
Put ~/.local/bin on your PATH, then start the worker. The chooser, the apps, and
every plugin get their agents from it:
vendetta notify startTo run it at login, see Notifications.
For a binary-only install, run cargo build --release --locked, adding
-p vendetta-hud -p vendetta-dictation-hyprland for those two, copy the binaries from
target/release/, and install integrations individually with the commands below.
Provider integrations
Section titled “Provider integrations”Integrations report each agent’s lifecycle (working, question, approval, done). Without one, an agent is still found, titled, and navigable, but its state shows as unknown and it never accepts remote input. Codex is the exception: its state falls back to its rollout files.
| Provider | Install | Then |
|---|---|---|
| Codex | vendetta install-hooks |
Trust the hooks under /hooks in Codex. |
| omp | vendetta install-omp |
Restart omp and resume; /reload does not reload extensions. |
| Claude Code 2.1.296+ | vendetta install-claude |
Restart Claude and resume. Idle sessions may also reload it automatically. |
| OpenCode | vendetta install-opencode |
Restart OpenCode. |
| Gemini CLI | vendetta install-gemini |
Restart Gemini and review /hooks. Settings must be strict JSON. |
| Aider 0.86.2 | Run vendetta-aider instead of aider |
Other versions run unobserved with a warning. |
Notes:
- Claude Code gets a native Mod in
$CLAUDE_CONFIG_DIR/skills/vendetta(default~/.claude/skills/vendetta). It keeps Claude’s own UI, reports activity, submits prompts through Claude’s prompt API, and bridgesAskUserQuestionmenus. A prompt sent mid-turn shows at once above Claude’s prompt, marked sent from Vendetta, until it joins the next tool result, as a typed one does, or runs next if the turn ends first. Slash commands run through Claude’s command API as if typed, after any running turn; a name Claude doesn’t know is rejected. Claude titles a session only after a typed prompt, so a new session started by a Vendetta prompt is renamed with a short Haiku title before that prompt runs, so the name shows at once; the prompt is accepted at once and waits only for the title. Titled sessions keep theirs. A session whose first prompt is/goalis named from the goal the same way, and so is the first prompt after/clear, which otherwise keeps the ended conversation’s name; a session started with--namekeeps it. A manager is named from the owner’s request instead of its brief, even after its brief’s turn. A turn that ends on a temporary API error (a dropped connection, overload) is continued after 5 s, 30 s, and 2 min; messaging hides an error only when such a retry followed it. Permission dialogs always stay local; while one is open, the session’s own or a subagent’s, the agent needs approval and takes no remote input, until the call it asks about ends. While subagents Claude lists as working run, a background one after the turn that started it ended included, the agent reads running, their calls in flight among its tool calls, and still takes prompts. Installation does not change authentication, permissions, trust, or other plugins. - omp native questions need omp 18.1.14+, and permission dialogs need a release
with
tool_approval_requested. OpenCode questions need its v2 SDK APIs. - OpenCode attach: with
opencode attach, the plugin runs in the server, so that pane is process-only. - Gemini has no cancel or error hook, so an interrupted Gemini can keep its last state until its next event.
- Aider:
vendetta-aideruses the Python of your existingaider-chatinstall. SetVENDETTA_AIDER_PYTHONif a wrapper hides it. Aider has no conversation ID, so its conversations cannot be resumed.
Upgrading
Section titled “Upgrading”Rerun install.sh. It restarts the scheduler, and on macOS the worker too. Other
running processes keep their old code until restarted:
- On Linux, restart the notification worker.
- Restart omp, OpenCode, and Claude Code agents to load their updated integrations.
Codex and Gemini hooks use the new binary on their next event.
install.sh works the same on macOS 13 or newer, with tmux from Homebrew. There,
launchd runs the notification worker and the scheduler from login, as
dev.vendetta.notify and dev.vendetta.schedule in ~/Library/LaunchAgents,
with the PATH you install from. Its sockets live in ~/.local/state, as macOS
has no XDG_RUNTIME_DIR. Desktop notifications go to Notification Center. The
Kitty and Hyprland pieces are Linux-only. The omp and OpenCode integrations read
/proc, so those agents report no state on macOS yet.
The Vendetta app adds hotkey dictation and draws the HUD.
tmux setup
Section titled “tmux setup”Terminals covers tmux, Kitty, and both together. The tmux host binds
Vendetta’s keys in the server itself, from [plugins.host-tmux.keys], and binds them
again whenever you change them; add nothing to tmux.conf. Each binding passes the exact
client and socket, so the right terminal switches when several clients are attached.
No key is bound until the table names it. If a bound Alt+s does nothing, check
tmux list-keys -T root M-s, and the worker’s log for the
keys table. For a prefix binding, copy a line of
~/.local/state/vendetta/tmux/vendetta.conf into tmux.conf as bind-key s ....
tmux needs [plugins.host-tmux] in your config, which a new install’s config has. The
worker serves one tmux server: tmux’s default, or the one in [plugins.host-tmux] socket.
A chooser on any other server says so instead of opening.
- Alt+w opens the overview; Esc closes it.
- Alt+Shift+A selects the running Master inside an open chooser. Otherwise it switches to the Master’s pane. It never launches anything.
- Alt+Shift+D toggles between the current and previously focused agent. The three hooks keep that focus list in tmux.
- Alt+z shows this project’s agents side by side in their Agents tab, and again zooms the one in focus.
Recommended terminal settings:
set -g default-terminal "tmux-256color"
set -as terminal-features ',xterm-kitty:RGB' # if Kitty true color isn't detected
set -g allow-passthrough on # large provider badges in Kitty
set -sg escape-time 50 # see below
set -s extended-keys on # Shift+Enter for preview typing
set -s extended-keys-format csi-uOver a slow connection, such as SSH from a phone, the terminal’s replies to tmux
queries can arrive in pieces. With a very short escape-time, tmux then types
them into the active pane as text like ?62;22c. 50 ms avoids this; lower it
only for purely local use.
With tmux in Kitty, and without Kitty’s own host plugin, add integrations/kitty.conf for Shift+Enter and for Alt shortcuts that keep working under non-Latin keyboard layouts. The Kitty host’s own file replaces it:
map shift+enter send_text normal,application \x1b[13;2u
map --allow-fallback=shifted,ascii alt+shift+a send_text all \x1bA
map --allow-fallback=shifted,ascii alt+a send_text all \x1ba