Skip to content
Docs0.9GitHubInstall

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 app

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 worker serves one Unix stream socket per state directory:

$XDG_RUNTIME_DIR/vendetta/control/<hash>.sock

It 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.sock

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

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 vendetta commands.

Plugins lists the ones that ship. Write a plugin builds one.

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

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.

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