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.
Plugins that ship with Vendetta
Section titled “Plugins that ship with Vendetta”| 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.
Claude proxy
Section titled “Claude proxy”[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 onlyThe 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.
Skills and MCP servers you share
Section titled “Skills and MCP servers you share”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 asshared: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 inreviewed; 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 itsheadersHelperprints 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 runsvendetta mcp-bridge SOCKET, its tools namedmcp__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 --forcein 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.
Tailscale
Section titled “Tailscale”[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 answersThe 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:
- 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 endpointtcp:443. A host’s advertisement shows for approval only once its Service is defined. - 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
autoApproversapprove 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.
GitHub
Section titled “GitHub”[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 nameMake 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.
Providers
Section titled “Providers”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.
Services
Section titled “Services”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.
Pages in the apps
Section titled “Pages in the apps”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.
Turning one on
Section titled “Turning one on”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 pluginNames 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).
Commands
Section titled “Commands”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 nonevendetta 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.
Do you need a plugin?
Section titled “Do you need a plugin?”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.
Write one
Section titled “Write one”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 stopTo 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.
What the worker does
Section titled “What the worker does”- Starts it with the
commandargv, and no shell parsing, once for each enabled plugin. Write logs to stderr, sincenotify startdiscards 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
pluginname inhellois only a label. Only the exact process the worker started is supervised: a wrapper script mustexecthe 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.
What a plugin can call
Section titled “What a plugin can call”| 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.
Rules for a plugin
Section titled “Rules for a plugin”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;
resyncmeans 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
idfromlist_agentsworks only on the connection that listed it. To recognize an agent across restarts, use itsconversation_key. - Give slow calls their own connection. A connection answers one request at a time,
so
wait_for_agentor aservice_callto 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_agentanddelete_historyact 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.
Writing one in Rust
Section titled “Writing one in Rust”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.
Troubleshooting
Section titled “Troubleshooting”| 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. |
Adding one to Vendetta
Section titled “Adding one to Vendetta”- Put the crate in
plugins/<name>, with a binary namedvendetta-<name>. Add it todefault-membersinCargo.tomlunless it needs system libraries. - Add the name and its manifest to
SHIPPEDinsrc/plugins.rs, so that it needs nocommand. - Install the binary from
install.sh. - Have its config reject unknown keys while accepting
commandandenabled(and, for one Vendetta does not ship, its manifest keys), as the tmux host’s does. - Test it on owned state, and add it to this page and
config.example.toml.
Writing a host
Section titled “Writing a host”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 withNAME:too. Vendetta routes on that prefix. - A location of an ended lifetime is refused, never reinterpreted.
inputtypes 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_viewportandcurrent_panefind a process from its ancestry or environment. A viewport’spidis what places it inside another host’s window, so a host never needs to know any other.zoomshows a pane with its tab zoomed on it, or with every pane laid out and it in focus; a viewport’szoomedsays which its tab shows.shortcuttakes a desktop-wide key pressed while one of its windows has focus, as its own key there;floatruns 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::Appliednotices 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.