Skip to content
Docs0.9GitHubInstall

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 running

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

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.
  • name is its name everywhere; rename it in the file, as clients refuse to.
  • model and effort apply from its next start or resume. A member without them takes its manager’s team choices, else [harnesses.PROVIDER] team’s.
  • provider or cwd changed, 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.
  • /exit or 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 = true starts it as a manager, with brief as 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 removing manager takes it out of only the declared one’s team.

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 project naming anything else is ignored, which status notes: 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 recreate for it.
  • An agent whose conversation is gone from the machine fails (conversation_gone); starting it again starts a fresh one with its brief.
  • model and effort apply 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.

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 (with timezone), 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, and new = true (default) or reuse = true, as vendetta schedule add takes them.

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

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.

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. approved holds agent:ID and schedule: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. versions holds 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. spec is 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.

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.

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 only vendetta.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, as vendetta alert sounds (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_agent from the owner and the chooser’s confirmed close set paused before their signal (cleared again if the signal is refused). The owner’s deletion of the conversation sets paused and drops session_id and both keys. close_agent and a send_message of /exit or /quit (and /q, /bye) from anyone but the owner and the apps, schedules included, close_idle_agent, a manager’s delete_agent, and rename_agent refuse a declared agent. resume_agent of 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 turns start_uncertain instead 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.

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.

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

  • Declared {folder, id, paused, failed: Option<String>}; declared: Option<Declared> on Topic and OverviewAgent.
  • ProjectFile {folder, project, hash, state, error, agents: Vec<DeclaredAgent>, schedules: Vec<FileSchedule>, pending: Vec<PendingItem>} and Overview.project_files.
  • DeclaredAgent {id, name, state, reason, conversation_key, manager, provider, model, effort, manages}: manager is 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. App schedule list passes source through.
  • App requests trust_project and start_declared; typeshare outputs regenerated.
  • enabled in 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.
  • /stop interrupts a turn in messaging today and leaves the process running, so it does not pause. The app’s and chooser’s stop/close do.
  • project is 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_files carries each declared agent’s state, and clients draw Start from it.