Skip to content
Docs0.9GitHubInstall

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

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

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.

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.

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.

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.

Rust changes run:

cargo fmt --all --check
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings

Changes to the omp and OpenCode extensions run:

bun install --frozen-lockfile --ignore-scripts
bun test tests/omp.test.ts tests/opencode.test.ts

Web client changes run, in web/:

bun install && bun run check && bun run test && bun run e2e

iOS 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 fixtures
  • 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.py starts a worker on isolated state and gives a client of its control socket.
  • Never repurpose HOME or CODEX_HOME in 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.

  • A method or event change updates docs/protocol.md in the same commit. A frame change updates docs/app-protocol.md.
  • A change to public behaviour or a default updates docs/, the README where it says the same thing, and config.example.toml.
  • A change to what an agent can send the owner, or how, updates the vendetta, vendetta-pages, and vendetta-alerts skills.

Docs are terse and written for the person using the thing. They carry no history of what a feature replaced.

  • 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 session
  • Put the crate in plugins/<name>, with a binary named vendetta-<name>.
  • Add the name and its manifest to SHIPPED in src/plugins.rs, so it needs no command.
  • Install the binary from install.sh.
  • Have its config reject unknown keys while accepting command and enabled.
  • Test it on owned state, and add it to docs/plugins.md and config.example.toml.

Write a plugin covers the plugin itself, and Design rules the look a change to the apps keeps.