Four levels and one board: who does the work, who directs it, who remembers, and where you come in. Written for the person who will never open a terminal, and for the one who will.
One coding agent is a hire. Five of them on the same repo is a company, and a company needs the things a company needs: somebody who splits the goal into jobs, somebody who keeps people off each other's toes, a way for a question to reach whoever can answer it, and a way for finished pieces to be folded back into one whole. Orchestration is that layer. Not the coding, the running of the coding.
Qai Guard took the names from an opera house because the shape is the same. The house is your repo. A performance is a goal. The impresario runs the house across seasons: books the productions, knows the building, never leaves. A maestro conducts one performance and does not play a note. The orchestra plays, each musician on their own part. A section may have its own principal who leads a few players. And the owner, who signs the cheques, decides what needs their say and gets called for nothing else.
Underneath, the hooks do the part no metaphor covers: every edit is checked against the board before it lands, so two musicians never play the same line at once, and a change that would collide with an unmerged branch is refused before it becomes a merge conflict. The levels above the hooks decide who plays what. The hooks make sure they can.
Top to bottom: who answers to whom. Each level is one tap on the board.
You do not need every level. One agent on one runner is the smallest unit and it works alone. A maestro is for a goal with several parts. The Impresario is for a repo you come back to.
Each one told twice: what it is in the house, and what it is on the board.
You say what the season is for. You decide which decisions are yours: which tools an agent may run without asking, when a finished piece may be merged, how much a day may cost. Everything else happens without you, and the things that are yours arrive on your phone with the answer already drafted, so most of them are one tap.
You can also step onto the podium yourself and conduct from a terminal, or walk into the pit and be one of the players. The board does not mind who is human.
A Qai account key on the live board makes you an actor: every message, pause, answer, approval and merge is signed with your name. On the public key the page is a window.
Bash(npm test*), Read, Edit(src/**)) decide which tool calls go through without you. Anything else is an approval on Now, with the Impresario's advice attached.controllers in guard.json names who may pause, start and talk to the agents of a clone.Every maestro and every player is a contractor: they arrive with no memory of the building and leave when the performance ends. The Impresario is the one who has worked here longest. It keeps the house notes (which checks flake, which files are landmines, what you always say no to) and briefs every newcomer with them.
When a player asks a question, it drafts the answer before your phone buzzes. When a performance ends, it reads the work and writes a verdict: ready to merge, needs your eyes, should be redone. When you say "fix the flaky billing test", it writes the brief, picks a stage and, if you let it, starts the show. When two productions want the same room, it holds the younger one. When the day's money is spent, it pauses everyone with a note.
It never deletes anything, and it never decides an approval: your rules do that, it only advises.
One server-side agent per repo, turned on from the Impresario view with a Qai company key (or QAI_IMPRESARIO_API_KEY on the API). It thinks on a qai model (qai-max by default) and wakes on events: a question, a permission request, a finished job, a footprint change, the clock.
suggestion with a confidence; in routine or run it answers itself when sure.review from its diff, checks and report; in routine or run a merge verdict with passing checks is merged for you.POST /impresario/draft turns a sentence into a brief, a runner and a role; run mode starts it.heldBy) until the older merges.brief, and it rewrites them as runs teach it.Hired for one performance. The maestro reads the goal, looks at the score (the repo), and splits it into parts: this player takes the nav, that one the billing tests, each with a brief and the files it may touch. It hears a report each time a player finishes a passage, sends them back when a check fails, answers their questions, and stops anyone who drifts. It never plays an instrument itself.
When the performance is over it hands you one report naming every branch, and it leaves. Nothing it learned survives, which is why the Impresario exists.
Pick "a conductor with a team" on a runner's start form, or POST /jobs with role: "conductor", a goal, a team budget, a worker cap, a model and an effort. It runs in its own worktree like any job, with the guard's MCP tools:
spawn_worker with a brief, areas (path patterns), a model from runner.models and a budget share that comes out of the team's.wait_for_reports, then send_to_worker with follow-ups or /compact, /model, /effort; stop_worker for the ones that drift.merge team into <branch> folds every worker branch with commits into the maestro's; stopping the maestro stops the team.node .qai/qai-guard.js mcp --install gives your own terminal session the same tools.Approvals never go to the maestro; they stay with people, unless you started the team with permissions bypassed.
The players. Each one has its own copy of the repo and its own branch, so nobody edits over anybody. Before every edit it claims the exact lines it is about to touch; if another player holds them, or another branch has already changed them and not merged, the edit is refused and it is told who, where and what to do instead. It asks when it must, up the ladder, and gets on with it when it can.
A player hired by a maestro is a worker: same musician, with a brief, a set of files to stay inside, and a share of the budget. A player you start yourself, or a Claude Code session in your terminal with the hooks installed, is a session: it answers to you.
A job on a runner: Claude Code, Codex or Cursor run headless in a git worktree on its own branch, reporting every turn to the board. Or a terminal session with the hooks, which joins the same board from the person's own machine.
runner.checks run after every turn that changed files; the results ride on the card and in the worker's report.merge into <target> and a pull request on every job with commits.parentJobId, areas and a budget share; files it changes outside its areas are flagged in the report.Sometimes one part is itself a small orchestra: the strings need a principal who splits the passage among a few players. A worker may hire its own helpers, if the maestro allowed it when it set the depth. They play on their own branches, report to the worker who hired them, and their work folds into that worker's branch before it folds into the maestro's.
Two levels down is the default and it is usually enough. Deeper than that and nobody can hear the whole piece.
A worker calls the same spawn_worker the maestro did. The team's maxDepth (default 2, at most 3) says how far down it may go: the maestro is depth 0, its workers 1, their workers 2. A spawn past the cap is refused with too-deep, and one that would overrun the budget is refused too.
merge into <parent> on the card), then upward.The building. A computer with the repo and an agent CLI on it, turned into a stage with one command. Maestros and players run there, each in its own room (a worktree), and the runner is the one who actually runs the checks, captures the diffs, merges branches when asked and does the Impresario's chores at the end of the day. A laptop under a desk is a fine runner. So is a box in the office that never sleeps.
node .qai/qai-guard.js runner in any clone. It announces itself with its adapters (claude, codex, cursor) and its slots, and polls the board for jobs, actions and chores.
.qai/state/runner/<jobId> on its own branch.runner.checks in guard.json are the commands that decide whether work is done.Three journeys, one ladder.
The short version of the rules the board enforces.
| You | Impresario | Maestro | Agent | Sub-agent | |
|---|---|---|---|---|---|
| Set the goal | yes | drafts it from your sentence; starts it in run mode | receives it | receives a brief | receives a brief |
| Split the goal | by starting agents yourself | one brief and a runner per request | yes, its whole job | its own part, when depth allows | no |
| Edit code | in your own terminal, as one of the players | never | never | yes, on its own branch | yes, on its own branch |
| Approve a tool call | yes | only through your allow rules; the model advises | never | asks | asks |
| Answer a question | yes | suggests; answers itself in routine or run when sure | answers its workers first | asks the maestro or the board | asks its parent |
| Merge | yes, one tap | in routine or run, when checks vouch | merge team into its branch, when asked | asks | asks |
| Spend | sets every budget | a daily budget; pauses everyone at the line | a team budget and a worker cap | its share of the team's | a share of its parent's |
| Remember | yes | the house notes, across every run | nothing after the run | nothing after the session | nothing |
| Delete | yes | never | only what its workers do in their worktrees | in its own worktree | in its own worktree |
No. The hooks alone, in one terminal, are the product most people start with: your own Claude Code session refuses to edit lines another session holds. A runner and a session started from the board come next. A maestro is for a goal with several independent parts. The Impresario is for a repo you keep coming back to, where the same questions would otherwise be asked every week.
Same thing, two vocabularies. The board and the API use the plain words: a job with role: "conductor", workers with a parentJobId. When we talk about the house we say maestro, because the impresario books maestros and that is the picture. Read conductor wherever you see maestro on this page.
Two things, at two levels. At edit time the hooks refuse the second edit into lines the first one holds, or into lines a branch has changed and not merged, and tell the agent who, where and what to do instead. At the job level, when two jobs in different trees have both changed the same files, the Impresario holds the younger one (pauses it with a note) until the older one merges, then lets it go. A merge that still conflicts is reported, not forced.
Both. node .qai/qai-guard.js mcp --install gives a terminal session the conducting tools (spawn_worker, wait_for_reports and the rest), so you conduct from your own Claude Code with the workers on a runner. And any terminal with the hooks installed is a player on the same board, claiming lines and answering to you.
You, always. The Impresario proposes; the allow rules you wrote decide tool calls, never its opinion; the dial says how much it may do without asking; it never deletes anything; and every time you overrule it, it writes down why. "Run the place" is the most rope it can have, and it is still your rope.
Install the hooks in a repo, open the live board, and add the levels as the goals grow.