Skip to content
Docs0.9GitHubInstall

Building on itPlugin protocol

Control protocol

The reference for the notification worker’s control socket, the only way plugins reach Vendetta. Plugins explains what they are and how to write one. The core performs every check; a plugin can ask, never decide.

Rust plugins use vendetta-protocol (crates/protocol): Client, the wire types, Provider, and shared data such as questions and session profiles.

Any process of yours can connect. What it may call is checked on every call against the peer’s pid and start time from SO_PEERCRED, never a request field:

  • Any client: the agent tools and the first table of additional methods.
  • Supervised plugins: the exact processes the worker started.
  • Not an agent: any process of yours that no agent of this worker runs, with no agent among it and its ancestors. A provider whose environment names another state directory, as an owned test’s does, is another worker’s. Reads and colours (overview, project_colors, canvas_color, schedule_snapshot, window_viewports) and desktop focus (focus_agent, focus_window, focus_machine_agent) need no more, so keys, links, and the owner’s scripts keep them.
  • The owner: not an agent, on a terminal a person sees. Its controlling terminal is a host’s pane in a tab a viewport shows (only that pane when the tab is zoomed), whose terminal process no agent runs; or a popup of a host’s server, such as the chooser’s in tmux, with such a viewport of that server; or, outside every host (a plain terminal, sshd), a terminal whose holders no agent runs. A process with no terminal (tmux run-shell -b, setsid, cron, a timer), a pane in a detached window, session, or background Kitty tab, and a terminal an agent draws are not. Checked at a connection’s first owner call and kept once granted; a refused connection is checked again at its next, so a chooser opened in a hidden window works once shown. A refusal starts owner_only: and says why and what to do. Changes to trust, deletions, teams, keeping, schedules of the Master, screen, the owner’s close_agent, resume_agent, and quit commands of a declared agent, administration, machines, and owner-kind service calls are the owner’s. No setting extends it to terminal-less callers; the apps reach it through the app plugin.

Same-user processes are never a security boundary: an agent can still type into the owner’s pane or show a window of its own on the owner’s screen. These rules keep it from owner rights by accident or out of sight.

One JSON object per line on a Unix stream socket, at most MAX_FRAME (160 MiB) bytes. The socket is $XDG_RUNTIME_DIR/vendetta/control/<hash>.sock, one per state directory (so one per user), mode 0600; peers must share the worker’s uid.

{"type":"request","id":1,"method":"list_agents","params":{}}
{"type":"response","id":1,"result":{"agents":[]}}
{"type":"response","id":2,"error":"Unknown agent"}
{"type":"event","seq":4,"event":{"kind":"transcript","process_key":"..."}}

The first request must be hello {"plugin":"name","protocol":1}, which replies {protocol, tmux_socket}; plugin is only a label. Each connection owns its agent handles: an id from list_agents is valid only on the connection that listed it. A connection answers one request at a time, so give slow calls their own. A malformed frame ends the connection without a response.

An error response means the core reports the outcome. A connection that ends, or a timeout, after a request was written is uncertain: the core may have acted. Client returns Uncertain for that case. Never repeat an uncertain mutation.

subscribe {"topics":["agents","transcripts","history","deletions"]} once per connection. Topics are the events below, with transcripts for transcript; resync always comes. An unknown topic ends the connection without a response. Events say what changed, never the new data; reread it through the methods below. On a subscribed connection, list_agents and list_history may answer from the worker’s scan of the last 250 ms, so the reread an agents event prompts lists the scan that published it; a later change brings another event. Unsubscribed connections always scan afresh.

Event Meaning
agents An agent appeared, exited, or changed state, title, question, or typed input.
transcript {process_key} That agent’s transcript grew or was replaced.
history The lifecycle history changed.
deletions A local deletion request changed.
tasks The owner’s tasks changed; the plugin serving tasks raises it.
dictation A dictation started, changed, or ended.
notifications An alert arrived, or one came due for plugins that push it.
alerts An agent’s alert was set, came due, or was cancelled; read it through alerts.
live A Live Activity started, changed, or ended; read them through live.
canvas A project’s color changed; reread project_colors.
teams {teams: [{manager, members: [key], choices}], managers: {key: [key]}}, members in the order they joined, and each member’s managers oldest first. A member with several managers is in each of their members; a sub-manager is one team’s manager and others’ member.
actions The actions the worker and plugins offer for keys changed; reread actions.
prompts A prompt send_message accepted was read or dropped; reread prompts.
machines A project machine started, stopped, or its link or runtime changed; reread list_machines. agents and history follow.
project_files A project file appeared, changed, or was trusted, or a declared agent’s state changed; reread project_files. agents and history follow.
people The people this worker knows, or whether their workers answer, changed; reread people.
shares A share was given, changed, or ended, here or by another person; reread shares. agents and history follow.
jobs A job moved a step; reread jobs.
proxy The proxy’s targets changed; the plugin that proxies rereads proxy_targets.
claude_login The Claude proxy reported; reread claude_login.
expose What is exposed changed; the plugin that exposes rereads expose_targets.
notes A one-line note for an agent’s chat was written; read them through agent_notes.
person_notes {conversation_key} Topic transcripts: a note between people of that shared chat was written or removed; reread person_notes.
choosers A full chooser opened or closed; reread window_viewports.
focus_master {pid} Topic choosers: the chooser of process pid selects the Master, as the Master key pressed where it shows asks.
services A plugin’s services appeared, changed, or went; reread services.
service_call {call, service} A service call waits for its plugin (topic service_calls).
service_cancelled {call} A service call’s caller stopped waiting (topic service_calls).
resync Events were lost; reread everything.

Subscribe before the first full read. seq counts from 1 per connection; the client turns a gap into resync.

Agent tools, which vendetta agent calls (its --help describes their arguments): list_tmux_sessions, list_agents, read_agent, read_agent_messages, send_message, interrupt_agent, close_agent, create_agent, bind_session_profile, list_history, resume_agent, rename_agent, wait_for_agent, the team tools team, assign_agents, release_agents, and mute_agents, keep_agents, ephemeral_agents, delete_agent, auto_delete_plan, notify_reply, set_agent_plan, agent_plan, launch_options, and the schedule tools: list_schedules, create_schedule, update_schedule, delete_schedule, enable_schedule, disable_schedule, run_schedule, schedule_history, scheduler_status, start_scheduler, and stop_scheduler. Guards against an agent controlling itself check the calling process and its ancestors.

agent_in_window {pid} answers {agent, in_window}: the one agent the desktop window of process pid shows, in the pane its terminal’s innermost host shows or running in it outside every host, else null; several candidates are null too. With no terminal or agent in that window, in_window is false and the agent is the one in the most recently used viewport. Dictation uses it to pick its recipient on any host.

Clients open agents and move desktop focus through the worker, never by asking a host or the desktop themselves. The worker shows panes through its hosts and moves focus through the plugin that serves focus_window (the shortcuts plugin, on Hyprland and macOS); without one, they fail with focus_unavailable. Supervised plugins and callers no agent runs may call focus_agent and focus_window, terminal or not; an agent is refused.

Method Result
focus_agent {id} or {process_key}, viewport? Opens a live agent where the owner is: an agent in a host’s pane in viewport, else in the terminal of the focused desktop window, else in the most recently used viewport, whose window then comes forward; an agent outside every host by bringing its terminal’s window forward. {viewport, raised}. The HUD and vendetta open use it.
focus_window {pid} Brings forward the desktop window holding process pid: its own, or an ancestor’s, the one focused most recently. {}.
chooser_shown {client?} Any client, on its own connection: a full chooser shows on the caller’s terminal (its standard input, as the kernel says), client the viewport a popup started from, until the connection ends. Publishes choosers.
chooser_focus_master {viewport} Any client: the Master key in viewport. When a chooser shows in its active pane, still on that pane’s terminal, publishes focus_master to it: {forwarded: true}; else {forwarded: false}, and the caller shows the Master itself. A terminal that routes the key itself is never forwarded. vendetta master-focus and the hosts’ Master key call it.
window_viewports {pid} For supervised plugins and callers no agent runs: {viewports: [{id, width, height, chooser}]}, every host’s viewport inside the desktop window of process pid, outermost first, chooser whether a full chooser shows in it (in a pane of the tab it shows, unless the tab shows only another pane, or floating over it). The Kitty HUD hides by it; choosers says when to ask again.
master_location {project?} Where the Master agent’s own pane is, in project (the caller’s [master] project, else the worker’s): {location: {server, target}}, never merely its project’s selected terminal; refused while it is not running or runs in more than one pane. vendetta master-focus shows it.
agent_location {pane} Where the live agent in exactly pane (%12) is: {location}; a pane with no live agent is refused. vendetta agent-focus shows it.
previous_agent {viewport?} The most recently focused live agent other than the one viewport shows, else the first other in the HUD’s order: {location}, null when no other runs. vendetta last-agent shows it.
open_project {entry} The owner’s: a project header’s session for a list_history entry: {location}, the existing session named for its project, else a new shell session in the directory it recorded. It never resumes a conversation.

list_history {limit?, conversation_key?} lists the newest conversations; with conversation_key, only that conversation, found in every record of the history’s seven days, so one that newer agents pushed out of a listing can still be resumed.

rename_agent {id | conversation_key, name} keeps an owner’s name for a live or recorded conversation in the state directory’s names.json; list_agents, list_history, and everything built on them show it as title (list_history marks such entries named), and an empty name removes it. A manager whose provider is not Claude shows, until then, a name from the owner’s request (its first sentence, at most 50 characters), kept in requested-names.json; any rename_agent, an empty one too, ends it. Changing it publishes agents and history; messaging retitles live topics and named exited ones. The Master, live or exited, is always titled Master and refuses a name.

send_message {id, text, require_idle?, origin?}’s receipt for an accepted prompt adds prompt, an id, and delivery: waiting until the prompt is in the agent’s input, then read, or dropped when the agent will never read it, as when Claude refuses a held prompt after Escape in its terminal or the agent exits first. Each change publishes prompts. Claude’s Mod reports it; Codex and omp are read when their transcript shows the prompt as user input. Other providers and slash commands carry no delivery.

The worker records who sent each accepted prompt other than a slash command: owner (the owner, a supervised plugin, a caller no agent runs), agent (a caller an agent runs, with its conversation_key and title as name), or worker (a manager’s brief, a team change, the relay’s updates, named Manager brief, Team change, and Team update), or plugin (a supervised plugin’s plugin_prompt, named by its label). A caller no agent runs may say it is a schedule or dictation with origin {kind, name?}; an agent’s prompt is always its own, and any other claim is refused. record_prompt {conversation_key, text_hash, origin} records the same for a prompt a process without the worker’s prompts submitted (the scheduler’s runs): the owner’s, and the schedule worker’s of this state directory as its own record names it.

list_agents entries carry the agent’s identity (id, provider, pid, process_key, conversation_key, session_id), its presentation (title, state, detail, updated_ms, question_pending, and starting: its provider has reported nothing since its process started, at most five minutes ago; list_history marks live entries the same way), and its place in tmux: pane, pane_index, window, window_index, window_name, project, tmux_session_id, managed, and sessions. A window linked into several sessions lists the agent once; sessions has one {tmux_session_id, project, window_index, window_name} entry per session that shows the pane, ordered by session ID. vendetta-protocol exposes the presentation subset as AgentInfo.

A manager is an agent with a team: other agents it leads, usually in one project. Teams are kept by conversation key (the process key until the provider names a conversation, then the conversation’s) in the state directory’s teams.json, and survive restarts and resumes. An agent may have several managers: each is one of its managers, kept oldest first, and each hears its events, may prompt, answer, mute, and release it. Teams nest to any depth: a manager may be a member of other managers’ teams (a sub-manager), never in a cycle: no agent is its own manager at any depth. The Master neither manages a team nor joins one. list_agents, list_history, and overview entries carry manager (it manages a team), managers (its managers’ conversation keys, oldest first, [] when it has none), muted, and kept (Auto-delete). An entry may carry both manager: true and managers; a client nests the tree by showing each entry beneath every one of its managers, marking there the others it has.

Method Notes
teams {teams: [{manager, members: [key], choices}], managers: {key: [key]}}, members in the order they joined, and each member’s managers oldest first. A member with several managers is in each of their members; a sub-manager is one team’s manager and others’ member.
team {manager?} {manager, members, choices}: the manager and each direct member as list_agents or list_history lists it ({conversation_key, state: "unknown", manager, managers, muted, kept} when neither does), and its team’s choices. A member with manager: true leads a team of its own; one whose managers name others is in their teams too. Without manager, the calling agent’s team.
set_team_choice {manager?, provider?, model?, effort?} Sets what the manager’s agents of provider (default: [harnesses] default) run with, replacing what it had; a part left out falls to [harnesses.PROVIDER] team. {manager, choices}. Without manager, the calling agent’s team; an agent sets only its own. Refuses an effort or model the provider does not take.
launch_options What create_agent takes: {default_provider, ephemeral_after_ms, master_start, terminal, host, providers: [{provider, models, efforts, team: {model?, effort?}}]}, ephemeral_after_ms how long an ephemeral conversation stays idle before it goes, master_start whether start_master can start the Master ([master.start] is set), terminal whether agents can start in a terminal window of their own ([launch] terminal), host the kind of host a launch with no place to follow goes to ([launch] host), each launchable provider’s suggested models ([harnesses.PROVIDER] models, else what Claude’s and Codex’s own pickers offer, read on each call; any other may be named), its efforts lowest first (none for OpenCode), and what agents a manager creates run with ([harnesses.PROVIDER] team).
create_agent {…, model?, effort?} Starts the agent on that model and effort, refused before anything starts when the provider takes no such effort or a session profile names the model too. A restore starts it on them again. An agent a manager creates takes, for each it leaves out, its manager’s team choices for the provider, else [harnesses.PROVIDER] team’s.
create_agent {…, images?} Up to ten photos ([{mime_type, data}], as send_image takes them), checked before anything starts, sent with prompt as the first message once the agent takes input: through send_image’s guards for a provider with native images, else as private local files the prompt names, as messaging does. Not for a manager or placement: "terminal". files: true says the prompt names files on this computer: a project machine’s agent cannot read them, so it is refused there, as a chat’s send of a document is, before the machine starts.
create_agent {…, ephemeral?} ephemeral: true makes the new conversation ephemeral from its start, under its process key until the provider names it; the receipt adds ephemeral. Any caller may ask; refused for the Master’s project and placement: "terminal".
create_agent {…, prompt?} An agent (not a manager, whose is task), not placement: "terminal", that waits up to 30 s for it to take input and then sends prompt once, through send_message’s guards as the caller would; never replayed. The receipt adds conversation_key, prompted, and prompt_error when it was not sent; the agent runs either way.
create_agent {…, prompt?, images?, files?, defer_prompt: true} Checks the first message as above and starts the agent, then answers at once, sending nothing: the receipt’s process_key is what deliver_first names. Not for a manager or placement: "terminal". Every tmux receipt carries process_key once the pane’s process is known.
create_agent {…, check_only: true} Checks everything a launch would, a project machine’s refusals too, and starts nothing: {checked: true}.
deliver_first {agent, server_key?, pane?, prompt?, images?, wait_ms} One wait of at most wait_ms (1 to 15000) for an agent defer_prompt started (agent its process or conversation key; server_key and pane find it while discovery names another process there) to take input, then prompt and images sent once as create_agent sends them. Replies {outcome, reason?, conversation_key?}: sent, ready (it takes input and there was nothing to send), waiting, needs_you (a provider dialog or question in its terminal waits for the owner), gone (its process exited), or refused (it takes input but refused the message); only sent sent anything. A machine’s agent is asked in its machine.
create_agent {…, manager: true, members?, task?, team?} Starts a manager in its project’s Agents window, never placement: "terminal", with members (conversation keys) as its team, then waits up to 30 s for it to take input and sends its brief once: ~/.config/vendetta/manager-prompt.md (else the shipped one), its project, its team, and task, the owner’s request. The brief never names the manager: task does, else the first prompt anyone else sends it, unless the owner named it. The receipt adds manager: true, conversation_key, briefed, and brief_error when the brief was not sent; the team stands either way. Members are refused before anything starts. team ({PROVIDER: {model?, effort?}}) sets its team’s choices. An agent a manager creates joins its team, muted; every tmux receipt carries muted. A manager that a manager creates is a sub-manager: it joins the caller’s team, muted, runs on the caller’s team choices as any member does, starts with no choices of its own, and its brief names the caller and says its replies reach it, not the owner.
assign_agents {manager?, members} Adds the manager to each member’s managers, making it a manager; a member keeps the managers it had. Without manager, the calling agent adopts them. A manager that did not ask is told by prompt, through send_message’s guards: the brief when it just became one, else who joined. Each joining member that manages a team and took its brief, but the caller, is told once in the same way that it joined, naming its new manager and where its replies now go (its managers when muted, else the owner as well); its mute is left as it was. {manager, members: [joined], notified, notice_error?, members_notified: [key], member_notice_error?}. A manager may join a team and a member may manage one; a member that becomes a manager is briefed naming its managers, and, when muted, that its replies reach them, not the owner. Refuses, changing nothing, unknown keys, the Master, an agent managing itself, and a member that manages the manager at any depth (a cycle).
delete_agent {agent} Deletes an agent: the owner (the chooser, supervised plugins such as the apps’ Delete) any but the Master, a manager a member of its own team it no longer needs. Stops it, if live, with one SIGTERM once it is idle with no question open, waits for its confirmed exit, then deletes the exited conversation with its chats and topics as the owner’s deletion does; its files stay. {agent: conversation_key, deleted: true, topics}. Refuses, changing nothing, with rejected: true and reason, a kept conversation, an agent working, asking, or waiting on an approval, and a manager whose team still has members; for the owner, the Master; for a manager, an agent not in its team, a member with another manager (the caller releases it instead), and a declared one; and any other caller.
release_agents {agents, manager?} Removes one manager from each agent: manager, else the calling agent. An agent names only itself as manager, and only its own members. The owner and supervised plugins may name any manager, or none: then each agent leaves every team it is in, a sub-manager keeping its own, and each manager among them in no team is dismissed, freeing its members. Managers that did not ask are told who left, and each briefed manager that left its last team, but the caller, is told once that it reports to the owner again (one that keeps a manager is told which left). {released, dismissed, notified, notice_error?, members_notified: [key], member_notice_error?}. A refused notice is reported, never retried, and never undoes the change.
set_managers {agent, managers} The owner’s alone: sets the agent’s managers to exactly these conversation keys, in this order where they are new; each added one becomes a manager, and the managers added and removed are told as assign_agents and release_agents tell them. [] takes it out of every team. {agent, managers, added, removed, notified, notice_error?}. Refuses, changing nothing, an agent caller, unknown keys, the Master, the agent itself, and a cycle. vendetta agent managers AGENT [MANAGER…] calls it.

A muted agent’s finished turns, questions, and approvals notify the owner nowhere; its chats still update. Its own vendetta alert and vendetta timer still sound. Mutes are kept like teams, in mutes.json. An agent a manager creates starts muted.

A muted member’s finished turn (its reply’s first 500 characters and link), question, approval, error, and exit reach every one of its managers instead: one prompt per manager for the events within 20 s of the first, through send_message’s guards, member titles and text quoted as untrusted data. A finished turn whose reply a manager already read through read_agent_messages or read_agent_history is left out of that manager’s prompt. When no manager takes its notice, refused or with no live manager, the owner gets those events’ alerts instead; none is retried. A muted sub-manager is a member like any: its events reach its direct managers only, never one further up.

A manager’s turn that a team update starts is quiet: its final reply alerts nobody, unless the manager flags it while it runs. A turn’s progress alerts nobody, quiet or not: Telegram and Discord get it without a sound, and the apps no push. list_agents entries carry quiet, always present:

  • It turns true when the worker sends a team update to an agent that is not running, so an update that joins a running turn never makes it quiet.
  • It stays true through that turn and after it ends, until the agent’s next turn starts: the first listing showing it running after one showed that turn over.
  • It turns false at once when the agent flags the turn (notify_reply) while it runs, when anyone but the relay prompts it through send_message or send_image (so a turn the owner joins alerts), and when the update starts no turn within 60 s.
  • The worker keeps it in memory: after a restart it is false.

A final reply is quiet when the listing that first shows its turn over says quiet: true; any later listing says the same until the next turn starts, so a reply read after its turn ended reads the same value. Questions, approvals, and errors of a quiet turn alert as usual. For a muted sub-manager “alert” means reach its managers: its quiet turn reaches nobody, and once flagged reaches each of its managers as a team update. A top manager’s flagged reply reaches the owner, whichever of a member’s managers flags it.

Method Notes
notify_reply {} Flags the calling agent’s quiet turn, found from the caller and its ancestors, as needing the owner: quiet turns false and the reply alerts as any does. {conversation_key, flagged: true}; flagged: false, rejected: true with a reason, changing nothing, outside a running quiet turn. vendetta agent notify calls it.
Method Notes
mute_agents {agents, muted} Mutes or unmutes agents named by conversation or process key: {agents: [conversation_key], muted}, then agents and history. The chooser, supervised plugins, and callers no agent runs may name any agent; an agent only members of its own team (any of a member’s managers may). Refuses, changing nothing, unknown keys.

Deleting a conversation from the history takes it out of every team, unmutes it, and stops keeping it.

A project’s vendetta.toml (Project file) declares agents the worker keeps running and schedules it keeps in step. list_agents and list_history entries of a declared agent carry declared: {folder, id, paused, failed}; scheduler records of a file schedule carry source: {kind: "file", folder, id, agent?}, and update_schedule and delete_schedule refuse them (read_only). The overview adds project_files, those untrusted, invalid, missing, or with items awaiting approval, as {folder, project, state, trusted, error?, pending}. note says how a file reads that the owner should know, such as a container project’s project ignored.

Method Notes
project_files {} {files: [{folder, project, hash, state, trusted, error?, note?, agents: [{id, name?, state, reason?, conversation_key?, manager?, provider, model?, effort?, manages}], schedules: [{id, cron?, at?, timezone?, agent?, provider, reuse, cwd?}], pending: [{kind, id, agent?, schedule?}]}]}: state untrusted, invalid, missing (trusted but gone or empty: nothing changes), or trusted. trusted says whether the folder is trusted: a file that does not check is untrusted with an error in an untrusted folder (nobody can trust it until it checks) and invalid in a trusted one (the owner can untrust it); missing is always trusted. An agent’s running, starting, waiting, paused, failed, superseded, awaiting_approval, or untrusted; manager is its declared manager’s id in the same file, absent at the top, and manages says it leads a team. A schedule prompts the declared agent, or starts provider in cwd (absolute: the file’s cwd resolved inside the folder), new each run or with reuse; no prompt or brief is listed. A pending item carries its agent or schedule. All of it is the file hash names; while the file does not check or is missing, agents and schedules are those in effect, from their records, and pending is empty. Any client.
trust_project {folder, trusted, hash?} Trusts or stops trusting a folder, by canonical path. Trusting takes hash, the file’s as project_files showed it, and refuses with changed if the file differs, and a file that does not check. The owner and supervised plugins only (owner_only otherwise, with why). {folder, trusted}.
start_declared {folder, id} Starts a paused or failed declared agent again, resetting its backoff. Same callers.
approve_project_item {folder, kind, id, hash} Takes the file’s hash as shown, as trusting does. Approves an agent or schedule (kind agent or schedule) a trusted file added since it was trusted, or in a shared container project changed since it was approved: until then it is listed in the file’s pending, an added agent awaiting_approval, a changed one running as last approved. Same callers.
adopt_declared {folder, id, agent, hash} Binds declared agent id to agent, a running agent’s handle, conversation key, or process key: of the declared provider, its conversation named, in the folder’s machine or, for a host folder, in the folder, and no other declared agent. Allowed before trust, so trusting starts none beside it; hash as trusting takes it. A binding with another conversation keeps that one as superseded. {folder, id, conversation_key}. Same callers.

A declared agent refuses rename_agent (named_in_file), close_idle_agent, delete_agent, and close_agent, resume_agent, and quit commands (/exit, /quit) through send_message from anyone but the owner and supervised plugins; the owner’s close_agent pauses it, and their resume_agent starts it as start_declared does.

With [auto_delete] enabled, the worker deletes a stopped conversation once it has been stopped (its last recorded activity) longer than after, exactly as a confirmed delete_history does: its history entry, and a deletion request for each app chat, Telegram topic, and Discord channel bound to it. Conversation files stay. It never deletes a kept conversation, a declared one, a live one, one a schedule reuses or targets by session, the Master, a manager whose team has members, a member any of whose managers is running, or one whose earlier deletion request never finished, and deletes nothing while the kept, team, schedule, or deletion state cannot be read. A pass runs 20 s after the worker starts, 5 s after the configuration file changes, and every ten minutes; it deletes at most 16.

Kept conversations are kept like mutes, in kept.json, by conversation key (the process key until the provider names one). list_agents, list_history, team, and overview entries carry kept, always present. Exited entries carry deletes_ms, when auto-delete will delete them (past means the next pass), while it is enabled and they are not excluded; absent otherwise.

An ephemeral conversation is the owner’s per-chat request that it go once idle: it is deleted after [auto_delete] ephemeral_after (default 30m, from 1m to 6d) without activity, even while [auto_delete] enabled is false, and whatever projects and skip_projects say. Idle means no running turn, no open question or approval, no prompt waiting to be read, and no status change, message in, or reply out for that long. A live idle one is stopped with one SIGTERM, as close_agent stops an idle agent, judged afresh right before, and once seen exited is deleted as a confirmed delete_history deletes; a stopped one is deleted that long after it stopped. Files stay. Never the Master, a declared one, a manager whose team has members, a member while any of its managers runs, or one a schedule reuses or targets by session, and nothing while that state cannot be read. A check runs every minute, so one goes within two minutes of its deadline; it deletes at most 4 a check. Ephemeral conversations are kept like kept ones, in ephemeral.json. Keeping and ephemeral exclude each other: making a conversation ephemeral stops keeping it, and keeping it makes it no longer ephemeral. Deleting one by hand forgets it. list_agents, list_history, team, and overview entries carry ephemeral, always present, and an ephemeral one, live or exited, carries deletes_ms while it is idle and not exempt (past means the next check).

Method Notes
keep_agents {agents, kept} Keeps conversations named by conversation or process key, or stops keeping them: {agents: [conversation_key], kept}, then agents and history. The owner’s and supervised plugins’ alone; an agent is refused. Refuses, changing nothing, a key to keep that no live agent or recorded conversation has; one to stop keeping may be any kept key.
ephemeral_agents {agents, ephemeral} Makes conversations named by conversation or process key ephemeral, or no longer: {agents: [conversation_key], ephemeral}, then agents and history. The owner’s alone, as keep_agents; refuses the Master, and, changing nothing, a key no live agent or recorded conversation has (one to clear may be any ephemeral key). vendetta agent ephemeral AGENT… and --off call it.
auto_delete_plan {} What the next pass would delete, deleting nothing: {enabled, after, ephemeral_after, delete: [entry], stay: [entry]}, each {conversation_key, title, project, provider, stopped_ms, ephemeral, deletes_ms?}, stopped ephemeral conversations among them whether or not auto-delete is on, and each one staying with a reason (recent, next_pass, kept, declared, live, master, manager, team (one of its managers is running), schedule, not_included, skipped, requested: an earlier deletion request never finished, and auto-delete does not retry it; unreadable) and a detail. While auto-delete is off, enabled: false and what it would do once on; error when the configuration cannot be read. vendetta agent auto-delete --dry-run calls it.

Agents running in a project machine are listed too, under their own keys; see there for what differs.

Agents running in a terminal outside every tmux server are listed too, unless their environment names another Vendetta state directory (XDG_STATE_HOME), whose worker they report to. Their tmux fields are empty, sessions is [], and project is the name of their git root, or of their working directory. Native questions, images, Claude, omp, and OpenCode text and interrupt_agent, and close_agent work for them; terminal input, read_agent, and other agents’ interrupt_agent reject, with input_blocked_reason no_terminal where the result carries one. read_agent with check_input answers for them with empty text and their readiness.

Schedule tools that change one schedule (update_schedule, delete_schedule, enable_schedule, disable_schedule, run_schedule) take an optional expected schedule: the configuration a person confirmed. The change applies only while it is still current.

create_schedule and update_schedule take one of cron, at, or on_demand: true (no time of its own: it runs only through run_schedule or trigger_schedule), and one of new: true (a new agent each run), reuse: true (the same agent each run), or session_id (one exact conversation). reuse_from, a conversation key, reuses that conversation (and implies reuse); otherwise a schedule switched to reuse takes the newest conversation its own runs started that still exists in its folder. A reusing schedule’s record carries conversation: {provider, session_id, conversation_key, session_file?, since_ms}, and the reply to create_schedule or update_schedule has it too, once a run started one or it was taken this way; a run that found it deleted or missing started another, and its receipt has replaced: {session_id, reason}, reason deleted or missing.

Additional methods, for any client:

Method Notes
send_image {id, text, images:[{mime_type, data}]} One to ten base64 images, validated before any reaches the agent.
read_agent_progress {id, cursor?, from_turn_start?, content?} A running turn’s new text since cursor. content {commentary, reasoning, tool_calls, separate_responses} picks commentary, readable reasoning (quoted lines), and ⏺ Tool(summary) lines. With separate_responses, U+2029 begins each response, and reasoning is one of its own: U+2029 and U+FDD0, its unquoted text, then U+2029. U+FDD0 never appears in agent text. tools lists the turn’s tool calls not yet answered, then those of a Claude session’s working subagents, the newest four, oldest first, each {name, detail?} as in ⏺ Bash(cargo test), whatever content picks; with none open, the turn’s newest call with done: true, else a subagent’s. Outside a turn it holds only subagents’ calls.
read_agent_todos, read_agent_question, answer_agent_question, prepare_agent_messages Progress and native questions. read_agent_todos {id} answers {id, supported, todos}, the agent’s Progress: the list the agent set (set_agent_plan), supported: true, unless its harness reported a different non-empty list since, else the harness’s. Harness lists carry no link or change.
set_agent_plan {todos} Sets the calling agent’s own plan, found from the caller and its ancestors; anyone else is refused. todos is {phases: [{name, items: [{text, status, link?, change?}]}]}, status pending, in_progress, done, blocked, or abandoned; link, who does the item, a reference link to a chat or one reply in it as reference::link writes it (vendetta://conversation/HASH, …/reply/ANCHOR), and change, the change holding its work, vendetta://page/diff/change-ID; at most 256 items and 64 KiB; null or no items clears it, hiding the harness’s older list too. {conversation_key, todos}. Kept in memory while that process runs that conversation: a new conversation, another process, or a worker restart drops it. vendetta agent plan set and clear call it. The owner sees it as Progress; how the apps and chats show it: docs/dev/plans/progress.md.
agent_plan {} The calling agent’s {conversation_key, supported, todos} as read_agent_todos answers. vendetta agent plan show calls it.
read_agent_approval {id} {id, approval}: the permission dialog a Claude Code session’s main loop has open, which the owner can answer from an app, as {id, tool, input, full, reason} (input the first line of each string field of the call’s input; full its command, old_string, new_string, and content whole, up to 2000 characters each), or null: none, a subagent’s, or one only the terminal can answer.
read_final {reference} The exact final reply a FinalReference names.
read_agent_history {id, limit?, responses?, reasoning?} Up to 60 of the newest user prompts and exact final replies, oldest first: {supported, messages:[{owner, text, ts_ms, key, response?, thinking?, anchor?, origin?}]}. A Claude prompt delivered mid-turn, inside a tool result, is a prompt of its own, without Claude’s line before it. A prompt whose text names its sender has origin, as prompts lists them: a team update {kind:"worker", name:"Team update"}, a plugin schedule’s marked run {kind:"schedule", name:<schedule id>}; who sent the others, the prompts listing says while the worker remembers them. With responses, the agent’s text between steps too, marked response: true. With reasoning, each readable thinking block too (OMP/Claude thinking text, Codex reasoning summaries), marked response: true, thinking: true, before its record’s text. Reads a bounded transcript tail; tool text never appears. Each entry’s text is at most 32 KiB; a final reply also has anchor, its reference anchor over all its text.
process_replaced {previous, current} Whether the core proves previous exited and current replaced it.
process_gone {process_key} {gone, project_removed}: whether the core proves that exact process exited (another boot, or its pid no longer runs with its start time; a machine’s, asked in its machine, or gone with its project once that is no longer a container project), and whether its project’s removal is why. Never inferred from a listing; a router deletes a chat whose agent and history are gone only with this proof.
idle_agent_status, close_idle_agent Inactivity checks and the guarded stop.
agent_info {id} or {conversation_key} What a live or recorded conversation’s own records say, for a list_agents or list_history handle or a conversation key: {id, conversation_key, provider, supported, as_of_ms, model:{id, name, provider, effort, detail}, context:{used, window}, session:{input, output, cache_read, cache_write, reasoning, cost_usd, responses}, limits:[{name, scope, used_percent, window_minutes, resets_at_ms, as_of_ms}], plan, credits:{balance, unlimited}}. context is in tokens; session sums every recorded response, input uncached and reasoning part of output; limits are the account’s windows that have not reset since. What the provider does not record is null (limits []); nothing is estimated. Claude: root responses, the window from Claude Code’s cached model catalog (or [1m]), and the plan; a live session’s cost_usd comes from its Mod, and its limits from every reading there is, Claude Code’s cache and each of the account’s live sessions’ Mod (read from every response): of a window’s readings the highest, as of the newest, since use only grows until the window resets; a recorded one’s cost_usd once it stopped, and the cached limits. Codex: turn settings and token counts, totals across resumes, limits, plan, and credits. OMP: model changes, thinking level, and per-response usage and cost; no window or limits. Other providers: supported: false. A transcript is read once, then only what it gains.
agent_commands {id} or {conversation_key} The slash commands a message can run in a live or recorded conversation, for the same handles as agent_info: {id, conversation_key, provider, live, commands:[{name, description, hint, source}]}, sorted by name. name is what follows the /; hint is the argument hint or null; source is builtin, user, project, plugin, skill, mcp, extension, or prompt. Built-ins that open a terminal picker or dialog, are terminal-only, quit, or sign in or out are left out, and so are aliases and Claude’s /new and /clear. Claude: the session’s own list from the Vendetta Mod (live: true), with argument hints from the vendored built-ins and the command and skill files; without a Mod to ask, the vendored built-ins and the files. OMP: the vendored built-ins, and with the Vendetta extension, its extension, prompt, and skill commands (live: true). Codex: the vendored built-ins. OMP and Codex take commands typed into their terminal, so an agent no tmux pane shows gets none; a recorded conversation resumes into one. Other providers: none. Read-only; nothing is kept.
start_master {}, confirm_master_start The configured Master’s guarded launch, from the worker’s own [master] project and [master.start].
alert {text, sound?, at_ms?} Sets an alert that sounds on the owner’s app devices at at_ms (now when absent, at most a day ahead): text one line of 1 to 300 characters, sound ping (default), chime, bell, or alarm. It belongs to the agent among the caller and its ancestors, matched to a list_agents entry by pid and start time, and goes to that conversation’s chat; without one, to the root chat. At most 64 wait at once, in the worker’s memory only: a restart loses them. Replies {id, at_ms, conversation_key}, conversation_key null for the root chat. vendetta alert and vendetta timer (an alert set its duration ahead) call it.
alerts {alerts: [{id, text, sound, conversation_key, set_ms, at_ms, state, ended_ms?}]}: every pending alert and the newest 64 that fired or were cancelled, state pending, fired, or cancelled, the most recently changed first (ended_ms, else set_ms). IDs are unique and increase in the order alerts were set, across restarts. Kept in memory only. Messaging reads it on each alerts event, past a baseline read when it starts, and hands on each change it has not seen: an alert set ten seconds or more ahead starts a timer, one that fires sounds, and one cancelled stops its timer.
prompts {conversation_key?} {prompts: [{prompt, conversation_key, delivery?, changed_ms, origin, text_hash}]}: what became of the prompts send_message accepted, every one still waiting, the newest 64 read or dropped, and the newest 64 without delivery, the most recently changed first. origin is {kind, conversation_key?, name?} as above; text_hash is the lowercase hex SHA-256 over the prompt’s trimmed text, so a router can tell which prompt a transcript shows. With conversation_key, that conversation’s alone, and also who sent its prompts others sent among the newest 1024 of them, which the worker saves in its state directory (prompt-origins.json: conversation keys, hashes, origins, and times, never text) and reads back after a restart; those have no delivery. Ids, states, and origins only, no text.
cancel_alert {id} Cancels a pending alert so it never sounds, and publishes alerts. Refuses one that fired or was cancelled, or an unknown ID. vendetta alert --cancel ID and the app’s timer cancel call it.
live_set {content} or {update} Shows the caller’s Live Activity on the owner’s iPhone: content starts or replaces it, update changes the one showing (each field given replaces, clear lists fields to remove). Content is vendetta_kit::live::Content (docs/dev/plans/live-activities.md): title, subtitle, status {text, tone}, progress {value, total}, timer {ends} or {starts} (ms), up to three counters [{label, value}], icon (an SF Symbol name), tone. The caller is a supervised plugin (plugin:NAME), else the agent among the caller and its ancestors as for alert (agent:KEY), else root; each has one. At most 4 show at once. Replies the activity {id, conversation_key?, content, started_ms, updated_ms, state, ended_ms?, dismiss_ms?} and publishes live. Kept in memory only. vendetta live start and update call it.
live_end {dismiss_after_ms?} Ends the caller’s Live Activity; its last content stays on the lock screen dismiss_after_ms (at most 4 h), else leaves at once. An agent’s also ends when list_agents no longer lists it live, and any after 7 h 55 min. vendetta live end calls it.
live {activities: [...]}: those showing, then the newest 16 ended, as live_set replies them.
actions {actions: [{plugin, name, run, description}]}: every action offered for desktop-wide keys, the worker’s own (plugin vendetta) first.
dictation_state {state, age_ms}: the latest reported dictation, or null, and how long ago it came. A display shows an ending for as long as it likes.
notifications {notifications: [{id, agent, project, pane, provider, event, text, at_ms, push?}]}: the worker’s newest 100 alerts, newest first, kept while any connection subscribes to notifications: which agent, its project and tmux pane (empty outside tmux), what happened (finished, needs input, needs approval, reported an error), and all it said or asks, in lines, up to 4,000 characters. push {title, body, chat, expires_ms, test?} comes once the alert is due (its chat shown, or the wait over; see hold_alerts): what a plugin that delivers alerts sends, as private as [notifications] makes it, chat the conversation’s hash or null, and expires_ms when it stops being worth sending. Kept in memory only.
config_reload Has the worker read and apply its config file now, as it does about a second after the file changes: {changed, started, stopped, restarted, errors, restart, summary}, the top-level sections that changed, the plugins started, stopped, and restarted, those that could not be, and why the worker restarts to apply it, or null. An invalid file is an error and changes nothing. vendetta config reload calls it.
test_notification Adds a test alert from Vendetta, due at once, and waits up to 30 s for each plugin that called deliver_notifications to report it: {deliveries: [{plugin, delivered}]}, one that never reported delivered: false. vendetta notify test calls it.

Supervised plugins only:

Method Notes
report_health {state} starting, running, or unavailable; shown by vendetta notify status.
answer_agent_approval {id, approval_id, allow} The owner’s answer, from the chooser or an app device, to the dialog read_agent_approval named: the call ends, refused, or approved and unrun, for the agent to make again within two minutes, when it runs once. {id, answered: true, allow} once the call ended; rejected: true when that dialog is no longer open. Never for an agent, the Master, or a schedule.
trigger_schedule {id, source, name, run, data?} A supervised plugin’s run of one schedule, as run_schedule does, but only while it is enabled: {outcomes: [{id, status}]}, status disabled when paused. source is the kind of trigger, such as webhook (a lowercase word of up to 32 letters, digits, or -, other than at, minute, and manual); name says which one and run the plugin’s ID for the run (1–128 letters, digits, -, _, .). They make its history occurrence SOURCE:NAME:RUN. data, up to 64 KiB, follows the prompt for this run only as “The SOURCE NAME sent this”, fenced as untrusted data and cut to keep the prompt within 64 KiB; it is never stored. Personal hub schedules refuse.
report_dictation {state} What the running dictation shows, the frontend protocol’s event (listening, transcribing, sending with the agent it goes to, completed, error with kept, the name of a recording kept to send again, canceled), or null for none. The worker keeps the latest, ending included, until the plugin reports another or disconnects.
set_actions {actions} What this plugin can do for desktop-wide keys, replacing what it offered before: up to 32 {name, run, description}, name as namespace:action (lowercase letters, digits, and hyphens), run the argv started, without a shell, when the action’s key is pressed, with any word {key} replaced by that key, and description up to 80 characters for the desktop’s list. [] offers none. They end with the connection. The plugin never names a key: the shortcuts plugin gives keys to the names its config lists.
deliver_notifications This plugin delivers alerts (its manifest’s delivers_alerts, docs/plugins.md), as ntfy does: it pushes each notifications entry once it has push, never one that was due before it started or past expires_ms, and reports each with notification_delivered. test_notification waits for it while its connection lasts.
notification_delivered {id, delivered} Whether that alert reached the plugin’s service. Report each once; an uncertain report is not repeated.
hold_alerts This plugin shows agents’ replies, as the app does: while its connection lasts, the worker holds each agent’s alert until the plugin reports that agent’s chat shown, at most 12 seconds past the alert’s own hold, so a push never arrives before what it announces.
report_shown {conversation_key, updated_ms} This conversation’s chat shows the agent as list_agents listed it at updated_ms, or later: its replies, question, or approval. Alerts from that listing or an earlier one go out. Report an agent only once it is no longer running and the chat has read all it wrote.
deletions_list, deletions_transition, deletions_recover_prepared Local deletion requests, one per topic or chat; each router settles its own.

Supervised plugins and the owner; schedule_snapshot, overview, project_colors, and canvas_color any caller no agent runs. They also see schedules that prompt the Master in the schedule tools, which other callers neither list nor touch.

Method Notes
delete_selection {plan} Carries out a deletion the owner confirmed in the chooser: terminals to close and conversations with their Telegram topics, Discord channels, and app chats. The worker rebuilds the plan from its own state and refuses if anything changed; the chooser and its ancestors are never closed.
plan_history_deletion {id} What deleting an exited list_history entry deletes, for the owner to confirm: {plan, title, provider, project, conversation_key, topics:[{platform, name}]}, each topic’s platform telegram, discord, or app and its name without status symbols. Refuses a live agent.
plan_selection {targets, entries, scopes} The owner’s: the deletion plan for what they selected, {plan, places}, built from the worker’s own state as delete_selection rebuilds it: targets the terminals to close as [kind, location], entries the list_history entries to delete, each with the topics and chats bound to it and where they live, and scopes the selection’s projects, windows, and panes, whose members it lists; places is [topic, {platform, name}] for each topic and chat, for showing. The chooser shows it and hands plan back unchanged.
delete_history {plan} Deletes the confirmed entry: only while it is still exited and its plan, topics included, is unchanged. Conversation files stay. The entry leaves the history at once; each router deletes its topic or chat once it runs, and never retries an uncertain one.
schedule_snapshot {records, running, runs}: every schedule, whether the schedule worker runs, and the newest runs.
overview The dashboard every client renders: {as_of_ms, attention, running, ready, ended, schedules, tasks, project_files}. Agents are {id, title, provider, project, state, detail, updated_ms, pane, pid, process_key, conversation_key, manager, managers, muted, kept}, and ended ones deletes_ms as list_history has it; a live agent with an exact transcript (OMP, Codex, Claude) also has peek, its newest three prompts, replies, and in-between text, oldest first, as {owner, response, text, ts_ms} with text one plain paragraph of at most 400 characters. Agents have state question, approval, running, starting (listed with running), idle, unknown, or exited, and agents of the configured Master project titled Master: attention the longest waiting first, running and ready the newest first, ended the conversations that exited in the last day, newest first, with a list_history id. schedules is {available, worker_running, paused, next:[{id, provider, project, prompt, reminder, next_ms}], problems:[{…, status, at_ms}]}, status failed, uncertain, or recovery. tasks is {available, timezone, pending, message, items:[{id, title, project, due_ms, all_day, deadline, overdue}]}: unfinished, unsnoozed tasks due or starting by the end of today, overdue first; never a partial list.
project_colors {} {colors: [{project, person?, color}]}: every project colour the worker keeps, live or not; a live project without one takes one first, from one read of the agents, the Master’s project before the rest, those needing the owner first, then the busiest. Each project keeps the colour it was first given, 0 to 11 (hue 45 + 30 × color degrees), the first in the order 0, 6, 3, 9, 1, 7, 4, 10, 2, 8, 5, 11 that no other live project has, or the least used.
canvas_color {project, color, person?} Gives any project, live or not, another of the 12 colors, 0 to 11, kept from then on (at most 500, those not live and oldest dropped first); person names another person’s shared project. A name up to 256 bytes without control characters. Publishes canvas.
screen {id} The agent’s visible terminal screen: {id, cols, rows, lines, hash}, lines rows of runs {t, fg?, bg?, b?, d?, i?, u?, v?} (text; colors "0" to "15" from the client’s palette or "#rrggbb"; bold, dim, italic, underlined, inverse), at most 300 columns and 120 rows; hash changes with the screen. Rejects agents outside tmux (no_terminal). Untrusted terminal output, never kept.

A container project (Machines) runs every agent in one container, the machine NAME, with a worker of its own. The host worker links each running machine and lists its agents and history beside its own; clients talk only to the host worker, with the methods above. Everything a machine reports is untrusted input from that machine.

Inside a machine, plugin_call for a plugin its worker does not run, such as vendetta diff’s, waits for the host (40 s): the machine’s worker publishes host_call {call} (topic host_calls), with the caller’s work tree top and branch as its own git reads them, and the host’s link reads it with host_take {call} and answers with host_reply {call, result?, error?} (both only for the host’s link). The host asks its own plugin with the caller’s key wrapped as this machine’s, machine its name, and cwd and top only inside its clone; a call from no agent is refused. Shipped plugins with commands for machines register them inside one though no such plugin runs there.

read_project_file {} (only for the host’s link) answers {text}, the clone’s vendetta.toml as a local file is read (a regular file of at most 64 KiB, no symbolic link), or null without one. The host checks it as untrusted text; trusting and running it are the host’s alone, so inside a machine trust_project, approve_project_item, and start_declared are refused and the reconciler never runs. set_declared {keys} (only for the host’s link) tells the machine’s worker which of its own process and conversation keys the host’s project file declares, at most 2048, kept in memory and sent again every 30 s; its guards then refuse its agents stopping, quitting, renaming, idle-closing, resuming, or deleting one, as the host’s do. The host applies its own guards to routed calls first.

vendetta:machine:v1/<len>:<NAME>/<len>:<inner key>

<inner key> is the machine worker’s own process or conversation key. Every key the host reports for a machine agent is wrapped this way: process_key, conversation_key, managers, team members, prompts entries’ conversation_key, alert owners, and transcript events’ process_key. A machine agent’s conversation key is never equal to a host conversation key, even for the same provider session. vendetta-protocol has machine_key(name, inner), machine_identity(key) -> (name, inner), key_provider(key) (the provider of any process, conversation, or machine key), and valid_machine_name. process_identity returns None for a machine key: its pid, boot, and start time describe nothing on the host. Names are 1 to 63 of a-z 0-9 _ . -, starting with a letter or digit.

list_agents, list_history, and overview entries of a machine agent carry machine, absent for the host’s own:

"machine": {"name": "groceries", "state": "running", "pid": 170,
            "pane": "%3", "window": "@1", "session": "$0", "host_pane": "%41"}
  • state: running; stopped (its container is stopped: its conversations are exited, and list_history shows them from the host’s last copy); unreachable (the container runs but its link is down: the entry shows the last reported state, and writes are refused); unavailable (the container runtime cannot be used).
  • pid, pane, window, session: the machine’s own process and tmux, meaningless on the host. host_pane: the host tmux pane attached to the machine’s tmux in the project’s Agents window, or null when none is open.
  • The entry’s own pid is 0 and its host tmux fields (pane, pane_index, window, window_index, window_name, tmux_session_id) are empty and sessions is [], so nothing that matches agents by pane or pid confuses a machine agent with a host one or with another agent of the same machine. project is the host project. vendetta-protocol’s AgentInfo has it as machine: Option<Machine>.
  • A machine agent’s exit reaches list_agents and list_history together: once list_agents no longer lists it, its list_history entry reads exited.
  • list_history entries from the host’s copy (a stopped machine’s) have detail: "", as the host keeps no replies.
Method Notes
list_machines {machines: [{name, state, project, repo, image, image_current, memory, agents, error?}]}, every configured machine: state as above, or absent (configured, not created); image_current whether it runs the image vendetta machine image build made or pulled last and that image is this install’s; memory its limit; agents how many live agents it has; error why it is unavailable or unreachable. Any client.

Every agent method above works for a machine agent: the host forwards it to the machine, after its own caller checks, and the machine’s worker applies the same guards as for its own agents. list_agents, list_history, teams, prompts (a machine’s prompt ids are strings, NAME:<id>, and their origin has no conversation_key), and overview merge the host’s entries with each machine’s. The alerts and auto-delete cover the host’s own agents only.

  • create_agent in a machine project starts the machine if it is stopped, starts the agent inside it on the machine’s clone of the project (a cwd must be inside the clone), and opens the host attach pane if none is open. Its receipt is the machine’s, keys wrapped, with machine. A schedule in a machine project starts a new agent there each run and prompts it, through the worker; reuse and exact-session schedules are refused (machine_unsupported).
  • resume_agent of a machine conversation starts the machine if it is stopped. Its receipt adds machine, conversation_key, and the resumed agent’s process_key (null if it was not listed within 20 s).
  • read_agent_messages for a machine agent never has image_refs: the machine loads every referenced image itself, under the same rules and bounds, and returns it in images; when that fails, the message has images_error, why, and no images. A final reply’s final_reference has machine; read_final reads it through that machine, and the host never opens its path.
  • send_image to a machine agent whose provider takes no native images (Claude) writes each image as a private file inside the machine, kept 24 hours, and sends the prompt naming them, as messaging does for a local agent. Messaging sends a machine agent’s photos with send_image whatever its provider; it never writes a file for one.
  • Deleting a machine conversation (plan_history_deletion, delete_history, delete_agent, auto-delete) deletes its entry in the machine; the host settles its topics and chats as for its own.
Method Notes
read_agent_file_image {id, path} For a machine agent: the image at path, an absolute path inside the machine, as {id, image: {mime_type, data}}, base64, validated as an image, at most 8 MiB. Messaging’s /photo PATH uses it for machine agents; for a host agent it is refused, as messaging reads host files itself. Never retried.
read_agent_page {id, page} For a machine agent: the page page (its file name without .html, the name a ?page= link or file:// link to the machine’s pages folder gives) as {id, page, data}, base64 HTML, at most the pages size limit, from the machine’s own pages folder only. Messaging writes it to the host’s pages folder as NAME--<page>.html and links that.

A machine agent has no host pane of its own: the project’s Agents window holds one host pane attached to the machine’s tmux, and the machine selects the agent’s pane in it. A client opens a machine agent in two steps: focus_machine_agent, then its usual navigation to the returned host pane, with the exact IDs and its own tmux client.

Method Notes
focus_machine_agent {id} or {process_key} For a machine agent (a list_agents handle, or its wrapped process_key): makes sure the attach pane exists, opening it in the host project’s Agents window (creating the window, at index 0, if needed) when none is open or it died, then selects and zooms the agent’s pane inside the machine. {id, process_key, host_pane, tmux_session_id, window, window_index, created}: the host tmux pane, session, and window to navigate to, and whether the pane was opened now. Never changes a host client’s selection: the caller navigates. The owner, supervised plugins, and callers no agent runs; refused for an agent. Refused with machine_stopped, machine_unreachable, or machine_unavailable, and with an ordinary error for a host agent. vendetta agent-focus --agent KEY calls it, then focuses the pane as for any agent.

Several host clients may show the attach pane at once; they share the machine’s selection, so the newest focus_machine_agent wins in all of them.

A refusal is an error response whose text starts with its reason code and : , then a sentence for people. Nothing was sent to the machine, so it is never uncertain:

Reason When
machine_stopped A write to an agent of a stopped machine (resume and create start it instead).
machine_unreachable Any call to a machine whose link is down. Nothing is queued.
machine_unavailable The container runtime cannot be used; nothing starts it.
machine_unsupported What machines do not do: placement: "terminal"; the Master or a Master project; session profiles (bind_session_profile, provider-tagged profiles); a provider the machine’s image lacks; a reusing or
exact-session schedule; a team across the boundary (a host manager with machine members, or a machine manager with host or other machines’ members: a manager runs inside the machine with members there); a key of one machine in a call about another; interactive preview input.

A request already written when a machine’s link ends is uncertain, as for any connection, and is never repeated. The host never answers it: it ends the caller’s whole control connection, so Client returns Uncertain, as when the worker itself goes away. Everything on that connection ends with it: requests sent after it go unanswered (treat them as uncertain too), and its handles, subscription, held alerts, and offered actions are gone. Reconnect, hello again, subscribe again, and list again for new handles. A failure before the request reached the machine, a refusal included, is an error response and leaves the connection open.

A paused machine reads state: "unreachable" with an error saying it is paused in list_machines, and calls about its agents are refused up front with machine_unreachable; a call written in the moment before the worker saw the pause (up to two seconds) is uncertain.

A machine’s agents, history, transcript, prompts, alerts, and teams events reach subscribers as the host’s own, transcript with its key wrapped; a machine’s resync, or its link restarting, is resync. machines comes when a machine’s state, link, or runtime changes, followed by agents and history. The host derives a machine agent’s alerts from the merged list, as for its own, so mutes, holds, and the relay apply.

Each person on the computer has a full Vendetta, all under the admin’s account: the admin’s own, and each person’s, whose agents run only in their container projects. A person shares a container project, every conversation of it now and later, with another person, who then has it in full: they read, prompt, answer, interrupt, resume, and start agents in it. Stopping, deleting, and the machine itself stay with the sharer. Only whole container projects are shared; there is one kind of share and one level of access, so shares carry neither a kind nor a role.

Workers reach each other on this computer only, over Unix sockets in a private folder, $XDG_RUNTIME_DIR/vendetta/links/SERVER/CALLER.sock (0700 folders, 0600 sockets): each worker serves one socket per person it knows, and the socket a connection arrives on names the caller. Only Vendetta’s own processes run on the host under this account; machines see none of these folders. Both ends check the peer is this account (SO_PEERCRED), and a hello must name the person its socket serves. The admin knows people from its instances.json; a person knows the admin from their [person] and everyone else from the admin’s link.

Every worker links to everyone in its directory. A link speaks the frames above but answers only these, with the caller’s shares applied:

  • hello as above, then peer_hello {name, display_name, admin, version}; subscribe to agents, history, transcripts, prompts, shares, and people;
  • list_agents, list_history, overview, and prompts, filtered to what is shared with the caller, each entry with share {id} and nothing of who else sees it; shares_with_me {by, person, shares: [{id, project, created_ms}]};
  • the agent methods a share allows (below), on handles those listings gave the same connection only, checked against what each names now; read_final on references it was given; create_agent {project, provider?, name?, model?, effort?} in a project shared with it;
  • leave_share {id};
  • chat_people, person_notes, and add_person_note for a conversation shared with it (Notes between people), the note written as the caller;
  • from the admin only: directory {people} (to people), projects {} (project names and machine states, never chats), pair {} (a pairing code of this person’s app), jobs {}, and the container project methods; to the admin only, from a person: claude_target {machine}, which makes that machine a Claude proxy target of theirs before its container exists, {dir}; and services for people (admin_services, admin_service_call) to people who take them. The instance runs them as itself; they take names, URLs, and choices, never commands.

Everything a link says is untrusted input, as a machine’s is: keys wrapped with the link’s person, sizes bounded, events only rereads. A request written when a link ends is uncertain: the worker ends its caller’s connection unanswered, as for a machine, and never repeats it.

A message in a shared chat that mentions a person of it is a note for the chat’s people, never the agent: no prompt, transcript, or machine carries it. The sharer’s worker keeps each chat’s notes, the newest 200, 4,000 characters each, in person-notes/ in its state folder (0600), never logged, and removes them with the chat. Only supervised plugins call these; a peer conversation’s go to its sharer, the note written as the person the link’s socket names.

Method Result
chat_people {conversation_key} {people: [{name, display_name}]}: the sharer, then each person the project is shared with. not_shared for a chat no one else sees.
person_notes {conversation_key} {notes: [{id, at_ms, from: {name, display_name}, text, mentions: [{name, display_name}]}]}, oldest first; id increases.
add_person_note {conversation_key, text, mentions: [name]} {note}, by this worker’s person. Refuses, keeping nothing, without a mention, a mention not of the chat (not_in_chat), empty or too long text.

A person who takes the admin’s services (instance --services proxy, the default; their worker reads shared.json in its state folder) uses the admin’s copy of any service method whose declaration has people, through the admin’s worker, whose credentials never leave it. The admin answers only people its registry gives them, named by the socket their link came on, within the method’s people bounds, and calls its plugin on their behalf (caller.on_behalf is the person’s name); the plugin scopes what it keeps, such as open readings, by that caller and hands a person nothing private, such as a command.

Link method Result
admin_services {} {services: [{name, methods: [{name, people}]}]}: only the methods that declare people.
admin_service_call {service, method, args?, deadline_ms?} The plugin’s answer. Closing the connection cancels the call.

On a person’s worker, a supervised plugin’s service_call goes to the admin’s copy when no plugin of theirs serves the method, and to both when the admin’s declares people.fill: their own answer, with the admin’s for each top-level field it leaves null, false, or out. A person’s calls never wait for the link: while the admin cannot be reached, or does not share the method, the call fails with service_unknown, as for a service no one serves. The admin refuses with service_refused (not shared with this person), service_unknown (not shared at all), service_too_large (over people.max_args), and service_busy (people.each of this person’s, or people.all of everyone’s, under way). Neither worker keeps or logs what a call carries, and nothing is retried.

vendetta:peer:v1/<len>:<person>/<len>:<inner key>

The inner key is the sharer’s own, a machine key. vendetta-protocol has peer_key, peer_identity, and valid_person_name; key_provider reads any key, and process_identity is None for a peer key. Entries of a shared agent or conversation (list_agents, list_history, overview, team) carry, where they are received:

"shared": {"by": "Georgi", "person": "georgi",
           "key": "<sharer's conversation_key>", "state": "linked"}

state is linked or unreachable (the entry shows the last state reported, history comes from a kept copy without replies, and writes are refused). machine is the sharer’s; its host_pane is null, pid is 0, and host tmux fields are empty. vendetta://conversation/HASH links match either key. The sharer’s own entries carry shares: [{id, person, name}]. A final reference from another person carries peer, their name; read_final reads it through their worker.

The sharer’s worker checks every call; the receiving worker checks it too, before sending.

On an agent or conversation of a shared project
Listings, agent_info, read_agent_messages, read_agent_history, read_agent_progress, read_agent_todos, read_agent_question, read_final, read_agent_page, read_agent_file_image, screen, prompts, agent_commands, wait_for_agent yes
send_message, send_image, answer_agent_question, interrupt_agent, resume_agent, create_agent yes
Stopping (/exit and the like, close_agent), deleting, renaming, keeping, teams, approvals, machines, schedules, project files, the sharer’s mutes no

create_agent {person, project, provider?, name?, model?, effort?} starts an agent in a project person shares with the caller (vendetta agent create --person). The receiver’s own mutes of a shared agent are theirs and silence only their alerts. Their managers take no shared members, and their schedules target no shared agent or project. Each person’s worker derives alerts for the shared agents it lists, as for its own; an agent’s alert and timer reach the sharer only. The sharer’s auto-delete and deletions apply, and a deleted conversation leaves every receiver.

A person makes at most 4 calls into one of the sharer’s machines at once, and all people together 8, so the owner keeps the rest of its link; more are refused (machine_busy), as is a call while every channel of the link is busy, which leaves the calls in flight alone. wait_for_agent across a share waits at most 30 seconds. A worker serves only the people in its directory, at most 16 connections at once from each and 64 in all. A link takes frames of at most 24 MiB from another person’s worker and keeps no listing entry larger than 64 KiB; a Client’s queue holds 1024 events, and on overflow the queued ones give way to one resync.

A prompt over a link is recorded with origin {kind: "person", name, via?}: name the display name of the link’s person, via {kind, name?} what of theirs sent it (app, terminal, agent with its title, dictation, schedule), as their worker says, shown and never trusted for rights. A peer cannot claim any other origin.

In a shared conversation the worker begins every prompt the agent gets, the sharer’s own included, with its own line:

Vendetta: from "Ana".
Vendetta: from "Ana" (agent "Shopper").

The line is the sender’s durable record: history reads it back from the first line only, in exactly this form, and clients show the text below it. In every prompt to a machine agent, shared or not, any line of the text that starts, after spaces, with Vendetta: from in any case (zero-width characters left out) is sent as a quote, > before it; a line ends at a line feed, a carriage return, a vertical tab, a form feed, U+0085, U+2028, or U+2029. So no text passes for the worker’s line. A slash command’s first line goes as typed, with no line, and the lines after it are escaped the same way. Across a share a person sends only /compact, /context, /cost, and /usage; any other slash command, /clear, /new, and /resume among them, is refused (sharer_only), as are quit commands. Display names are 1 to 40 characters with no quote, newline, or control character. vendetta-protocol::sharing has the line, its parsing, and the escaping.

“Owner callers” are the chooser, supervised plugins, and callers no agent runs; “host agents” adds the person’s own agents (a machine’s agents reach only their machine). Refusals start with a reason code and : , as machines’ do: share_none, sharer_only (only the sharer does that), share_revoked, machine_busy, peer_unreachable, peer_unsupported, not_container, not_git, admin_only, contained (a person’s worker never runs anything on the host).

Method Callers Notes
people {} any {me: {name, display_name, admin}, people: [{name, display_name, admin, state}]}, state linked or unreachable. Names only.
shares {} owner callers, host agents {given: [{id, project, person, name, created_ms}], received: [{id, project, by, person, state}]}.
share {project, person} owner callers, host agents Shares a container project in full. Refuses not_container, an unknown person, and oneself; sharing the same again gives the same share back. {share}. Kept in shares.json. vendetta share calls these.
unshare {id} owner callers, host agents The sharer’s.
leave_share {id} owner callers, host agents The receiver’s: ends the share at the sharer’s.

A share ends when its project stops being a container project or its person is removed.

Admin only (admin_only elsewhere), owner callers. They run vendetta instance’s steps in the worker, without a terminal; none needs root. A paired app device of the admin can therefore add and remove people and their containers.

Method Notes
instances {} {instances: [{name, display_name, port, web_url, state, worker_running, endpoint_up, current, link, projects: [{name, machine?, old_image?}], address?, providers}]}: the registry, with each person’s project names and machine states over the link (old_image when a machine runs on an image an earlier install built); never their chats. address is their tailnet address while the plugin runs: {state, service, web_url, port_web_url, service_web_url, note}.
instance_add {name, display_name?, port?} A job (instance_add): instance add’s steps but pair; exists when it is one already. Done once their Vendetta links (at most a minute after its steps), its result is {name, web_url, pairing}, pairing their first code as pair gives it, or null when their Vendetta did not link in time.
instance_pair {name} {code, qr, web_url, expires_ms}, made by that instance over the link.
instance_update {name?} A job.
instance_remove_plan {name} {plan, lines}: what goes, as instance remove lists it, first that their home goes with their conversations, chats, devices, and container projects.
instance_remove {plan} A job, only while the plan is unchanged.
instance_rename {name, display_name}
capabilities {} {claude, git, services}: what the admin has to give people now, from the Claude proxy’s report and whether any service method declares people other than one with fill, which only says what is offered. Any caller.

The person’s own, or with instance (admin only) another person’s, carried out by that person’s worker over the link. Owner callers and host agents, except removal (owner callers).

Method Notes
container_projects {instance?} {projects: [{name, state, repo, origin, image_current, memory, agents, unfetched, shares: [{id, person}], error?}]}, state as list_machines, or absent.
container_project_finish {instance?, name} Finishes a recorded project that has no machine, from its own record, as a project_create job: a create that failed, or that the worker’s end cut off (which the worker finishes itself as it starts). Until then its machine methods are refused: “NAME was never finished: finish creating it, or remove it”.
container_project_create {instance?, from, make_git?} from: {existing: folder}, a git repository of theirs (not_git otherwise, unless make_git: true, the person’s confirmation, which runs git init and one commit of what is there); {new: name}, an empty repository with one commit in [machines] checkouts/NAME, NAME being the typed name folded as vendetta_protocol::machine_name folds it (machines); or {clone: url, name?}, cloned there with the person’s git. A job: config, image, clone, claude (the machine’s Claude proxy target, asked of the admin in an instance; claude_unavailable when it cannot be had), create, restart, ready.
machine_start, machine_stop, machine_fetch, machine_update {instance?, name, ref?} As vendetta machine: {name, said}.
machine_recreate {instance?, name, stop?} A job (machine_recreate); stop stops a running machine first.
container_project_remove_plan {instance?, name, delete_folder?} {plan, lines, warnings, folder, folder_optional, delete_folder}: the container, its volumes and clone, its conversations, and the shares that end; and its folder, which goes when Vendetta made it (new or clone), and for one the person brought (folder_optional) only with delete_folder. warnings, also among lines, say plainly what would be lost: a deleted folder’s uncommitted changes and commits on no remote, and the machine’s (its uncommitted changes, read inside it while it runs, and branches not fetched).
container_project_remove {plan} A job, only while the plan is unchanged, its warnings included: confirming the plan is the consent.
Method Notes
jobs {} {jobs: [{id, kind, instance, target, step, steps, state, error?, result?, started_ms, ended_ms?, title?}]}, newest first, the newest 32, kept in memory and ended with the worker: kind instance_add, instance_update, instance_remove, project_create, project_remove, or machine_recreate; title what it does in words when its kind’s are not enough (“Turning Claude on for Ana”); state running, done, or failed with error, the step’s command and output. A failed job is never retried on its own; running the same method again checks each step before acting and finishes it. Owner callers and host agents.

Instances and machines use the admin’s Claude login through the Claude proxy, which claude_login reports.

Tests add people with the real vendetta instance add under their own account, with systemctl and tailscale stood in (VENDETTA_INSTANCE_BIN, tests/people.py).

What plugins declare to the worker about what a person connects: a git host they serve, and the settings people’s copies of them take. What the apps show of a provider is the plugin’s own UI, the connections and new_project slots; on a person’s worker, the worker publishes what the admin gives them (claude-login, git-proxy, services, shared-tools) the same way, as plugin vendetta.

Method Caller Result
set_providers {providers: [{id, offers?, inherit?}]} supervised plugins Replaces this plugin’s providers (at most 8, ids unique across plugins); they end with its connection. offers are git_host {hosts} alone (1 to 8 host names; any other kind is refused). inherit: settings each person’s copy of this plugin takes from this one (at most 8; a lowercase name, never enabled or command, to text of up to 256 characters, a number, or a boolean), written into their [plugins.NAME] by instance add and update. Public values only.
provider_inherits {} any {plugins: {NAME: {KEY: VALUE}}}: what running plugins declare in inherit.
provider_targets {provider} the owning plugin, for a provider with a git_host offer {targets: [{id, dir, inside, uid}]}: this person’s host (none for a person’s worker) (<state>/providers/ID) and each machine (<state>/machines/NAME/providers/ID, seen inside as /run/vendetta-providers/ID). It serves git.sock and a gitconfig in each, as the git proxy does.

For providers with a git_host offer, the worker keeps <state>/providers/gitconfig, including each one’s gitconfig, in this user’s git config (include.path, once, while any exists), and the same in each machine’s folder, which the machine sees at /run/vendetta-providers and its image’s /etc/gitconfig includes.

Over a link, the admin asks a person’s worker provider_summaries {}: each provider node of their plugins’ connections pages as {id, name, icon, origin: "own", state: {status, account?}} (id the contribution’s), never a flow, an action, or a credential. Their ui events on the link make the admin read them again.

vendetta providers list|connect|disconnect|cancel|items reads the connections and new_project contributions and their pages and acts with ui_call: a provider node’s action by its id, a secret flow’s submit with context.secret, a source’s list with context.query.

What supervised plugins put into the apps as data: contributions to slots (the sidebar, a chat’s menu) and pages of keyed nodes the apps draw with their own pieces. The node kinds, slots, and the dashboard’s page are in Plugin UI; the worker checks only bounds and structure, so new kinds need no core change.

Method Caller Result
ui_set_contributions {contributions, on_demand?} supervised plugins (any but one named vendetta, the worker’s own) Replaces this plugin’s contributions (at most 16): {id, slot, label, icon?, badge?, home?, modes?, order?, when?, on}, known fields only, ids unique. on_demand: up to 8 page id prefixes it builds on request; fresh: those of them built again each time a page is read whole.
ui_set_page {page, title, root, nodes} supervised plugins Replaces one page (at most 8 per plugin): at most 4,000 nodes of 16 KiB, 2 MiB in all, keys of 1 to 200 bytes, each node with a kind, every children, footer, and trailing key a node, every on well formed. When it changed, its rev rises and the patch is kept.
ui_remove_page {page} supervised plugins Removes it.
ui_contributions {} any {version: 1, contributions}, each with its plugin, by slot, order, plugin, and id.
ui_page {plugin, page, since?} any {rev, patches: [{rev, set: {KEY: node|null}, root?, title?}]} since since while the last 64 reach it, else {rev, title, root, nodes}. ui_page_unknown once it is gone. A page not published whose id starts with one of the plugin’s on_demand prefixes publishes ui_wanted {plugin, page} and waits up to 8 s for it; read whole, a page of a fresh prefix is asked for again the same way, and served as the plugin last set it.
ui_call {plugin, page?, node, item?, choice?, context?} any of this user’s callers, agents included The plugin’s answer to the action of that node (a contribution’s id without page; item picks one of a node’s actions, choice one of its, or that action’s, ask.choices): its on.action and on.args as the plugin published them, with context (at most 4 KiB). 10 s, 30 s for a new_project contribution (ui_timeout, never resent); one call per node at a time (ui_busy); ui_unknown for a node with no action; ui_gone when its plugin ends first.
ui_take {call} the owning plugin {call, page, node, action, args, context, caller}, once; caller as plugin_call gives it. A plugin acting on what only the owner decides refuses a caller without owner.
ui_reply {call, result?, error?} the owning plugin Answers it: {notice?, on?} for the apps.
plugin_prompt {id, text, label?, require_idle?} supervised plugins Sends text to the listed agent id through send_message’s guards, recorded and shown as the plugin’s (origin {kind: "plugin", name}), never the owner’s: name is label (1 to 40 characters, one line), else the plugin’s name. send_message’s answer.
agent_place {id} supervised plugins {top, branch}: the listed agent’s work tree and branch, from rev-parse in its working directory; a machine’s agent’s, read by its machine. Claims to check, not paths to open.
caller_identity {} any {conversation_key?, cwd?, owner}: the caller as plugin_call names it.
plugin_call {plugin, action, args?} any of this user’s callers, agents included A plugin’s own command, such as vendetta diff, asking its plugin (one that publishes UI): it reads {call, action, args, caller} with ui_take (no node), caller {conversation_key?, cwd?, owner} from the socket’s peer: the nearest agent among its ancestors and the peer’s working directory; owner for supervised plugins and the owner. 30 s; args at most 64 KiB.

Everything a plugin published ends with its connection. Events: ui {plugin} (topic ui) when its contributions or a page changed, ui_call {call, plugin} (topic ui_calls), which its plugin reads with ui_take, and ui_wanted {plugin, page} (topic ui_calls).

Methods a supervised plugin serves for the rest of Vendetta: the worker itself, other plugins, the owner, and agents call them through the worker. The worker checks who may call each method from the kernel’s peer, never a request field, and carries the call to the plugin. Types are vendetta-protocol’s services module.

Method Caller Result
set_services {services} supervised plugins Replaces this plugin’s services (at most 8); they end with its connection. Publishes services.
services {} any {services: [{name, plugin, events, methods: [{name, callers, deadline_ms, max_args, max_result, max_calls, people, limits}]}]}, by name.
service_call {service, method, args?, deadline_ms?} whoever the method’s callers name The plugin’s result, or its error. args is an object; deadline_ms may shorten the method’s, never lengthen it.
service_take {call} the serving plugin {call, service, method, args, caller, deadline_ms}, once; deadline_ms is when the caller stops waiting, in ms since the epoch.
service_reply {call, result?, error?} the serving plugin Answers a call it took. error reaches the caller, cut to 400 characters.
raise_event {kind} the plugin whose service declares kind in events Publishes that event. Only tasks may be raised, by the tasks service.

A service: {name, methods, events?}. A method: {name, callers?, deadline_ms?, max_args?, max_result?, max_calls?, people?, limits?}; limits names the method’s own bounds on what it takes, such as {max_seconds: 1800}, for callers to read: up to 8 whole numbers, each named in lowercase letters and _, listed by services {} and not checked otherwise. people {each, all, max_args?, fill?} lets people under the admin’s account call the admin’s copy (Services for people): each calls of one person’s and all of everyone’s in flight (1 ≤ each ≤ all ≤ 16), max_args at most the method’s and 23 MiB, the most a link carries, and fill for a method whose answer says what the service offers. Names are a lowercase letter, then lowercase letters, digits, -, or _, at most 32 bytes; a service’s name, and each event it raises, are one plugin’s (service_taken). Bounds:

Field Default At most
deadline_ms 10 000 900 000
max_args, max_result (bytes of JSON) 64 KiB, 1 MiB 48 MiB
max_calls (in flight at once) 4 16
methods per service 32

callers lists who besides the worker may call, which always may: plugin (plugins the worker supervises), owner (the owner, as Who may call says; a refusal says why), master (the configured Master’s process or one under it), and any (any process of this user’s, agents and the CLI included). An empty list is the worker’s alone. A call’s caller is the first of those, in that order, the peer is and the method allows: {kind, plugin?}, with plugin the calling plugin’s name; the worker’s own calls are {kind: "worker", on_behalf?}, on_behalf whom it calls for, such as a person over their link.

Bytes, such as a recording, travel as base64 in args or result; 32 MiB of audio fits max_args of 43 MiB. Work in pieces, such as a reading aloud, is several calls: one that opens it and answers an id, one per piece, one that closes it. The plugin keeps that state and may scope it by caller.

A call is never resent. The worker publishes service_call {call, service} and waits; past the deadline the caller gets service_timeout, and when the caller’s connection ends, the call is cancelled; either way the worker publishes service_cancelled {call}, and a late service_reply gets service_call_unknown. A result over max_result fails the call with service_too_large, which the plugin’s reply also gets. When the plugin’s connection ends, its calls fail with service_gone and its services go. Other errors: service_unknown, service_refused (not a caller the method names), service_too_large (args), and service_busy (max_calls under way).

The worker looks these up by method name in every service, so any plugin may serve them; it calls them as itself.

Method Result
endpoint {} The app endpoint the plugin runs, {listen, public_url} (listen a loopback HOST:PORT, public_url the wss:// address devices use), or null. One plugin serves it. The worker remembers the last answer and its plugin, so the endpoint stays a tailnet target while that plugin restarts, as long as its table is enabled.
bound_topics {conversation_key, process_key} {topics: [{account, owner, destination, platform, name}]}: the chats bound to that exact conversation and process (a destination with a thread), platform and name (no status marks) for showing the plan. The worker’s deletion plan (plan_selection, plan_history_deletion) asks every plugin that serves it and lists them all, and asks again before carrying the plan out; a plugin may let the owner ask too (callers: ["owner"]). A plugin’s error fails the plan, and so does a plugin that served it before, is still enabled, and does not serve it now (restarting, say), so no deletion leaves its chats unseen. The chat plugins serve it, each from its own checkpoints, as a service named after the plugin; the app plugin also serves endpoint.
focus_window {pid} {} once the desktop window holding process pid (its own, or an ancestor’s) is in front. Declare it for the worker alone. The shortcuts plugin serves it, as service desktop.
focused_window {} {pid}, the focused desktop window’s process, 0 with none. The shortcuts plugin serves it on Hyprland.

The vendetta-speech plugin serves speech, which supervised plugins call (service_call {service: "speech", method, args}); its settings are [plugins.speech]’s transcription and narration tables. It declares offer always, transcribe only with transcription, and the narrate_* methods only with narration, so a caller that finds none gets service_unknown.

Method Result
offer {} {transcription, narration, max_seconds, piece_chars}: the transcription provider’s name or null, whether a voice reads aloud, and the limits transcribe and narrate_piece declare (max_seconds, max_chars), each null without its method. They are in the offer as well because a person’s worker sees the admin’s offer, never its declarations.
transcribe {audio, max_seconds?} Base64 Ogg/Opus, WebM/Opus, WAV, MP3, or M4A up to 32 MiB, to {text, seconds, cut}. Only the first max_seconds (1 to its declared max_seconds, 1800, the default) are transcribed: seconds is how much was, and cut says the audio went on. It goes to the service in parts of about two minutes, in order, within 600 s; any part failing fails the call. Deadline 630 s; use a connection of its own, as closing it cancels the call and stops the service.
narrate_start {} {reading}, a string: a reading with the voice, its key loaded now and held only while the reading lasts. Four open per caller; one unused for two minutes ends.
narrate_piece {reading, text} {mime: "audio/mpeg", seconds, audio}, base64; 1 to its declared max_chars (4,500) characters, each piece carrying on from those before, one at a time per reading (speech_busy).
narrate_end {reading} {}.

Readings are their caller’s. People use the admin’s copy of every method it declares (Services for people): one transcription each and four in all, up to 16 MiB of audio; two readings each, of at most 40,000 characters (speech_too_long); and an offer that fills in theirs. Nothing is retried, and neither the plugin nor the worker keeps or logs audio or text.

A supervised plugin keeps schedules of its own, each id its plugin name, -, and more:

Method Result
schedule_upsert {schedule} Adds or replaces it, the schedule as schedule_snapshot records it (id, cron or at, timezone?, enabled, provider, session_id, session_file, reuse?, cwd, tmux_session, prompt, master?, guard?); the worker sets plugin. {id, schedule, last_claimed_at, recovery_needed, last_outcome}, last_outcome {at_ms, occurrence, status, finished}, finished once the run ended. A one-off already due runs at the next tick; one already claimed at its at, or awaiting recovery, stays off. At most 256 per plugin.
schedule_remove {id} Removes it: {removed}.

Another plugin’s id, or one not under the plugin’s prefix, is refused (schedule_taken). The schedule tools list them with plugin; update_schedule refuses them (read_only), and pausing, running, and deleting them work as for any schedule. The worker never prunes a plugin’s schedules: the plugin removes those it is done with.

master: true makes it prompt the configured Master’s exact conversation (session_id, with tmux_session the Master’s project): the scheduler refuses it while another conversation is the Master, checks the Master again right before submitting, and resumes an exited Master from its transcript, in the cwd that records, through [master.start]; never a new conversation. guard: {service, method, args?} names a method of a service the same plugin serves, which the scheduler calls (as any) before launching and again right before submitting: {eligible: false} ends the run suppressed, and an error fails it. Schedules with master are listed and changed only for the owner and supervised plugins.

The scheduler starts each run’s prompt with the line [vendetta-schedule ID] (when the id is 1–256 ASCII letters, digits, and -_:.). read_agent_messages and read_agent_progress mark the replies of the turn it starts with schedule_run: ID, read from the agent’s input record, never from its own text. A plugin that wants to hold back or acknowledge such replies serves, on any service of its own, two methods messaging calls (as plugin) for a run in the Master’s chat:

Method Result
run_status {schedule, provider, session_id} {status, eligible}: null for a run it does not track (the reply goes out as usual); running until the outcome is known (messaging asks again later); submitted, with eligible whether the reply should still reach the owner; or the receipt already given: delivered, suppressed, or uncertain.
run_receipt {schedule, status} Records delivered, suppressed (held back), or uncertain, only for a run now submitted or already so: {}.

Messaging finds the service from services {}: the one serving run_status whose plugin’s name, then -, starts the schedule id.

One plugin may serve the tasks service: the owner’s tasks for the chooser (p, C, project headers), the overview, the apps, messaging’s Master messages, and the HUD. Clients find it in services {} and show no tasks while nothing serves it. It declares events: ["tasks"] and raises tasks whenever its tasks change. Types are vendetta-protocol’s tasks module.

Method Callers Result
projection {} owner, plugin Every task, as one snapshot (below).
task_mutate {id?, expected_hash?, mutation_id, patch} owner, plugin Applies an owner’s edit: {hash, ...}, the task’s new hash.

A projection: {generation, complete, errors, timezone, as_of, tasks, pending, project_names, presentation_warnings}. generation changes with anything in it; complete: false or any errors makes clients show nothing rather than a shorter list. timezone is an IANA zone and as_of an RFC 3339 time. pending lists {id} for each capture not yet a task; clients count them. project_names maps project ids to display names; presentation_warnings are display problems, such as a name that could not be read, which clients note but never show.

A task: {id, hash, title, details?, status, priority?, project_ids, scheduled?, deadline?, snoozed_until?, next_reminder?, reminder_times?, created_at?, updated_at?}. status is open, in_progress, blocked, done, or canceled; priority low, normal, high, or urgent. project_ids are Vendetta project names; a task without one is personal. Times are RFC 3339. scheduled and deadline are {zone, instant, local}, an exact moment with local the same moment in zone’s offset, or {zone, date, sort_instant}, a whole day (YYYY-MM-DD) with sort_instant its start for scheduled and its end for deadline.

A task_mutate edit names the task’s current hash as expected_hash and must conflict, not overwrite, when the task changed; a new task has no id and needs a title. mutation_id (at most 128 bytes) makes a repeat of the same edit a no-op. patch holds only title, details (text up to 16 KiB), status, priority, scheduled, deadline, snoozed_until, and project_ids (up to 8 names of 1 to 128 bytes). A title comes with explicit scheduled and deadline, so no date is read from its words; snoozed_until comes alone and never moves a deadline. Callers never retry a failed or uncertain edit.

The personal-hub plugin serves tasks from a Personal Hub vault, and the hub’s own operations as the personal-hub service:

Method Callers Result
snapshot, mutate, resolve, validate_reminder master The hub operation of the same name (validate_reminder is validate-reminder) with args as its JSON request, as vendetta service call personal-hub METHOD runs them.
context, record_change any The same, for project knowledge only.
run_status, run_receipt plugin A reminder’s run; eligible is the hub’s validate-reminder, and a receipt is passed to the hub. Captures’ runs are untracked.
guard {kind, key} any {eligible}: the scheduler’s question before a reminder or capture prompts the Master.

Reminders and captures are its master schedules with this guard; it reads each finished run back from schedule_snapshot, tells the hub, and removes a schedule once settled. A run whose outcome is uncertain stays blocked, never replayed.

The plugin that proxies (its manifest’s proxies, plugins; Vendetta ships claude-proxy) serves the admin’s Claude login to each target (a machine, an instance’s host Claude, an instance’s machine) on a Unix socket of its own, and with [plugins.claude-proxy.git] the admin’s git login on another beside it (plugins). These carry names, states, and counts, never a token.

Method Callers Result
proxy_targets {} the plugin that proxies {targets: [{id, kind: "machine", instance, machine, dir, inside, claude, git}]}: each target’s socket folder, the same folder as its processes see it (inside: /run/vendetta-claude in a machine), and which logins it gets: the admin’s machines, and each person’s machines (as the admin’s link lists them or claude_target asked) when they take the admin’s Claude or git login, in people/NAME/targets/machines/M. A target’s folder is mounted into that machine alone, so the socket names the target. Empty on a person’s worker.
proxy_sync {} any Publishes proxy, so the plugin rereads its targets now; vendetta machine calls it before a machine starts. {}.
claude_target {machine} any, on a person’s worker (vendetta machine asks it) Asks the admin over the link to make the machine’s target; {dir}. claude_unavailable without a link to the admin.
proxy_report {source, targets} the plugin that proxies Its status, whole; kept until the next report or until its connection ends. Publishes claude_login.
claude_login {} any The latest report with plugin: "running", or {source: null, targets: [], plugin: "unavailable"}.

source: {present, expires_ms, refreshed_ms, refresh: "ok"|"running"|"failed"|null, git}, the access token’s expiry only; git says it serves the admin’s git login. While a report is kept, people may take the admin’s Claude login, and with git its git login. Each target: {id, kind, instance, machine, state, last_used_ms, requests, input_tokens, output_tokens, error, git_requests, git_refused, git_last_used_ms, mcp_in_use}, mcp_in_use {NAME: count} the Claude sessions connected to each shared server now, state one of waiting, ready, active (used in the last two minutes), refused (a connection from another account in the last hour), or error. Connections are limited per target and per person. Counts are since the plugin started; last_used_ms persists. The plugin rereads its targets on claude_proxy, machines, and people events, and every 10 seconds.

The admin shares their own Claude Code skills and MCP servers one by one: nothing is shared until the admin picks it for a person, for everyone (current and future people), or for the admin’s own container projects (_machines). The claude-proxy plugin reads them as the admin and keeps, in each target’s folder, a Claude plugin the target’s Claude loads (CLAUDE_CODE_PLUGIN_DIRS): shared/plugin with the picked skills copied and one vendetta mcp-bridge SOCKET entry per picked server, whose socket (shared/mcp/*.sock, in the target’s folder) runs the server as the admin. A server’s command, arguments, environment, URL, and headers never leave the plugin.

Method Callers Result
share_items_report {skills, mcp} the plugin that proxies Names and states, whole: skills: [{id, name, description, source, state: "ok"|"refused", reason}], mcp: [{id, name, transport: "stdio"|"http"|"sse", source, state: "ok"|"refused"|"failed", reason}], nothing else; failed is a server that would not start as the admin, still shared, shown unavailable in the picker until it starts or its definition changes. The target’s bridge is told only notifications/vendetta/start_failed {server}, never the cause, and answers calls with “NAME couldn’t start on ADMIN’s side”. Kept until the next report or its connection ends. Publishes people and proxy.
share_items {} the admin’s owner callers {plugin: "running"|"unavailable", skills, mcp, everyone: {skills, mcp}, machines: {skills, mcp}}.
share_picker {name} the admin’s owner callers One person’s (or _machines’) picker, which the Claude proxy draws on the People screen: {name, state: {status, detail}, actions: ["reload"]?, items: [{id, title, subtitle, status, detail, everyone, reload, actions}]}, each item’s actions its switch (share/unshare) and everyone’s (share_all/unshare_all).
instance_share_item {name?, item, on, everyone?, reload?} the admin’s owner callers item is skill:NAME or mcp:NAME; name a person or _machines; everyone: true for every person. Takes effect at once, no job. With reload, then as instance_reload for each: {item, on, reloads: [...]}.
instance_reload {name} the admin’s owner callers Asks that person’s worker over the link (reload_sessions), or each of the admin’s machines (shared_reload), to reload the Claude sessions that predate the servers shared now: {name, sessions: [{conversation_key, state: "reloading"|"pending"|"restart"}]}; restart, a session with no Mod connection, is told in its chat to restart (once).
agent_notes {} any {notes: [{id, conversation_key, text}]}, the newest 64: one line each for an agent’s chat, such as “Reloaded to pick up new tools from NAME”, or, once, “Restart this conversation to use the new tools from NAME” for a session the reload could not reach.
shared_reload {force, from?}, shared_reload_status {after, names?} inside a machine, its host The machine’s half of a reload; the status carries stale, pending, and notes after after, and with names {skills, mcp} its clashes: which of them the machine has its own of.

Over a link the admin asks a person shared_status {names}: {stale, pending, clashes: {skills, mcp}, machines: {NAME: {skills, mcp}}}, how many of their sessions predate the shared servers or wait to reload, and which of the asked names they have their own of in each machine that answered within three seconds (clashes is empty for a person: the host’s Claude is the admin’s) (theirs win: left out for them there). The admin asks its own machines the same with shared_reload_status {names}. reload_sessions {} starts their reload.

Each target’s shared/state.json is {skills, mcp} digests. A worker whose Claude loads the plugin (a person’s, a machine’s) watches it: when the skills change, each idle Claude session runs /reload-plugins (its conversation and cache stay); when the servers change, sessions that started before are stale until the admin’s reload runs /reload-plugins --force in each, once idle (reload_pending on list_agents until then), never in a session working, asking, or awaiting approval, and never again on its own. Done is the Mod registering again; then agent_notes gets the chat’s note. A changed server definition needs no reload: the bridge connects again and tells Claude notifications/tools/list_changed.

The plugin that exposes (its manifest’s exposes, plugins; Vendetta ships tailscale) serves each target (the admin’s app endpoint, each instance’s) by port and at its own name (plugins). The worker moves a target’s address in use to its name once the name answers, and back to its port when it stops answering, only between those two addresses. It keeps the address in its state (app-address.json: the admin’s in its own, each person’s in theirs), never in a config; the endpoint’s plugin asks for it with app_address.

Method Callers Result
expose_targets {} the plugin that exposes {targets: [{id: "admin"|"instance:NAME", instance?, port}]}: the port of the app endpoint, and every instance not being removed.
expose_sync {} any Publishes expose, so the plugin passes now; instance add and remove call it, then poll tailnet. {}.
expose_report {node, targets} the plugin that exposes Its status, whole; kept until the next report or until its connection ends.
app_address {} any {url, port}: this worker’s app endpoint’s address in use (where the worker moved it, else the endpoint’s own public_url) and its listen port; each null without an endpoint. The endpoint’s plugin uses url for pairing and links; vendetta page link and instance add read it.
tailnet {} any The latest report with plugin: "running", each target with port_url, service_url, url (the address in use), and note; or {plugin: "unavailable", node: null, targets: []}.

node: {host, tags, ports} (every port tailscale serves, anything’s), or {error}. Each target: {id, port, port_state: "served"|"taken"|"failed"|"unknown", port_error?, service?, host?, state: "off"|"waiting"|"answering"|"unavailable", error?}. waiting is served but not answering, as before a tailnet admin defines its Service and approves its host. note is a sentence for the owner, its one-time steps among them: define svc:NAME with endpoint tcp:443, then approve this machine as its host or add the policy. policy (top level, and on each waiting target) is the tailnet policy that approves every current name at once.