Building on itContribute
Contribute
How to build Vendetta, find the checks a change needs, read the rules for the area you touch, and commit.
This page is for anyone changing Vendetta’s own code. It covers the build, the tests, where the rules for each area live, and how changes are committed.
You need Linux or macOS and a stable Rust toolchain. The rest depends on what you build:
| For | You need |
|---|---|
| Building on Linux | A C toolchain, pkg-config, clang, and the ALSA and PipeWire development files |
| The web client | Bun, Rust’s wasm32-unknown-unknown target, and wasm-bindgen-cli at the version crates/kit/Cargo.toml pins |
| The HUD and the Hyprland dictation frontend | GTK 4.20+ and gtk4-layer-shell |
| The terminal tests | tmux 3.3+ |
cargo build --release --lockedbash install.sh builds and installs everything into ~/.local/bin, which replaces the Vendetta you are running. While you work on a change, run the tests instead: they start their own workers on their own state.
The map
Section titled “The map”AGENTS.md at the repository’s root is the map. It says what each top-level folder holds:
| Path | Holds |
|---|---|
src/ |
The vendetta binary: worker, scheduler, and CLI, a module per area |
apps/tui |
The chooser, vendetta tui |
crates/ |
Shared libraries: protocol, host, tmux, schedule, ui-common, and others |
plugins/ |
One binary per plugin |
integrations/ |
What runs inside providers, and the agent skills |
web/, ios/ |
The apps |
docs/ |
User docs; docs/dev/ holds the rules for areas of src/ |
tests/ |
Integration tests, and map.toml |
Each file in src/ starts with a //! line that says what it holds.
Read before you change an area
Section titled “Read before you change an area”Every area has a file with its rules, notes on its files, and its tests. AGENTS.md has the full table; these are the ones most changes meet:
| Touching | Read first |
|---|---|
The worker, the control socket, plugin supervision, crates/protocol |
docs/dev/worker.md |
| Agents, control methods, projects, schedules, webhooks | docs/dev/agents.md |
| The chooser | docs/dev/chooser.md |
The app transport, web/, ios/ |
docs/dev/apps.md and crates/chat-router/AGENTS.md |
| Telegram, Discord | crates/chat-router/AGENTS.md, then plugins/telegram/AGENTS.md or plugins/discord/AGENTS.md |
| Hosts and keys | crates/host/AGENTS.md |
| Plugin UI | docs/dev/plugin-ui.md |
| The Claude integration | integrations/claude/AGENTS.md |
| People, sharing, machines, providers | docs/dev/people.md |
A new rule goes in its area’s file, never in the root AGENTS.md. A new area gets a file of its own and a row in the table.
What every change keeps
Section titled “What every change keeps”The root AGENTS.md lists behaviour no change may break. In short:
- tmux is optional. Agents are found in the process list and identified by boot, PID, and process start time. A pane is only where an agent shows.
- A status record matches both PID and start time. Quiet output alone never makes a running agent idle.
- Status hooks only observe. Only the owner makes approval decisions.
- Vendetta’s state never holds prompts, answers, messages, or tool arguments.
- Installing an integration preserves the provider’s other hooks, extensions, and config.
- The worker, the scheduler, and every plugin exit on any panic and when a main loop stops beating, so a supervisor restarts them. Every blocking call in a watched loop has a bound below that limit.
Find the checks a change needs
Section titled “Find the checks a change needs”tests/map.toml maps files to the checks their change needs. Ask it:
python3 tests/run.py --changed # what the diff from main needs
python3 tests/run.py --changed BASE # from another base
python3 tests/run.py PATH... # what changing these files needs
python3 tests/run.py --changed --run # run them
python3 tests/run.py --check # the map covers every test, and its globs match files--changed counts committed, staged, unstaged, and untracked changes. The output names what to build first, then each check and the files that call for it:
First:
cargo build --release --locked
Checks:
cargo fmt --all --check
for: plugins/dashboard/src/page.rs
python3 tests/plugin_ui.py
Plugin UI end to end: an owned worker running the real messaging and
for: plugins/dashboard/src/page.rs--run runs the before commands, then each test through tests/slot, and goes on past failures. It exits nonzero if any failed. tests/slot has every checkout on the machine take turns at builds and integration tests, so several work trees can test at once.
Some tests name what the machine must have, such as a provider’s CLI, Chrome, or Docker. A test with no paths in the map is run by hand.
The core checks
Section titled “The core checks”Rust changes run:
cargo fmt --all --check
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warningsChanges to the omp and OpenCode extensions run:
bun install --frozen-lockfile --ignore-scripts
bun test tests/omp.test.ts tests/opencode.test.tsWeb client changes run, in web/:
bun install && bun run check && bun run test && bun run e2eiOS changes run ios/scripts/kit-test.sh, which tests VendettaKit on Linux.
When a wire type changes, regenerate the clients’ types and fixtures:
UPDATE_WIRE=1 cargo test -p vendetta-app-wire wire_types
UPDATE_WIRE=1 cargo test -p vendetta-app fixturesWriting a test
Section titled “Writing a test”- A new test gets an entry in
tests/map.toml. - A live test uses its own tmux server, state directory, sessions, and clients.
tests/owned_worker.pystarts a worker on isolated state and gives a client of its control socket. - Never repurpose
HOMEorCODEX_HOMEin a test. - Wait for rendered state, never a fixed delay. Raw terminal output can hold partial redraws, so assert a navigation result or the rendered screen.
- Detach a test’s client before removing its session.
- Keep captured transcripts and credentials out of the repository.
The terminal tests use synthetic model and Bot API endpoints on loopback, so they never touch your sessions or agents.
Change the docs with the code
Section titled “Change the docs with the code”- A method or event change updates
docs/protocol.mdin the same commit. A frame change updatesdocs/app-protocol.md. - A change to public behaviour or a default updates
docs/, the README where it says the same thing, andconfig.example.toml. - A change to what an agent can send the owner, or how, updates the
vendetta,vendetta-pages, andvendetta-alertsskills.
Docs are terse and written for the person using the thing. They carry no history of what a feature replaced.
Commits
Section titled “Commits”- Commit after every meaningful change, before starting the next independent one.
- Keep a change focused. Leave edits you didn’t make alone, even when they look wrong.
- Add no compatibility shims, migrations, or dual paths for a superseded format unless asked. Vendetta makes no backward compatibility guarantee between versions.
Subjects name the area, then say what is now true:
worker: a turn that ends across a restart or an unknown spell is told
tests: claude_deploy checks a deploy never unlinks a running Claude sessionAdding a plugin to Vendetta
Section titled “Adding a plugin to Vendetta”- Put the crate in
plugins/<name>, with a binary namedvendetta-<name>. - Add the name and its manifest to
SHIPPEDinsrc/plugins.rs, so it needs nocommand. - Install the binary from
install.sh. - Have its config reject unknown keys while accepting
commandandenabled. - Test it on owned state, and add it to
docs/plugins.mdandconfig.example.toml.
Write a plugin covers the plugin itself, and Design rules the look a change to the apps keeps.