Running itProject file
Project file
A vendetta.toml at a project’s root declares agents that always run and
schedules for that project. Nothing in it runs until you trust the folder.
# vendetta.toml
project = "shop" # optional: the project (tmux session) its agents open in;
# default: the one the folder shows under
[agents.lead]
name = "Lead"
provider = "claude" # omp, codex, or claude; default: [harnesses] default
model = "opus"
effort = "medium"
cwd = "." # inside this folder; default "."
manager = true
brief = """
You lead the shop rewrite. ...
"""
[agents.backend]
name = "Backend"
manager = "lead" # in lead's team
brief = "You own the API ..."
[schedules.nightly-review]
cron = "0 3 * * *" # or at = "2026-12-01T09:00:00+02:00", or neither: run now only
timezone = "Europe/Athens"
agent = "lead" # prompt this declared agent
prompt = "Review yesterday's merges."
[schedules.weekly-deps]
cron = "0 9 * * 1"
provider = "codex"
reuse = true # or new = true (the default)
cwd = "backend"
prompt = "Check for outdated dependencies."vendetta project status # project files Vendetta found, and each agent's state
vendetta project adopt FOLDER ID AGENT # bind declared agent ID to one already runningAn agent already doing a declared agent’s work can be adopted, before or after trusting,
so trusting starts none beside it: AGENT is its conversation or process key from
vendetta agent list, of the declared provider, in the folder (or its machine). Only you
may, from a terminal you can see.
Trust or untrust a folder, and start a paused or failed agent, from the chooser or the Vendetta app.
In the chooser, a project’s row marks its file right after its name: ⚿ waiting for
trust, ‼ invalid, ∅ missing, ⧗ items awaiting approval; the preview says why, and the
overview lists such files under what needs you. Inside the project, the file has a row
of its own, ≡ vendetta.toml and its state, holding its schedules and the declared
agents not running at the top of their team. Left and Right fold and open it; it is
open while the file or a declared agent needs you and folded otherwise, until you fold
or open it, which the chooser remembers for that folder. Enter on it shows the folder,
its state and error, every agent and schedule it declares, and what waits for approval.
A on the project, its file row, or that info confirms trusting, approving, or
untrusting it with the agents and schedules it runs. Declared agents carry ≡ and their
state (‖ paused, ✗ failed, ⚠ start uncertain, ⊖ superseded, ⧗ awaiting approval,
◷ waiting to start); those not running are listed beneath their declared manager, and
Enter starts a paused or failed one. File schedules are marked ≡ on the schedules
screen, which offers pause and run now but not edit or delete. (These are the text
glyphs; Nerd Font icons replace them when installed.)
Vendetta finds vendetta.toml at the root of every project it knows: the git root
of a folder an agent runs or ran in, or a tmux session’s folder. A file that names no
project belongs to the project its folder shows under: a tmux session’s there, else a
running agent’s, else a recorded one’s, else the folder’s name; once its agents run,
theirs while the folder still shows under it. An untrusted file
shows as waiting for trust in the chooser, the apps, and status; nothing in it runs.
Trust belongs to the folder. Trusting it approves every agent and schedule its file
declares then; later edits to those apply without asking. An agent or schedule id
added afterwards waits as awaiting approval, started or scheduled only once you
approve it, and one removed and added back needs approval again: an agent in the
repository or a git pull cannot add work that runs unasked. Only you trust a folder
or approve what it adds, from the chooser or the app; a shell, agents, the Master,
schedules, Telegram, and Discord cannot. Trusting and approving take the file’s hash as
you were shown it, and are refused (changed) if the file changed since, and while it
does not check: fix it first. This keeps
agents from doing it by accident, not a boundary: an agent of your user can edit
Vendetta’s state files, as it can anything of yours. A git worktree is its
own folder and needs its own trust. Moving or recreating a trusted folder ends its
trust.
Untrusting stops Vendetta managing the file: its agents keep running as ordinary agents and its schedules are removed. Trusting it again picks up the same conversations. A folder that no longer exists can still be untrusted by the path it was trusted at; gone folders do not count toward the 256 trusted ones.
Agents
Section titled “Agents”Each [agents.ID] is always running. Vendetta starts it the first time, with its
brief as its first prompt, and resumes the same conversation whenever it exits,
crashes included. An agent that keeps exiting soon after starting is marked failed
and you are told; it waits for you to start it again.
- Stopping a declared agent from the chooser or the app pauses it: it is not restarted until you start it again. Agents, managers, and idle timeouts cannot stop one.
- Deleting its conversation pauses it too; its next start is a fresh conversation with its brief. Auto-delete never deletes one.
nameis its name everywhere; rename it in the file, as clients refuse to.modelandeffortapply from its next start or resume. A member without them takes its manager’s team choices, else[harnesses.PROVIDER] team’s.providerorcwdchanged, or the agent removed from the file: the running conversation is left running as an ordinary agent, marked superseded, and a changed agent starts fresh./exitor Ctrl+D in the agent’s terminal reads as an exit: Vendetta resumes it. To stop one, stop it from Vendetta, which pauses it.manager = truestarts it as a manager, withbriefas its request.manager = "ID"puts it in that declared agent’s team, muted, as agents a manager starts are. Teams nest: a manager can be in another manager’s team. The file names one manager; managers added from a client stay alongside it, and changing or removingmanagertakes it out of only the declared one’s team.
Container projects
Section titled “Container projects”A container project’s file is the one in its machine’s clone, which its agents work on and may change. It is trusted from the chooser or the app as any other, and what it declares runs in the machine:
- Its agents start, resume, and restart in the machine, and its teams are the
machine’s. A
projectnaming anything else is ignored, whichstatusnotes: the same file may serve a host checkout. - A stopped or unreachable machine’s agents wait for it: nothing starts the machine, and nothing in it counts as exited until it runs again.
- Its agents are kept from the machine’s other agents as the host keeps them: the
host tells the machine which they are, and its worker refuses stopping, quitting,
renaming, or deleting one. Inside a machine this keeps them from accidents only:
anything there can act as its worker. A machine made before this needs
recreatefor it. - An agent whose conversation is gone from the machine fails (
conversation_gone); starting it again starts a fresh one with its brief. modelandeffortapply when an agent starts fresh, not when it resumes.- The host reads the file through the machine, never from the clone itself, at least every 30 seconds while the machine runs.
- Shared with another person, every change to an agent or schedule waits for your approval, as an added one does: it shows as awaiting approval and runs on as you last approved it until you approve the change.
- A person’s container projects work the same for that person: their app or chooser trusts and approves, as their owner; the admin is not asked. Nothing runs on the host.
Schedules
Section titled “Schedules”Each [schedules.ID] is a schedule like any other, kept in step with the file:
added, changed, and removed as you edit it. The chooser and apps show them
read-only; you can pause one, run it now, and acknowledge an uncertain run. A pause
stays in Vendetta, not the file. To change one, edit the file.
- Timing:
cron(withtimezone),at, or neither (run now and webhooks only). agent = "ID"prompts that declared agent while it runs; a run while it is paused, failed, or starting fails and is not retried.- Otherwise
provider,cwd, andnew = true(default) orreuse = true, asvendetta schedule addtakes them.
Errors
Section titled “Errors”A file that does not parse or check changes nothing: running agents and schedules
stay as they were, and the chooser, apps, and status show why. Neither does a file
that is gone or empty, as switching branches or an editor writing in place leaves it:
it shows as missing, and what it declared runs on. To stop managing a folder, untrust
it, or take the agents out of a valid file. Unknown keys are
errors. Limits: 64 KiB, 32 agents, 64 schedules; IDs are 1–64 of a-z0-9_-;
cwd must be a folder inside the project; a manager = "ID" must name a declared
agent, with no cycles. A file in the Master’s project is refused (the Master runs
alone there).
Wire and state
Section titled “Wire and state”For implementers and client authors; docs/protocol.md and docs/app-protocol.md
carry the final contract.
src/projects/file.rs (parse, check, discovery, trust, the declared store) and
src/projects/reconcile.rs (the worker’s thread). Team calls go through one function,
project_reconcile::place_in_team(manager, member), which calls the worker’s own
assign_agents and mute_agents; a refused placement shows as that agent’s
reason. A member whose manager has a conversation is created in its team, through
Control::create_for, the worker’s own create_agent for a manager: it starts muted,
and a sub-manager’s brief names its manager. Agents cannot reach it.
State files
Section titled “State files”In the state directory, each 0600 with a .lock, written atomically, bounded:
project-trust.json:{folders: {CANONICAL_PATH: {dev, ino, trusted_ms, approved}}}, at most 256 live ones. A folder whose(dev, ino)differs is untrusted.approvedholdsagent:IDandschedule:ID: the file’s ids when it was trusted, then each one the owner approved; a valid file that drops an id drops its approval.versionsholds each one’s content digest as approved, or as applied while the project is not shared.project-agents.json:{agents: [Declared]}, at most 1024, one per(folder, id):{folder, id, provider, cwd, process_key?, conversation_key?, session_id?, paused, failed?: {reason, at_ms}, superseded, untrusted, starting?: at_ms, spec: {name?, model?, effort?, manager, managed_by?}}. A superseded entry is an old binding left unmanaged after a provider or cwd change, or its id left the file; it is kept until its conversation is deleted, so an id back in the file with the same provider and folder takes back that conversation instead of a fresh one.specis the last checked file’s, without the brief, so an invalid file or a worker restart keeps resuming as before. No prompt or brief text is stored.
Schedule state stays in schedules/state.json.
Identity
Section titled “Identity”A first start is the worker’s create_agent (manager: true and task: brief for
a manager; otherwise the brief by send_message once the agent takes input, as a
schedule’s prompt). The record takes the pane root’s process key at once and the
conversation key (provider:session_id) when discovery names it, as teams.json
does. Later starts resume exactly that session_id through the launch journal’s
ResumeGuard, with the file’s current model and effort. Nothing is ever adopted
by name, cwd, or title. What can fail before the host is asked to launch is checked
first; any error after that, or a fresh agent that never shows, leaves the outcome
unknown, as does a starting left over from a worker that stopped: such a start is
never repeated, and the agent turns failed (start_uncertain, with what happened)
until the owner starts it. A resumed agent that never shows goes back on the backoff:
its next try runs through the resume journal, which refuses while anything runs that
conversation or the last launch’s pane root has not exited. The start fence is set under the store’s lock only while
the binding is as the pass saw it, so a pause, deletion, or failure since wins, and a
resume takes the conversation recorded now. While its file is invalid or missing, a
binding resumes from what it recorded (project, name, model, effort, team); a fresh
start needs a valid file for its brief. Its folder is checked again at every launch.
Reconciler
Section titled “Reconciler”A watched thread in the worker, like auto-delete, active while any trusted file declares something.
- Files: an inotify watch on each trusted folder (via
file_wake), counting onlyvendetta.toml; files are read again every 30 s regardless, and candidate roots found again once a minute. A file must be a regular file owned by the user. - Exits: it takes the worker’s agent listings (
Server::agent_watcher) only while a trusted folder declares an agent, never scanning on its own. A declared agent has exited when no listed agent has its conversation (or process) key and its recorded process is confirmed gone (boot or start time differs), so a host restarting never reads as an exit. - Pacing: restarts wait 5 s, 30 s, 2 min, then 10 min after each quick exit
(a run under 5 minutes, or a launch that certainly failed); a
run of 5 minutes resets it. The fifth quick exit in a row marks it
failed(crash_loop) and tells the owner: an alert, asvendetta alertsounds (the app and web), and a HUD notification. At most one start in flight and four a minute across all files, so a login starts declared agents a few at a time. Counters live in memory. - Pause:
close_agentfrom the owner and the chooser’s confirmed close setpausedbefore their signal (cleared again if the signal is refused). The owner’s deletion of the conversation setspausedand dropssession_idand both keys.close_agentand asend_messageof/exitor/quit(and/q,/bye) from anyone but the owner and the apps, schedules included,close_idle_agent, a manager’sdelete_agent, andrename_agentrefuse a declared agent.resume_agentof a declared conversation is the owner’s alone: it clears the pause or failure and holds the start fence for that resume. A start writes back what it started only while its fence is its own, and an agent that exits before its provider names its conversation turnsstart_uncertaininstead of starting a fresh one beside it. - Teams: after each start it places members in their declared manager’s team and mutes them on joining. It releases a pairing the file dropped, and never touches team links of undeclared agents. A container project’s are placed in its machine’s teams through the worker’s routing, as the worker’s own calls, and read from the machine’s reported teams; names likewise.
File schedules
Section titled “File schedules”Schedule gains source: {kind: "file", folder, id, agent?}. The record’s id is
file- + the first 12 hex digits of SHA-256(folder) + - + the file’s id.
tmux_session is the file’s project; cwd the resolved folder. The worker syncs
them under the scheduler’s state.lock, like plugins’ schedules: new ones are
added enabled, changed ones replace configuration only (claims, pause, recovery,
history, and a reusing schedule’s conversation stay, as update keeps them), and
ones no longer in a trusted, valid file are removed. add refuses the file-
prefix; update and remove refuse file schedules; enable, disable, and
run_schedule accept them. A run with source.agent resolves the declared agent’s
conversation at dispatch and only prompts it live (declared_not_running
otherwise); it never launches.
Control socket
Section titled “Control socket”| Method | Who | Notes |
|---|---|---|
project_files {} |
any client | {files: [{folder, project, hash, state: "untrusted"|"invalid"|"missing"|"trusted", error?, agents: [{id, name, state: "running"|"starting"|"waiting"|"paused"|"failed"|"superseded"|"awaiting_approval"|"untrusted", reason?, conversation_key?, manager?, provider, model?, effort?, manages}], schedules: [{id, cron?, at?, timezone?, agent?, provider, reuse, cwd?}], pending: [{kind, id, agent?, schedule?}]}]}: what the file hash names runs, never a prompt or brief; while it does not check or is missing, what is in effect, and no pending |
trust_project {folder, trusted, hash} |
owner | Refused with changed when the file is not the one hash names, and when it does not check. The owner and supervised plugins only; the app plugin offers it only to app devices. The owner’s terminal must show to a person (protocol): a detached tmux window or setsid, which an agent can start outside its ancestry, is refused. |
start_declared {folder, id} |
owner | Clears paused and failed and the backoff; the next pass starts or resumes it. |
adopt_declared {folder, id, agent, hash} |
owner | Binds declared id to a running agent (handle, conversation or process key): the declared provider, in the folder or its machine, its conversation named. Before trust too. |
approve_project_item {folder, kind, id, hash} |
owner | Approves an agent (kind: "agent") or schedule added to a trusted file since it was trusted, or in a shared container project changed since it was approved; the next pass starts, schedules, or applies it. |
Event project_files: a file appeared, changed, or was trusted, or a declared
agent’s state changed; agents and history follow.
list_agents and list_history entries of a declared agent carry
declared: {folder, id, paused, failed?}. Scheduler list/status records carry
source. The overview adds project_files: those untrusted, invalid, missing, or
with items awaiting approval, {folder, project, state, error?, pending}.
App wire (crates/app-wire)
Section titled “App wire (crates/app-wire)”Declared {folder, id, paused, failed: Option<String>};declared: Option<Declared>onTopicandOverviewAgent.ProjectFile {folder, project, hash, state, error, agents: Vec<DeclaredAgent>, schedules: Vec<FileSchedule>, pending: Vec<PendingItem>}andOverview.project_files.DeclaredAgent {id, name, state, reason, conversation_key, manager, provider, model, effort, manages}:manageris its declared manager’s id, so clients nest agents not yet running.FileSchedule {id, cron, at, timezone, agent, provider, reuse, cwd}.PendingItem {kind, id, agent, schedule}. The trust and approve dialogs list these.OverviewSchedule.file: bool. Appschedule listpassessourcethrough.- App requests
trust_projectandstart_declared; typeshare outputs regenerated.
Changes from the draft
Section titled “Changes from the draft”enabledin a file schedule is dropped. One flag can’t be both the file’s and the owner’s pause; the pause lives in state, and removing the schedule from the file turns it off.- Providers: declared agents need a provider Vendetta resumes (omp, Codex,
Claude Code). File schedules take no
session_id: conversation IDs are local to one machine. /stopinterrupts a turn in messaging today and leaves the process running, so it does not pause. The app’s and chooser’s stop/close do.projectis new: the tmux session the Agents window opens in.- Agents not running yet (never started, paused before a conversation,
failed) are in no listing, so
project_filescarries each declared agent’s state, and clients draw Start from it.