Several agents taking turns on one goal, with a check between turns that decides by numbers, not opinions — directed by Argus on the server, so a team goes on with every browser shut.

flowchart LR
  planner["planner"] --> exec["executor"]
  exec --> check{{"cargo test --release"}}
  check -->|PASS| rev["reviewer · judges"]
  check -->|FAIL| exec
  rev -->|OK, REDO| planner
  rev -->|DONE| done((done))

That diagram is a team: paste it into Draw or write and Argus draws it; give it a goal and a folder and press Start. This page explains every part of it.

• In one minute
• Starting one
• What a turn is, step by step
• How an agent reports its turn — the Argus tools, the shell, the file
• The shapes that ship
• Drawing your own — clicks, Mermaid, YAML
• Asking an agent to design one — it writes, checks and proposes; you start
• Roles, models and packs
• Watching it
• Pause, Stop, Reset, Restart — and what "from clean" means for your team
• When something is stuck
• Questions

Each agent runs in a tmux session of its own, <team>-<step>, in a window of the desk: you can watch it, type into it, or take over at any moment. Argus never reads a screen to know what happened — the agents tell it.

Team in the desk's toolbar (it needs --allow-write: a team writes into the project). Up front, three things:

1. What should the team get done? In words: make the alignment faster without changing its results. The shape follows from the words — faster picks Optimise, crash picks Fix a bug, paper picks Write — and a card changes it. Four cards are shown (Build and review, Optimise, Fix a bug, Write) plus yours and any proposed by an agent; N more… shows the rest, and find a team above them filters every card by name, description, pack or role.
2. The team — the graph, drawn. Click a step to change it (below), or Draw or write.
3. In — the folder. Required, never defaulted to your home: the team writes its log and its files there. Choose… walks the folders Argus serves, or makes a new one; a folder that does not exist is made when the team starts. Under the box it says there, to be made, or outside the folders Argus serves — that last one means the path is not under any of the roots in the config, and Start stays off.

Before you start, the sheet says what each agent chosen would be missing in a team, with the fix where there is one: no Argus plugin, or an old one (Install / update — without it the agent reports by writing to the log, which works but nobody checks until the next round); Codex asking before team_task and team_done (Allow them — in a team nobody is there to say yes; it writes approval_mode = "approve" for the two in ~/.codex/config.toml, keeping a copy); Codex's hooks never heard yet (open Codex once and accept them, or there is no Stop guard); Gemini (no Stop guard); a shell (not an agent: it takes no turn). Nothing stops you starting anyway.

When a step is a check with no command yet, the check asks for one, suggested from the folder (cargo test --release, a benchmark script, python3 -m pytest -q, npm test, make test, nextflow run main.nf -profile test). That one box fills every check step without a command; to give two checks different commands, click each step.

Everything else is under More, and good as suggested:

• Who does what — which of your launchers runs each agent step; a different agent per step where there is a choice (two minds, not one twice). In a git repository, each step has in its own copy: ticked, it works in a worktree on a branch team/<team>-<step>, so your checkout is not touched.

• What they may do without asking — ask me / edit files freely (the default) / everything, no questions, turned into each agent's own option (--permission-mode acceptEdits, --dangerously-skip-permissions, Codex's sandbox and --yolo) where its version has it. Everything is said in red under the folder, whoever chose it.

• How much it goes on alone

  • Ask me at the end of each round: you press Continue. The safest way to start.
  • Go on, stop if something goes wrong: it stops at the second failed check in a row.
  • Go on until the goal: it keeps trying through failed checks, until a judge says DONE or the rounds run out (10 by default, 30 at most).

  Whatever you chose, BLOCKED (from anyone) stops it and asks you, and so does a verdict with no arrow drawn for it.

• At most, rounds, and the buttons for files and packs (below).

• Arrange the desk — as a grid (the default), in columns, in rows, or leave it as it is: how the team's windows are laid out when it starts and each time one of its agents arrives, so they sit side by side instead of one on top of the other. A pinned window stays where you put it.

More opens by itself when something in it needs you — no agent among your launchers, or a start that was refused.

sequenceDiagram
  participant D as Argus (director)
  participant A as agent (its own session)
  participant L as TEAM.argus.md
  participant C as check (its own session)
  D->>A: starts it, first prompt on its command line
  A->>D: team_task — goal, duty, round, what came before
  Note over A: one turn of work
  A->>D: team_done — summary (+ verdict if it judges)
  D->>L: writes the turn, signed
  A--xD: tries to stop without reporting? the Stop guard sends it back (twice at most)
  D->>C: runs the check, if the flow says so
  C->>L: PASS / FAIL, exit code and the last lines
  D->>D: follows the arrow for PASS/FAIL or the verdict

1. An agent starts when its turn first comes, not all at once. Its first prompt travels on its command line (claude "…", codex "…", gemini -i "…"), so it runs as soon as the agent is ready, whatever the agent asks first; and the folder is recorded as trusted in Claude Code and Codex beforehand — the answer you would give to "trust this folder?".
2. The prompt says who it is, the goal, the folder, its duty, who came before it this round, a failed check to deal with first, and how to report.
3. It reports. Argus checks the report (is it this agent's turn? has it reported already? did a judge give a verdict?) and writes it into the log.
4. The check, when the arrow leads to one, is typed into the team's check session as if you had typed it. Its exit code decides; its last lines go in the log, in front of whoever is next.
5. The next turn goes to whoever the arrow says. A join waits for every arrow coming in; two steps after one arrow start together.

Three ways, in the order Argus offers them. The first is the one to have.

With the Argus plugin installed in Claude Code or Codex, the agent has two tools (Gemini CLI gets the tools too, from the extension, but no hooks and no skills — so no Stop guard):

• team_task — its task, structured: the team, the goal, its role and duty, the round of the maximum, whether it is its turn, what the steps before it said last, the work it should read, and the last check (PASS/FAIL, how long).
• team_done {summary, status?, details?} — its report. A judge must give status (OK, REDO, DONE, BLOCKED); anyone may say BLOCKED. Refused, with the reason, when it is not its turn, when it already reported, or when a judge left the verdict out — so a mistake is said to the agent there and then, not discovered in the log an hour later.

The plugin also brings the argus-team skill — the protocol in one page, so the agent knows it without being told in every prompt — and the Stop guard: when an agent in a team tries to end its turn without having reported, the plugin's Stop hook refuses the stop and tells it to report first. It says so twice at most per turn, so an agent that cannot report is never held for ever. Outside a team the hook is the ordinary bell. (Measured on Claude Code and on Codex 0.160: both carry on with the reason as their next instruction.)

argus-say task                                   # the same as team_task, as JSON
argus-say turn "made the hash join 30% faster"   # the same as team_done
argus-say turn --status REDO "the benchmark is not the one asked for"
argus-say turn --status OK --file notes.md "keep it; next: the index"

It finds its session from tmux and Argus from the config (https too). Any agent that can run a command can use it.

With neither, the prompt shows the block to append to the log, as a heredoc so the shell runs nothing in it:

cat >> TEAM.argus.md <<'ARGUS_TURN'
@TURN who=EXECUTOR round=2
made the hash join 30% faster; tests pass
@END
ARGUS_TURN

The director reads @TURN … @END blocks too, so a team runs with any agent at all. A report made with the tools is written in exactly this form — the log reads the same whichever way it came.

A failed check is not worth a review: its FAIL arrow goes straight back to whoever wrote the code (in Split the work, to the planner, who divides the work again), with the failure in front of it. A Write team ends when both critics say DONE.

Four ways to the same graph — clicks on the picture, drawing with blocks and arrows, Mermaid, YAML — and the drawing and the text follow each other; use whichever is quicker.

Click a step and a panel opens under the picture: its name, its role, whether it judges, its duty in your words; for a check, the command and whose work it checks; its arrows (condition and target — change, remove, add); and + agent after, + agent in parallel, + check after, + join after, the team starts here, Remove this step (its arrows are wired around it).

Draw or write opens the team twice, side by side: the text on the left, the canvas on the right — and each writes the other as you go. Draw, and the Mermaid (or YAML) is rewritten; type, and the drawing follows.

• The palette over the canvas: Agent, Judge, Check, Join, Done. Drag one
  • onto a step: it comes after it (and takes over where that step led);
  • onto an arrow: it goes in between — a check dropped between two agents also sends a FAIL back to the first, a judge sends REDO back to whoever did the work;
  • into the empty space: a new step on its own, to connect. A tap on a block (or Enter) puts it after the step that is picked.
• Arrows: pull one from the ● on a step's right edge onto another step. It gets the condition that step can give next — a check PASS, then FAIL; a judge OK forward, REDO back, DONE to the end; anyone else always. Let go in the empty space and a new agent is made there, already connected.
• Click a step for what can be changed: its name, role, whether it judges, its own worktree, its duty; a check's command and whose work it checks; the team starts here. Click an arrow for when it goes — the conditions that step can give, as buttons.
• Delete removes what is picked (a step's arrows are joined up around it), Ctrl+Z undoes and Ctrl+Shift+Z redoes, every change.

The layout is drawn for you, left to right in the order things happen — the order of a flow is its meaning, and Mermaid keeps no positions, so there is nothing to arrange or tidy. A team wider than the canvas is shown smaller rather than scrolled. While the text does not read (you are in the middle of typing a line), the canvas waits, greyed, rather than draw over it.

The same canvas sits beside the text when a team.yaml (or a team .mmd) is opened from Files: drawing there keeps what a drawing cannot say — the goal, gate, rounds, permissions, reset.

Draw or write opens on the team as a Mermaid flowchart, with the graph drawn beside it as you type; every problem is underlined on its line (the editor, below) and Apply puts it in the picture once no error is left. GitHub, GitLab and most editors draw the same text, so a team can live in a README.

Step names (the ids): a lowercase letter, then lowercase letters, digits and -, at most 20 characters; in Mermaid Bench_A is accepted and becomes bench-a. -.->, ==> and --- are read as -->; style, classDef, class, linkStyle, subgraph, direction and click lines are ignored. A check's work is the agent pointing into it — when exactly one does; otherwise say it in YAML with of:. What a diagram cannot say — a step's own duty, its worktree, what it reads — is kept from the team being edited, step by step, so drawing never throws them away. The tab remembers which of Mermaid and YAML you used last.

Draw or write in Team, and any team.yaml opened from Files (the pencil), use the same editor. Argus checks the text while you type and shows every problem where it is:

• the word is underlined — red for an error, amber for a warning — and its line number is marked in the gutter (hover it for the message);
• under the text, the list: line, what is wrong, and a Fix button when the answer is obvious — fixr → change to fixer, judges: → rename to judge, gate: autp → change to auto, an if REDO from a step that does not judge → make it a judge, the same arrow twice → remove this line. A click on a row goes to its line;
• a line over the list: no problems and what the team is (2 agents, judged by review, starts at executor), or how many errors and warnings are left.

Completion comes from the same schema: keys at the top, in a step and in reset:; the values each takes (role: → planner, executor, reviewer…, gate: → ask, auto, goal, judge: → true); step names after - , after -> (with done), in of:, reads: and start:; after if, only the conditions that step can give (a check: PASS, FAIL; a judge: OK, REDO, DONE, BLOCKED). Values and names are offered at once, keys once you type a letter; Ctrl+Space asks anywhere. ↑ ↓ choose, Enter or Tab take, Escape closes.

The picture and the text point at each other: a click on a step puts the cursor on its line; the cursor in a step lights it in the picture. Enter keeps the indentation (one level more after key:, a new - in a list), Tab and Shift+Tab indent, Ctrl+/ comments lines out, Ctrl+S saves (in Team: applies).

A team.yaml in Files. Read, it shows a card over its text: Team file, whether it reads, the team drawn, and Open in Team, which opens Team on that folder with this team chosen. The pencil opens the editor with the team drawn beside it. Save with errors left asks once more — Save anyway keeps a half-written file; Argus will not start it until it reads.

Either way round. A team.yaml can be edited as a diagram: the YAML | Diagram (Mermaid) switch over the editor rewrites it as a flowchart, you draw, and Save writes YAML again — keeping what a flowchart cannot say (duties, worktrees, reads) and the keys around the graph (gate, rounds, permissions, reset), from the file as it was. The other way, a diagram you keep as a file (.mmd, .mermaid) is recognised as a team when it is meant as one — it names itself (%% name:) or has a check, a done, a judge or a result on an arrow; any other flowchart is left alone. Its preview gets a card, A team, drawn, and Save as team.yaml makes it the folder's team: if a team.yaml is already there, the button asks once more (Replace team.yaml) and the old file's duties and settings are kept. Then Open in Team.

An agent gets the same answers: team_check lists every problem with its line and its fix.

The other tab of Draw or write, and Save as YAML under More. The whole team, duties included; a team.yaml in the folder (or at the top of its repository) is offered as a card of its own whenever that folder is chosen:

name: Quick fix
goal: fix the crash on empty input
permissions: edit           # ask | edit | everything
steps:
  fixer: {role: executor, worktree: true, duty: "Find the cause before changing anything."}
  tests: {check: pytest -q, of: fixer}
flow:
  - fixer -> tests
  - tests -> done if PASS
  - tests -> fixer if FAIL

Checked while you type. A team file has a JSON Schema, team.schema.json (in the repository as docs/team.schema.json, and served by your own Argus at /team.schema.json). Every team.yaml Argus writes starts with the line that points an editor at it:

# yaml-language-server: $schema=https://andreaderuvo.github.io/argus/team.schema.json

With it, VS Code (the YAML extension by Red Hat), Neovim, JetBrains — anything speaking yaml-language-server — underlines a wrong key as you type (judges: → did you mean judge:), a value that is not allowed (gate: maybe), a step name with capitals, an arrow that is not one, a reset.files path outside the folder; it completes keys and shows what each one means. Add the line by hand to a file you wrote yourself.

The schema checks the shape. What only the whole team can tell — an arrow to a step that is not there, a step that would restart itself for ever, an arrow on a result its step never gives — is checked by Argus when it reads the file: the editor and an agent's team_check say both, each on its line. Argus checks the schema itself, so a machine without the jsonschema package gets the same.

Keys. Top level: name, goal, gate (ask, auto, goal), rounds (1–30), permissions (ask, edit, everything), start, steps, flow, reset (what "from clean" means). A step: role, judge, duty, worktree, reads; a check: check (its command) and of; a join: join: true. Flow: a -> b, a -> b, c (parallel), … if PASS, if OK, REDO… — fan-in is one line per arrow (a -> j, b -> j). Besides team.yaml, Argus reads team.yml and .argus/team.yaml.

Argus refuses a graph it cannot run — an arrow to a step that is not there, a step that would start itself for ever, a join nothing leads into, no start, more than 12 steps or 8 agents, a role name over 30 characters or a duty over 4,000 — and says what is wrong. And it warns (in the editor, and to an agent in team_check) of what it would run but you almost certainly did not mean: an arrow on a result its step never gives (if DONE from a step that does not judge, if OK from a check, if PASS from an agent), a key it does not read (judges: for judge:), a team that nothing ends.

You can ask an agent for the team itself, in words: "make me a team that speeds up the parser: someone who tries ideas, the benchmark as the check, a reviewer who keeps the faster one". With the Argus plugin it knows how, and it goes like this:

sequenceDiagram
  participant You
  participant A as the agent
  participant Argus
  You->>A: "make me a team that…"
  Note over A: writes it — Mermaid or YAML<br/>(the argus-team-author skill)
  A->>Argus: team_check(text)
  Argus-->>A: "line 4: 'maybe' is not a condition"
  A->>Argus: team_check(fixed text)
  Argus-->>A: OK — 2 agents, 1 check, judged by rev, starts at quant
  A->>Argus: team_propose(text, folder)
  Argus->>Argus: writes <folder>/team.yaml
  Argus-->>You: bell: "proposes a team: Faster parser — …"
  You->>Argus: tap → Team opens on that folder, the team chosen
  You->>Argus: look, change, Start

1. It writes the team in the same language you would — a Mermaid flowchart (with %% name: and %% goal: comments) or YAML. The plugin's argus-team-author skill teaches it: the shapes, the arrows, the roles, the rules Argus checks, and what makes a good team (let a command decide, one judge, worktrees for parallel executors, small).
2. It checks it with the tool team_check: OK with a one-line summary — agents, checks, who judges, where it starts — or the line that is wrong. It fixes and checks again. Nothing is started or written.
3. It proposes it with team_propose and the project's folder. Argus checks it once more, writes it as team.yaml in that folder — the first line says who proposed it — and rings you. Tap the bell: the sheet opens on that folder with the proposed team chosen, its goal filled in. Missed the bell? The proposal waits: a dashed line over the desk (claude-1 proposes a team: … — Open · Dismiss) and a card marked proposed first in Team, whatever folder the box holds — choosing it moves the folder to the proposal's. It stays until a team is started in that folder, you dismiss it (the file stays), or its file is gone or made yours.
4. You start it — or change it first, or ignore it. Or say to the agent "start it in the desk Trading": it requests it, and you get the question — the folder, the goal, which agent runs each step, what they may do — with Do it / No. On Do it the team starts and its windows land in that desk. An agent never starts a team on its own: a team writes files and runs a command, and that stays your decision. See What an agent can do.

A team.yaml you wrote yourself is never overwritten: the proposal is refused and the agent is told to ask you. One an agent proposed earlier is replaced (version 2). Delete the first line and the file is yours. From a shell, the same as tools: argus-say team-check team.mmd and argus-say team-propose team.mmd --in ~/work/parser.

• A role of your own: write a step's duty, then Save as a role of mine — the name, the duty and whether it judges are kept with your preferences, on every device. A duty can name the agent's own skills: "use your /security-review skill on the diff".
• A model of your own: Save as my model keeps the shape (not the sessions) as a card.
• Packs are roles and models in one JSON or YAML file, to share: Examples… lists those this copy ships (trading research, security review, paper review), Open a file… takes one — or a team written as YAML — from disk, Export mine writes yours, Remove a pack… takes back exactly what a pack brought. A model in a pack may carry a goal and permissions. Nothing in a pack is ever a default.
• Where a card comes from is on it: Argus, yours, the pack's name, or team.yaml. The ✕ on a card of yours forgets it; teams already started are not touched.

The team is a window of the desk, opened with it: its graph, large and live — a pulse while an agent works, amber when it has stopped — the round, the last check (PASS/FAIL and how long), Continue ▶, Pause ⏸ (the turn under way finishes; nothing new starts), Stop ■, Restart, Reset, Log, Goal (the goal, whole, to read again) (opened beside) and Story, newest first, filling the window under the graph and keeping your place as it grows. Over the desk a one-row line per team says the same, with Graph to bring the window back. When the team needs you, the line turns amber and the bell rings with the reason.

Stop asks whether to end the team's sessions too — its agents and its checks, with what runs in them. The log, the files and any worktree stay. Restart and Reset are the next section.

From an agent, or a script: team_task / teams (MCP), argus-say teams, GET /api/teams.

Four things you can do to a team, each with one meaning:

What "from clean" means is declared by the team, once, in its file — because only the team knows which of its files are a run's state (a ledger, positions, a journal, a cache) and which are its code and its data:

reset:
  files: [ledger.csv, JOURNAL.md, "state/*.json"]   # paths or globs, inside the team's folder
  run: python3 reset_paper.py                        # optional: a command, run in the folder afterwards
  log: archive                                       # TEAM.argus.md: archive (default) | keep | clear

• Nothing is touched before you press. Reset and Restart first show the exact list — the globs already resolved: state/*.json → state/a.json, state/b.json — the command, and what becomes of the log.
• Only inside the team's folder. Absolute paths and .. are refused when the file is read; a symlink pointing out of the folder is skipped; .git, team.yaml (team.yml, .argus/) and the log are never deleted by a glob. Only files: folders stay, emptied.
• The log is archived by default — TEAM.argus.20261007-153000.md beside the new one — so the story of every run is kept. keep leaves it growing; clear deletes it.
• run runs in the team's folder in a login shell, after the deletions, for at most ten minutes; its exit code goes in the team's story.
• No reset: — Reset deletes nothing and only archives the log. A team that does not declare it never loses a file by accident.
• Restart keeps the team: the same id and name, the same launchers and options, the same desk — the window watching it goes on watching it — and it reads the team file again when the team came from one (a team.yaml, a proposal), so it is how an edited team.yaml takes effect. A step the new file adds gets the launcher of the first agent. A team started from a template or a card of yours restarts with the same graph.
• Restart leaves a clean desk: the windows of sessions that have ended — an earlier run's, a shell you closed — leave the team's desk; the team's own stay, and fill again on their turn.
• From an agent: request team_reset or team_restart — put to you as Do it / No, with the list of files, unless you ticked it in Settings → Agents (then it runs at once).

A team's agents end their turns all the time, and that is the director's business, not yours: the next turn is given without you. So by default a team's agents ring nothing when they end a turn, and their waits do not count as waiting for you — no amber, no Got it, all for them. You hear from a team when it needs you (a round to approve with ask, a check failed twice, BLOCKED, a turn not reported) and when an agent is stuck on a permission, which rings as always. More → Ring me when each agent ends its turn brings the old way back for that team; for a team an agent starts, ring_turns: true in the request.

I changed team.yaml while the team runs. What happens? Nothing, to that team. Start takes a copy of the team — steps, arrows, roles, duties, the check's command, the rounds — and the director follows that copy to the end; it never reads the file again. The change shows the next time Team is opened on that folder, as its card. To make it count: Restart — it reads the file again (see Pause, Stop, Reset, Restart); or Stop, open Team on the folder, Start. A file the agents read by themselves (a RULES.md their duty names) is different: they see an edit at their next turn, if their duty says to read it every turn.

Why not let the agents talk to each other? Because then nobody decides. Here the graph decides who goes next, the check decides whether it works, the judge decides whether it is good — and every one of those decisions is in the log, signed.

Why a file at all, now that there are tools? It is the record you read, keep under git, and hand to the next agent. The tools are how a turn arrives; the log is where it stays.

Can a team run with the browser shut? Yes: the director is on the server. You find it where you left it, and the bell (and ntfy, if you set it up) tells you when it needs you.

Can I use a skill of my own in a team? Write it into the duty of a role: "use your /kraken-backtest skill". The agent uses its own skills; Argus only says when.

What may a team do? Only with the full token and --allow-write: it writes a log into the project, can make worktrees, and its check is a command line. An agent's key cannot start one by itself: it reads its task, reports its turn, checks and proposes a team — and requests a start, continue, pause or stop, which you approve with Do it (What an agent can do). Starting one also records the team's folder as trusted in Claude Code (~/.claude.json) and Codex (~/.codex/config.toml).

Where is it kept? Beside the config: teams.json (every team and its state), proposals.json (proposals not yet taken up, the last 20) and teams/<id>/ (each check's output, per round). The log of turns is TEAM.argus.md in the team's folder.

Can an agent write a team? Yes — see Asking an agent to design one. The language is small enough that it gets it right, and team_check tells it when it does not.

The API: GET /api/teams, GET /api/teams/suggest?path=&goal=, POST /api/teams, POST /api/teams/{id}/go|pause|stop|reset|restart, GET /api/teams/{id}/reset (the plan), DELETE /api/teams/{id}, POST /api/teams/yaml, POST /api/teams/mermaid, and for agents GET /api/teams/task, POST /api/teams/done, GET /api/teams/expecting, POST /api/teams/check, POST /api/teams/propose; packs: GET /api/teams/packs, POST /api/teams/pack; proposals: DELETE /api/teams/proposals?folder=; requests: GET /api/agent/actions, POST /api/agent/request, GET /api/agent/request/{id}. See The API.