Skip to content
Docs0.9GitHubInstall

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.sh

install.sh puts these in ~/.local/bin:

  • vendetta, vendetta-app, vendetta-telegram, vendetta-discord, vendetta-host-tmux, vendetta-host-kitty, vendetta-hud-kitty, and vendetta-dictation, with the vendetta-aider and claude-master launchers;
  • vendetta-hud, on macOS and on Linux with GTK layer shell, and vendetta-dictation-hyprland on the latter.

It also:

  • creates ~/.config/vendetta/config.toml and master-prompt.md if 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, and vendetta-alerts agent skills into ~/.agents/skills, linked from ~/.claude/skills and ~/.codex/skills when those exist (Claude’s vendetta skill 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 start

To 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.

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 bridges AskUserQuestion menus. 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 /goal is 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 --name keeps 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-aider uses the Python of your existing aider-chat install. Set VENDETTA_AIDER_PYTHON if a wrapper hides it. Aider has no conversation ID, so its conversations cannot be resumed.

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.

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-u

Over 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