Skip to content
Docs0.9GitHubInstall

Running itPlugins that ship

Plugins

A plugin is a separate program that the worker starts, keeps running, and stops with itself. It can be written in any language. It reaches Vendetta only through the worker’s private control socket, where it reads what agents are doing and asks the worker to act. The worker makes every check, so a plugin can ask but never decide.

Plugin What it does Turn it on with Guide
telegram A Telegram topic for each conversation [plugins.telegram] Messaging
discord A Discord channel for each conversation, with status cards [plugins.discord] Messaging
app The endpoint the iPhone and web apps connect to [plugins.app] Apps
hud Cards over every window: agents, tasks, alerts, and your own sections. Hyprland, or macOS with the Vendetta app [plugins.hud] Desktop HUD
hud-kitty A panel in the corner of your Kitty terminal on Hyprland [plugins.hud-kitty], then vendetta-hud-kitty start Kitty HUD
host-tmux tmux as a terminal host: chooser, panes, launches, shortcuts, and tab labels [plugins.host-tmux] Terminals
host-kitty Kitty as a terminal host: chooser, panes, launches, shortcuts [plugins.host-kitty] Terminals
shortcuts Desktop-wide keys on Hyprland and macOS, for actions Vendetta and its plugins offer by name; brings windows forward for the worker (focus_window) [plugins.shortcuts] and its keys Anywhere on the desktop
speech Speech to text for voice notes and dictation, and the voice the apps read replies in [plugins.speech], with its transcription and narration tables Voice
dictation Push-to-talk into the focused agent or window [plugins.dictation], with keys for its actions in [plugins.shortcuts] Dictation
ntfy Alerts on your phone through an ntfy topic [plugins.ntfy] url Notifications
webhooks URLs that run a schedule when a service calls them [plugins.webhooks] and its hooks Webhooks
claude-proxy Your Claude login, and your git login for the hosts you list, for machines and instances, through Unix sockets of their own, never a copy [plugins.claude-proxy], and its git table Claude proxy, machines
github Your own GitHub account, connected from Settings → Connections (or vendetta providers connect github): your repositories for new projects, and github.com git for you and your machines from your token [plugins.github] client_id GitHub, providers
personal-hub Your Personal Hub tasks for the chooser, apps, and HUD as the tasks service, and its reminders and captures as the Master’s schedules [plugins.personal-hub] with your vault Tasks, protocol
dashboard The apps’ Overview: lanes of agents by what they need, filters, notices, and what comes up, as a plugin page [plugins.dashboard] Overview
diff Changes: each agent’s committed work on its branches, by revision, with merged state, commit links, and the owner’s line comments, as plugin pages [plugins.diff] Changes
tailscale Your app endpoint and each instance’s on the tailnet: by port, and at its own name (vendetta.TAILNET, vendetta-ana.TAILNET) [plugins.tailscale] Tailscale

./install.sh puts them beside vendetta. On Linux, hud is built only when GTK 4 and gtk4-layer-shell are installed.

Two more programs in plugins/ belong to dictation, and the worker does not supervise them: vendetta-dictation-hyprland, which the dictation plugin starts for each session, and the macOS app, which you start yourself.

Provider integrations, such as hooks, the omp extension, and Claude’s Mod, are a different thing: they run inside an agent to report its status. See Install.

[plugins.claude-proxy]
# credentials = "~/.claude/.credentials.json"  # read by the plugin alone, never written
# claude = "~/.local/bin/claude"               # runs `claude auth status` near expiry; default: on PATH, else this
# upstream = "https://api.anthropic.com"       # the API it forwards to; http:// only to loopback

# Your git login for a host, for every machine and every instance that takes it.
[plugins.claude-proxy.git.hosts."git.example.dev"]
username = "you"
token = { command = ["/home/you/bin/forge-token"] }  # prints the token; or { env = "NAME" }
env = { PROTON_PASS_AGENT_REASON = "Vendetta git proxy" }  # set for the command only
push = true                                    # false: clone and fetch only

The token command runs as you, in the plugin, on the first git request; its output is kept in memory only, never written or logged, and its stderr is dropped. It runs with the plugin’s environment, each env variable over it, and, when neither names one, your session bus (DBUS_SESSION_BUS_ADDRESS, XDG_RUNTIME_DIR), which a password manager needs: set its settings (for Proton Pass, PROTON_PASS_KEY_PROVIDER and PROTON_PASS_LINUX_KEYRING) in env. A command that fails is not run again for 30 seconds; git sees 502 and the plugin’s log says the login is unavailable. A token the host refuses (401) is loaded again once it is 5 minutes old; git sees 403 until then. Change the command to change the token; the plugin restarts with it.

Each target (a machine, an instance’s host, an instance’s machine) gets git.sock and a gitconfig beside claude.sock. The gitconfig sends each listed host’s https://, ssh://git@, and git@HOST: remotes to http://vendetta-git/HOST/ through git.sock as a SOCKS5 proxy (socks5h://localhost/PATH). The plugin accepts only that, only git’s clone, fetch, and push requests (info/refs, git-upload-pack, git-receive-pack) for OWNER/REPO on a listed host. It drops the client’s credentials, cookies, and framing, adds Authorization: Basic with your username and token, and streams to https://HOST. It answers itself with 403 for anything else (the host’s API, Git LFS, a push to a host with push = false), and keeps the host’s cookies and challenges from the client. Each target has at most 8 git connections, a person 24, and the plugin 64. Each request is logged with its target, host, repo, status, and size, never a header or body. See machines and instances.

The same plugin reads your Claude Code skills (~/.claude/skills, ~/.agents/skills, and enabled plugins’) and MCP servers (~/.claude.json’s user scope and enabled plugins’) and shares the ones you pick, one by one, with each person, everyone, or your own container projects: People in the apps, or vendetta instance pick. Nothing is shared until you pick it.

[plugins.claude-proxy.share]           # optional: these are the defaults
# claude_dir = "~/.claude"
# agents_dir = "~/.agents"
# claude_json = "~/.claude.json"
# reviewed = ["glab/references/troubleshooting.md:SHA256"]  # a flagged file you checked
  • Skills are copied into each target’s shared/plugin, a Claude plugin its Claude loads (CLAUDE_CODE_PLUGIN_DIRS), listed as shared:NAME. A skill with a file named like a credential (.env, *.pem, *credentials*, …), something shaped like a token or a private key, a link outside it, or more than 32 MiB or 4,000 files is never shared; the picker says which file. A flagged file you checked is cleared by its path and its content’s SHA-256 in reviewed; any change flags it again.
  • MCP servers run on your side, as you: a stdio server is started for each connection with its command and environment, an HTTP one reached with its headers (or what its headersHelper prints within 10 seconds). A server that won’t start shows as unavailable (“Couldn’t start”) in your picker, why in the Claude proxy’s log only; their Claude is told “NAME couldn’t start on YOUR side”, and it starts for them once it can. The target’s Claude runs vendetta mcp-bridge SOCKET, its tools named mcp__plugin_shared_NAME__TOOL. The definition never leaves the plugin. A server with Claude’s own sign-in (oauth) or the old SSE transport can’t be shared. A shared server acts as you: whoever you share it with can do with it what you can.
  • Your changes reach everyone at once, with no restart: a new skill or server shows in the picker; an edited skill is copied again and each idle session reloads its plugins, and the model of a running session is told of skills that came or went before its next prompt; a changed server is restarted and the bridge tells Claude to list its tools again; a removed one goes, and once it has been gone a minute it is unpicked everywhere, so adding it back shares it with no one until you pick it again. A running conversation gets a newly shared server only once reloaded: People’s “Reload their sessions” (or vendetta instance reload NAME) runs /reload-plugins --force in each of their sessions that predate it, once idle, never one working, asking, or awaiting approval, and their chat says “Reloaded to pick up new tools from YOU”. Their next message in it is not cached. A session it cannot reach (no Mod connection, or the reload is refused or never confirmed) gets “Restart this conversation to use the new tools from YOU” in its chat instead, once.
  • People’s picker says how many of their machines’ sessions use each shared server now.
  • A machine’s own skill or server of the same name wins, a person’s and your container projects’: yours is left out there, and the picker says where.
[plugins.tailscale]
# admin = "vendetta-workstation"       # your name; default vendetta-HOST; "" serves you by port only
# prefix = "vendetta-workstation-"     # each person's: svc:vendetta-workstation-ana; "" serves them by port only
# tailscale = ["tailscale"]     # run as its operator: sudo tailscale set --operator=$USER, once
# curl = "curl"                 # checks a name answers

The plugin serves your app endpoint (the port of whichever plugin serves endpoint: the app plugin’s [plugins.app] listen) and each instance’s on its port (tailscale serve --https=PORT) and, on a tagged machine, as a Tailscale Service at its own name, port 443 (tailscale serve --service=svc:NAME). Every 30 seconds it checks that each name answers with an HTTPS request from this machine. A Service name belongs to the whole tailnet, so the default names carry this machine’s tailnet name (HOST in HOST.tailnet.ts.net): vendetta-workstation and vendetta-workstation-ana on workstation.

A new name answers only once a tailnet admin has defined its Service and approved this machine as its host. Until then the address in use stays the port’s, and vendetta instance list and People in the apps say so, naming each one:

  1. Define each name, once: in the admin console’s Services, Advertise, then Define a Service, with its name (vendetta-workstation, vendetta-workstation-ana, …) and the endpoint tcp:443. A host’s advertisement shows for approval only once its Service is defined.
  2. Approve this machine as each name’s host there, or add the snippet they show to the tailnet policy, once for every current name: its autoApprovers approve this machine’s tag as their host, and its grant lets the tailnet’s members reach them.
"autoApprovers": {
  "services": {
    "svc:vendetta-workstation": ["tag:server"],
    "svc:vendetta-workstation-ana": ["tag:server"]
  }
},
"grants": [
  {"src": ["autogroup:member"], "dst": ["svc:vendetta-workstation", "svc:vendetta-workstation-ana"], "ip": ["tcp:443"]}
]

The host must be a tagged machine (tailscale up --advertise-tags=…): Services are hosted only by tagged nodes, and the plugin serves names only there. People who reach this machine through a node share, not as members of the tailnet, may not reach its Services: their devices keep the port address.

Once a name answers, the worker makes it the address in use, kept in its state (yours in your state folder, each person’s in theirs), never in a config. New pairing codes, QR links, page links, and web addresses use the name from then on; messaging reads it when it starts and when pairing (app_address), and a person’s worker restarts to take it. The port entry stays, so devices paired at it keep working. A name that misses three checks in a row, at least five seconds apart, goes back to the port. Only an address that is a target’s own port or name address moves; a public_url you set to anything else stays in use.

The plugin changes only what it serves for a target (tailscale/owned.json in the state directory), takes over an existing port entry that already proxies to the target, and never touches another entry. When an instance goes, so do its port and its name. An untagged machine, or a failing tailscale, leaves names off with the reason, and the ports work as before. Vendetta itself never runs tailscale: without the plugin, nothing serves a person’s endpoint beyond this computer, and instance add says so.

[plugins.github]
client_id = "Ov23li..."   # your GitHub OAuth App's client ID: public, no secret
# host = "github.com"     # or a GitHub Enterprise Server's host name

Make the OAuth App once at github.com/settings/developers → New OAuth App (any homepage; the callback is unused, such as http://127.0.0.1/), then tick Enable Device Flow. instance add and update give people the same client_id while the plugin runs (it declares it as a setting people take); each person connects their own account.

Connect from Settings → Connections, or vendetta providers connect github, which prints GitHub’s code and address. The token, with scope repo, stays in your state folder (github/account.json, 0600) and the plugin’s memory: never in a log, a machine, or anyone else’s Vendetta. While connected, https://github.com/, ssh://git@github.com/, and git@github.com: remotes go through your token for your git and your machines’ (the worker includes the plugin’s gitconfig), New project lists your repositories, and a new machine’s clone of a github.com repo keeps it as origin. Disconnect forgets the token here; GitHub keeps the grant until you revoke it at github.com/settings/applications. With host set, the same holds for that server: its web and git at https://HOST, its API at https://HOST/api/v3, and the OAuth App made there.

A plugin can be a provider: something a person connects (an account, a key) which then serves the rest of Vendetta. It shows itself with plugin UI: a connections contribution whose page holds a provider node (status, a connect flow, its actions), and a new_project contribution for a project source; devices and vendetta providers act on them with ui_call, which the plugin reads with ui_take and answers with ui_reply. A provider that serves a git host declares it with set_providers (git_host), serves git on sockets in the folders provider_targets names, and the worker includes them. See protocol; the GitHub plugin is one.

A plugin can serve methods the rest of Vendetta calls: the worker, other plugins, the chooser, and agents. It declares them with set_services, naming who may call each (plugin, owner, master, any; the worker always may), a deadline, and size bounds; the worker checks every caller and carries each call as a service_call event the plugin reads with service_take and answers with service_reply. A call is never resent. A plugin that serves something may also raise its change event (raise_event) and keep schedules of its own under its name (schedule_upsert, schedule_remove). See protocol; tests/services.py runs a scripted one.

Serving the tasks service (projection, task_mutate, and the tasks event) makes a plugin the task source every client shows.

A plugin can add buttons and pages to the web and iPhone apps, as data the apps draw with their own pieces: no HTML or script of the plugin’s reaches them. It contributes to a slot, nav (beside Chats) or chat_menu (a chat’s actions menu), with ui_set_contributions, and publishes pages of keyed nodes with ui_set_page, the whole page each time: the worker sends the apps only what changed, and a node that keeps its key moves rather than reappearing. A click opens a page, goes to an app page, sets the page’s filter, or calls the plugin, which reads the call with ui_take and answers with ui_reply; the call carries the arguments the plugin published, never the device’s.

{"method": "ui_set_contributions", "params": {"contributions": [
  {"id": "note", "slot": "chat_menu", "label": "Add note", "on": {"action": "note"}}]}}
{"method": "ui_set_page", "params": {"page": "notes", "title": "Notes", "root": "top", "nodes": {
  "top": {"kind": "list", "empty": "No notes yet", "children": ["n1"]},
  "n1": {"kind": "row", "title": "Ship it", "on": {"navigate": {"tasks": {}}}}}}}

Plugin UI lists the slots, layouts, and elements; the protocol the methods; tests/plugin_ui.py runs a scripted one, and plugins/dashboard is the Overview.

Each plugin is a table in ~/.config/vendetta/config.toml:

[plugins.host-tmux]       # enough for a plugin that ships with Vendetta

[plugins.alert-log]
command = ["/home/you/bin/alert-log", "--verbose"]  # argv, not a shell line
enabled = true            # the default; false keeps the table but does not run it
path = "~/alerts.log"     # every other key belongs to the plugin

Names start with a lowercase letter and hold lowercase letters, digits, and hyphens, up to 64 characters. command is required for a plugin Vendetta does not ship.

More keys are the plugin’s manifest, which the core reads before it runs it. Set them only for a plugin Vendetta does not ship; Vendetta sets its own plugins’:

host_only = true          # works on this computer's terminals or desktop, or serves you alone:
                          # a person's Vendetta (docs/instances.md) refuses to run it
delivers_alerts = true    # it calls deliver_notifications: `vendetta notify test` fails
                          # while it is enabled and not running
exposes = true            # a role, below
proxies = true            # a role, below
serves_apps = true        # a role, below
live_keys = true          # it reads its [plugins.NAME.keys] again itself when they change:
                          # a change to them alone does not restart it

[[plugins.NAME.commands]] is manifest too: the vendetta commands it registers (below).

A plugin can add commands to vendetta: vendetta NAME ARGS... runs it, in place of vendetta, with the same terminal, stdin, stdout, and stderr, and exits with its code. Declare each in its table:

[plugins.notes]
command = ["/home/you/bin/notes"]

[[plugins.notes.commands]]
name = "notes"                 # vendetta notes ...
description = "Your notes"     # one line, for vendetta --help
args = ["cli"]                 # after the plugin's command; default none

vendetta notes add milk runs /home/you/bin/notes cli add milk, after any --config, --socket, and --client given to vendetta ahead of the name. vendetta notes --help is the plugin’s help. Commands come from the config on disk, so they work while the worker is stopped, and only an enabled plugin’s. vendetta --help lists them under their own heading. A name vendetta has built in, or one two plugins claim, registers nothing; vendetta config check and the worker’s log say so.

Vendetta’s own: vendetta tui, the chooser, on unless [plugins.tui] enabled = false, vendetta app (pair, devices, revoke, recovery) while [plugins.app] is on, vendetta telegram recovery and vendetta discord recovery while theirs are on, and vendetta diff (changes) while [plugins.diff] is on.

A role lets one plugin take over a job Vendetta’s own plugin does, such as exposing your app through Cloudflare Tunnel or Caddy in place of Tailscale. At most one enabled plugin holds each role, so turn Vendetta’s off (enabled = false) when yours takes it.

Key Vendetta’s The plugin may call
exposes tailscale expose_targets, expose_report; it subscribes to expose (protocol)
proxies claude-proxy proxy_targets, proxy_report, share_items_report; it subscribes to proxy (protocol)
serves_apps app Nothing new. A person’s Vendetta (instances) sets its table’s listen and public_url, and pairs their devices by running its command with --config FILE pair --json, which prints {"code", "qr", "web_url", "expires_ms"} and works while the worker is stopped

The worker applies a saved config by itself: it starts a plugin turned on, stops one turned off, and restarts one whose table changed (Configuration). Check the plugin’s state:

vendetta notify status
State Meaning
starting It has not reported yet.
running It reported that it is ready.
unavailable It exited and is waiting to restart, could not start, or reported this itself.

A plugin’s stderr goes to the worker’s log, ~/.local/state/vendetta/notifications/worker.log, which each notify start empties, or to the journal under a service manager.

Plugins run as you, with your permissions and no sandbox. Enable only programs you trust.

Often something smaller will do:

To Use
Show your own data in the HUD A command section: a program that prints JSON
Support dictation on another desktop A dictation frontend
Let an agent see and drive other agents vendetta agent
Run a prompt later or on a schedule vendetta schedule
Run an agent when a service calls a URL Webhooks, which ship with Vendetta
Sound an alert on your apps from a script vendetta alert

Write a plugin for something that should keep running with the worker and react to your agents, such as a new chat platform or a status light.

This plugin writes a line to a file for each alert. It needs Python 3.11 or newer and nothing else. Save it as alert-log.py:

#!/usr/bin/env python3
"""A Vendetta plugin that writes a line to a file for each alert."""
import json, os, socket, sys, threading, tomllib

# The worker names its config file; this table is the plugin's own to read.
with open(os.environ["VENDETTA_CONFIG"], "rb") as file:
    settings = tomllib.load(file)["plugins"]["alert-log"]
path = os.path.expanduser(settings["path"])


# The worker holds the other end of stdin. End of file means it is gone.
def exit_with_worker():
    sys.stdin.read()
    os._exit(0)


threading.Thread(target=exit_with_worker, daemon=True).start()

control = socket.socket(socket.AF_UNIX)
control.connect(os.environ["VENDETTA_CONTROL_SOCKET"])
stream = control.makefile(encoding="utf-8")
last_request = 0
events = []  # Events that arrived while waiting for a response.


def read_frame():
    line = stream.readline()
    if not line:
        sys.exit("The worker closed the connection")
    return json.loads(line)


def call(method, params=None):
    global last_request
    last_request += 1
    request = {"type": "request", "id": last_request, "method": method, "params": params or {}}
    control.sendall(json.dumps(request).encode() + b"\n")
    while True:
        frame = read_frame()
        if frame["type"] == "event":
            events.append(frame["event"])
        elif "error" in frame:
            sys.exit(f"{method}: {frame['error']}")
        else:
            return frame.get("result")


def alerts():
    return call("notifications")["notifications"]  # Newest first.


call("hello", {"plugin": "alert-log", "protocol": 1})
call("subscribe", {"topics": ["notifications"]})  # Before the first read, so nothing slips by.
seen = max((alert["id"] for alert in alerts()), default=0)  # Earlier alerts stay unlogged.
call("report_health", {"state": "running"})

while True:
    if not events:
        read_frame()  # Blocks until the next event, which says only that something changed.
    events.clear()
    for alert in reversed(alerts()):
        if alert["id"] > seen:
            seen = alert["id"]
            with open(path, "a") as log:
                print(alert["at_ms"], alert["agent"], alert["event"], file=log)

Try it on a throwaway worker, which leaves your own setup alone. In a new shell, from the file’s folder:

root=$(mktemp -d)
mkdir -p "$root/config/vendetta" "$root/state" "$root/run"
cat > "$root/config/vendetta/config.toml" <<EOF
[master]
socket = "$root/tmux.sock"

[plugins.alert-log]
command = ["python3", "$PWD/alert-log.py"]
path = "$root/alerts.log"
EOF
export XDG_CONFIG_HOME="$root/config" XDG_STATE_HOME="$root/state" XDG_RUNTIME_DIR="$root/run"

vendetta notify start
sleep 2
vendetta notify status   # plugins: alert-log=running
vendetta notify test
sleep 1
cat "$root/alerts.log"   # 1793... Vendetta test
vendetta notify stop

To keep it, add the [plugins.alert-log] table to your own config and restart your worker.

A throwaway worker still lists agents you run outside tmux, since it finds agents among your processes. Read them if you like, but test anything that sends input against an agent you started for the test. tests/plugin_supervision.py runs this example, and is a starting point for a test of your own.

  • Starts it with the command argv, and no shell parsing, once for each enabled plugin. Write logs to stderr, since notify start discards stdout. The working directory is whatever the worker’s was, so don’t rely on it.
  • Gives it VENDETTA_CONTROL_SOCKET, the socket to connect to; VENDETTA_CONFIG, the config file it loaded; and stdin, a pipe that stays open for as long as the worker lives.
  • Trusts it by pid and start time, as the kernel reports them for the connection. The plugin name in hello is only a label. Only the exact process the worker started is supervised: a wrapper script must exec the plugin, because a child it forks is not.
  • Restarts it when it exits: after 1 second, doubling up to 60, and back to 1 second once it has stayed up for a minute.
  • Stops it by closing stdin and sending SIGTERM, then SIGKILL after 20 seconds. If the worker dies no signal comes, only stdin and the connection closing, so exit on end of file.
Caller Can call
Any process of yours The agent tools (list, read, send, interrupt, create, resume, schedules), questions, progress, history, alerts
Supervised plugins and your chooser The overview, project colours, live terminal screens, schedule snapshots, confirmed deletions, answering approvals
Supervised plugins only Health reports, speech to text, dictation reports, deletion requests, webhook runs, their own services and schedules, prompts to an agent in their own name

A plugin that needs to tell an agent something calls plugin_prompt {id, text, label?} with an id from its own list_agents: the chat shows the prompt as the plugin’s, under label (else the plugin’s name), never as yours, and the agent reads it as a prompt like any other. A plugin’s own command, run by an agent (vendetta NAME), reaches it with plugin_call, which says which agent asks.

Being supervised keeps other clients from these methods by accident. It is not a security boundary, since anything running as you can do what you can. The protocol has every method and event.

Vendetta’s own plugins follow these.

  • Subscribe, then read. Events say what changed, never the new data. Subscribe before your first read and reread on each event; resync means events were lost, so reread everything.
  • Start from a baseline. A plugin restarts whenever the worker does. Treat what exists when it starts as already handled, and never replay it.
  • Never repeat an uncertain request. If the connection ends or times out after you wrote a request, the worker may have acted, and a retry could send a prompt twice. Report it instead. An error response is a definite answer; these are not.
  • Tie handles to their connection. An id from list_agents works only on the connection that listed it. To recognize an agent across restarts, use its conversation_key.
  • Give slow calls their own connection. A connection answers one request at a time, so wait_for_agent or a service_call to transcribe would hold up everything behind it.
  • Exit instead of hanging. Put a limit on anything that can block, and exit when stuck or when the connection ends, so the worker restarts you.
  • Treat agent text as untrusted. Transcripts and terminal screens can contain anything. Never run them, or render them as markup.
  • Leave decisions to the person. No method answers a provider’s permission dialog. close_agent and delete_history act at once, so show what they will do and get confirmation first.
  • Keep what agents say private. Alerts and transcripts hold your agents’ words. Keep them out of logs and files unless that is the plugin’s job, as the example does by writing only who and what.

vendetta-protocol has the client and the wire types, and vendetta-ui-common adds the rest of what a plugin’s main loop needs. They are not on crates.io, so depend on a checkout:

[dependencies]
anyhow = "1"
vendetta-protocol = { path = "../vendetta/crates/protocol" }
vendetta-ui-common = { path = "../vendetta/crates/ui-common" }
use anyhow::{Result, ensure};
use vendetta_protocol::{Heartbeat, State, exit_on_panic};
use vendetta_ui_common::plugin::{Feed, terminating, watch_termination};
use std::time::Duration;

fn main() -> Result<()> {
    exit_on_panic();
    watch_termination()?;
    // Connects, subscribes to agent changes, and reports `running`.
    let mut feed = Feed::connect("agent-count")?;
    // Exits the process if the loop stops beating, so the worker restarts it.
    let heartbeat = Heartbeat::new("agent-count", Duration::from_secs(120));
    while !terminating() {
        heartbeat.beat();
        feed.wait(Duration::from_millis(200))?;
        ensure!(!feed.closed(), "The worker closed the connection");
        if feed.dirty() {
            let agents = feed.agents()?;
            let running = agents.iter().filter(|agent| agent.state == State::Running).count();
            eprintln!("{running} of {} agents running", agents.len());
        }
    }
    Ok(())
}

For other methods, vendetta_protocol::Client has call, call_timeout, subscribe, and next_event, and uncertain(&error) tells you when a request must not be repeated. vendetta_ui_common::plugin::load_config parses the config file the worker named. plugins/host-tmux is the smallest real plugin to read.

What you see Why
Stuck on starting It never called report_health, or a wrapper forked it instead of using exec.
report_health is only available to supervised plugins The process that connected is not the one the worker started: exec it, or run it from the worker rather than by hand.
unavailable It exited. The worker’s log says why.
The connection closes with no response A malformed frame, a field the protocol does not have, or an unknown subscribe topic.
vendetta refuses the config A bad plugin name, an empty command, no command for a plugin Vendetta does not ship, a manifest key on one it does, two enabled plugins with the same role, or a host_only plugin in a person’s config.
  1. Put the crate in plugins/<name>, with a binary named vendetta-<name>. Add it to default-members in Cargo.toml unless it needs system libraries.
  2. Add the name and its manifest to SHIPPED in src/plugins.rs, so that it needs no command.
  3. Install the binary from install.sh.
  4. Have its config reject unknown keys while accepting command and enabled (and, for one Vendetta does not ship, its manifest keys), as the tmux host’s does.
  5. Test it on owned state, and add it to this page and config.example.toml.

A host gives Vendetta a terminal or multiplexer: it lists panes, reads and types into them, launches in them, and shows them. Name the program vendetta-host-NAME and put it beside vendetta.

A host is a plugin that serves a Unix socket at $XDG_RUNTIME_DIR/vendetta/hosts/<control socket's name>-NAME.sock, mode 0600 in a 0700 directory, with one JSON line per request and per response:

{"method":"screen","params":{"pane":{"server":"NAME:...","target":"s:w.p"},"viewer_tty":null}}
{"ok":{"text":"...","width":80,"height":24,"cursor_x":0,"cursor_y":0,"cursor_visible":true}}
{"error":"That terminal has closed"}

Host protocol is the wire contract: identities, types, and every method. Rust hosts implement Backend in crates/host and call vendetta_host::rpc::serve.

The rules:

  • Server identities are NAME:ADDRESS,PID,START,BOOT, and a viewport’s ID starts with NAME: too. Vendetta routes on that prefix.
  • A location of an ended lifetime is refused, never reinterpreted.
  • input types only if the pane’s root process is still the pinned pid and start time, checked where nothing can replace it before the write.
  • current_viewport and current_pane find a process from its ancestry or environment. A viewport’s pid is what places it inside another host’s window, so a host never needs to know any other.
  • zoom shows a pane with its tab zoomed on it, or with every pane laid out and it in focus; a viewport’s zoomed says which its tab shows.
  • shortcut takes a desktop-wide key pressed while one of its windows has focus, as its own key there; float runs a command floating over whatever window has focus. Both say false when they cannot.
  • It binds Vendetta’s shortcuts in its terminal from [plugins.host-NAME.keys], and binds them again when the table changes, without a restart; vendetta_host::keys::Applied notices the change and writes the terminal’s file in Vendetta’s state directory. Forward a key only to a connection to another machine or to an open chooser.