Building on itArchitecture
Architecture
The worker, its control socket, hosts, plugins, and clients, and which of them talks to which.
This page maps Vendetta’s processes and the sockets between them. Read it before you write a plugin, a client, or a change to the core.
Claude Code Codex omp OpenCode Gemini CLI Aider
│ found in the process list; each reports state through
│ its own hook, extension, or Mod
▼
┌────────────────────────────────────────────────────────────┐
│ Worker, one per user │
│ agents, history, schedules, teams, alerts │
└──────────────────────────┬─────────────────────────────────┘
│ control socket (Unix, JSON lines)
┌──────────────┬──────┴────────┬──────────────────┐
▼ ▼ ▼ ▼
Chooser vendetta CLI Host plugins Other plugins
vendetta tui agent, service tmux, Kitty hud, speech, webhooks,
│ schedule, … ▲ dashboard, diff, …
│ │
└──── host sockets ────────────┘ Chat plugins
panes, screens, input │
├── telegram, discord
└── app
WebSocket /v1, loopback
│
web client, iPhone appThe worker
Section titled “The worker”One workerWorker. The background process everything talks to, one per user. Start it with vendetta notify start. runs per user. vendetta notify start starts it, and everything else connects to it.
- It finds agents among your processes and identifies each by boot, PID, and process start time. A terminal pane is only where an agent shows.
- It reads each agent’s state from the provider’s integration: hooks for Codex and Gemini CLI, an extension for omp, a plugin for OpenCode, a Mod for Claude Code, and a launcher for Aider.
- It keeps history, teams, alerts, project colours, and the state of schedules. The journals hold states and metadata, never prompts, messages, or tool arguments.
- It starts every enabled plugin, restarts one that exits, and stops them when it stops.
- It makes every check. A caller asks, and the worker decides.
The worker, the scheduler, and every plugin exit on a panic or a stuck main loop, so their supervisor restarts them.
The control socket
Section titled “The control socket”The worker serves one Unix stream socket per state directory:
$XDG_RUNTIME_DIR/vendetta/control/<hash>.sockIt is mode 0600, and a peer must share the worker’s user. Each line is one JSON object: a request, a response, or an event.
{"type":"request","id":1,"method":"list_agents","params":{}}
{"type":"response","id":1,"result":{"agents":[]}}
{"type":"event","seq":4,"event":{"kind":"agents"}}What a caller may do depends on who it is, which the worker reads from the kernel’s record of the connection, never from a request field:
| Caller | Who that is |
|---|---|
| Any client | Any process of yours. It gets the agent tools: list, read, send, interrupt, create, resume, schedules. |
| A supervised plugin | The exact process the worker started. |
| The owner | A process of yours that is not an agent and runs on a terminal you can see, such as the chooser or a shell. A cron job or a detached pane is not. |
Events say what changed, never the new data. A subscriber rereads through the same methods, so every read passes the same checks. Plugin protocol lists every method and event.
A hostHost. A terminal Vendetta can read, type into, and launch in: tmux or Kitty. gives Vendetta a terminal or multiplexer: it lists panes, reads and types into them, launches in them, and shows them. tmux and Kitty ship as the plugins host-tmux and host-kitty.
A host is a plugin that also serves a socket of its own:
$XDG_RUNTIME_DIR/vendetta/hosts/<control socket's name>-NAME.sockThe worker and the chooser both connect to host sockets. The worker launches and types through them; the chooser draws the pane tree and navigates. Hosts are optional: agents in a plain terminal are still listed, and the worker reaches them through their provider’s own channel and signals. Host protocol is the wire contract.
Plugins
Section titled “Plugins”A pluginPlugin. A separate program the worker starts and supervises. Messaging, the HUD, dictation, tmux, and the overview are plugins, and you can write your own in any language. is a separate program on the control socket. Telegram, Discord, the apps, the HUD, dictation, speech, webhooks, the Overview board, Changes, and the Tailscale and GitHub integrations are all plugins. A plugin can:
- read agents and react to events;
- serve methods the worker, other plugins, the chooser, and agents call;
- put buttons and pages into the apps and the chooser, as data;
- keep schedules of its own;
- register
vendettacommands.
Plugins lists the ones that ship. Write a plugin builds one.
Clients
Section titled “Clients”Every client goes through the worker, so the terminal, the apps, and the bots follow the same rules.
| Client | Connects to |
|---|---|
The chooser, vendetta tui |
The control socket, and the hosts’ sockets for panes |
vendetta agent, vendetta schedule, vendetta service |
The control socket |
| A Master or manager agent | The control socket, through vendetta agent |
| Telegram and Discord | The telegram and discord plugins, which call those services’ bot APIs |
| The web client and the iPhone app | The app plugin |
The app transport
Section titled “The app transport”The app plugin serves one WebSocket endpoint, /v1, on a loopback address (127.0.0.1:8743 unless [plugins.app] listen says otherwise). Plain HTTP requests on the same port serve the built web client, so the page and its socket share an origin.
Nothing listens beyond loopback until you publish the port, with the Tailscale plugin or a reverse proxy of your own. Each device pairs once with a single-use code and then signs in with its token.
The apps hold no logic of their own about agents. The app plugin turns the worker’s state into chats, messages, and events, and both apps share one Rust library for what they do with them. App protocol is the contract; Write a client starts one.
People and machines
Section titled “People and machines”A person you add gets a Vendetta of their own on your computer: their own worker, plugins, chats, and Master. A project machine is a container that runs a project’s agents on a private clone. Both link back to a worker over sockets, and neither changes the picture above. See People and Project machines.
Where the code is
Section titled “Where the code is”| Path | Holds |
|---|---|
src/ |
The vendetta binary: worker, scheduler, and CLI |
apps/tui |
The chooser |
crates/protocol |
Wire types and the blocking client |
crates/host, crates/tmux |
What a host provides, and tmux as one |
plugins/ |
One binary per plugin |
integrations/ |
What runs inside providers, and the agent skills |
web/, ios/ |
The apps |
crates/app-wire, crates/kit |
The app transport’s types, and the logic both apps share |