The Leader and the Workers

Three actors

User

You. The Leader's panel is in the middle; type what you want and the Leader starts. You can type on any Worker's panel too, and the Leader hears it the same moment. Rules about what the instance may do are yours, settled in your words on a permission popup.

Leader

One session, always there. It takes your words, hires Workers by name, briefs them, takes their questions and reports, decides what reaches you, stops and restarts them, files a finished desk away and parks the room when you say the day is over. When it is not running, the panel shows its history, and the next thing addressed to it — a line you type, a Worker's message, a server event — starts it on its desk.

Worker

A named session on a desk of its own, with one task. It keeps its desk written as the work moves, reports to the Leader with a message, and says with done when the task has shipped; ending its session is the Leader's and the server's, never its own. A Worker's panel lives with its process; hired again on the same desk it is back with its rows.

The day of a Leader

You open the page and type on the Leader's panel: what you want, in any words. The first time the server starts on a version, the Leader's panel opens with ovai's introduction: one screen on what ovai is, what it does not do, where Claude Code's own commands go and how to ask about the tool. The Leader is handed the same text, and ovai's guide, a skill with a page per topic it reads to answer how something is done here, in your own words. The Leader answers in plain language, and when the work is somebody's, it hires. Called with no name, the roster names the Worker: a fixed list of thirty first names, and the next one is the least recently used free one — never used first, then the one whose holder left longest ago. A new name gets a desk opened from the template, and the rules that make that directory the Worker's to write in. A name is for somebody who has a desk — somebody who stopped — started again on it, panel kept.

Then the Leader briefs: a message to the Worker, which comes back the moment the Worker has it, and the Leader's turn goes on. What the Worker says back arrives later, as a message the other way, and the Leader decides what of it reaches you. What cannot wait for the Worker's turn to end goes urgent, reaches it at its next tool call, and reads To Paul (urgent) on the Leader's panel. While the Leader's turn runs, one line reads what it is at — thinking, or the call it has out. It floats in the lower right corner of the last message and takes no room, so nothing moves when it comes or goes, and it disappears while the pointer is over it, so the corner it covers can be read.

What waits for you is in the Leader's status, one row right above the Leader's box. The Leader keeps it in STATUS.md on its desk, apart from its desk file, and calls confirm_status at the end of every turn that brought it anything; the row shows the file as it stood at that call, stamped with the call's time, and beside the stamp whether anything has reached the Leader since: up to date, checking, or how many new. It holds two kinds of bullet and nothing else: what only you can do, starting with a bold Waiting for you:, and the loose ends, started and stopped or found and not closed, that nobody is on. A result the Leader has reported is a Waiting for you: bullet until you close its topic. Work that is moving, progress and housekeeping stay out of it, and a bullet goes the moment it no longer waits or is no longer loose. It is one short bulleted list, the waits first, in the same order from one confirmation to the next, and a ticket or a page is a link with a short label. A click on the time asks the Leader to check it, and a click on a bullet quotes it in your reply, as a line of its own that your row draws as a quote, so the Leader reads the bullet as you saw it. The row appears after the Leader's first confirmation, and a switch on the Leader's head hides it.

Each thing you ask for is a topic, open from the ask until you close it: you say it is done, accept it, use the result or drop it. The Leader's report closes nothing, and neither does a Worker's done. The Leader's desk holds what is true now, one entry per open topic; when a topic closes, what is worth knowing again goes into knowledge/ and its entry leaves the desk.

What the Leader says to you is for you: a turn with nothing in it for you is answered with <noop/> and the panel shows nothing for it, and a Worker's checkpoint stays between the Leader and the Worker. A message says what happened; the status says only what waits. When you ask where things stand, the Leader says it in words in that reply, then brings its status up to date and confirms it, and whatever it asks you to choose from is in the message that asks, never in a list written earlier. A text a session writes before a call is held while the turn runs: when the turn ends it is shown, as ordinary rows, only if nothing else the turn wrote was, and never when the turn ends in <noop/>. The first text after a line of yours or an urgent message came in during the turn shows at once. An answer is words in the reply, written once, as the turn's last text after its calls, never before them and never only thinking or the desk. When the Leader reads what you typed and ends its turn with no words, the server tells it at once with an unanswered event, and it answers. Inline code is kept for a name, a path or a short command; quoted or proposed text is a blockquote, and longer code a fenced block.

Through the day the server tells the Leader what it needs to know and nothing more: that you typed on a Worker's panel, and what; that one Worker said something to another; that a Worker has been silent for 10 minutes, and again at 50; that a Worker's permission popup timed out, after 10 minutes or 2 for a subagent's call; how much of its context a Worker has used, at the warning size and at the size to restart it at; that a Worker says it is done; that every running Worker has sat idle for a minute with nothing waiting for it, once, usually a report it has not acted on; that a Worker has gone, and why — stopped or restarted by the Leader, idle, a spent window — with its desk as it was last written; that the service refused a Worker's turn, in the service's own words; that a spent window has reset; that admin mode ran — within seconds while the server runs, else at its next start — when it ended, and which of the instance's configuration files changed — by name, and nothing of what is in them. Told, not asked: nothing waits on the Leader for any of it.

The rules the instance holds are settled through the Leader, in your words. Say "you will be autonomous, push without asking" or "pip install is too much, ask me every time", and the Leader answers in plain language first, then calls permission once per rule — a permission popup on its panel with Allow, Deny and Ask every time, which also moves a rule already held. A Worker hired to push is hired after the push is allowed. To take a rule out, the Leader calls remove_rule: a popup with the rule, where it stands and who asked for it, and Remove and Keep. Permissions has the whole of it.

A stopped Worker that nothing open names — no topic on the Leader's desk, no bullet in its status — is retired, once knowledge/ holds what its desk knew: desks/<Name>/ is moved whole — the desk, the conversation, the persona — under archive/, the seat leaves the room and the page, and the name is the roster's again. Filed, never deleted. One that may be wanted back on the same desk is stopped with stop_worker, not retired. And when you say this is it for the day, in any words, the Leader parks the room: every Worker is closed, writes its desk and goes.

What a Worker does

One task at a time. A Worker is started on its desk with a persona rendered at that moment, reads its desk first, and works from there: what the work produces — a design, a finding, notes — is kept on its desk, beside the desk file, and every file it names is named by its whole path from the instance directory, where every session runs. It writes the desk with a tool at every point the work moves, not only at the end, because a written desk is what survives and anything worked out and not written is gone with the session. Its files stay inside the instance: /tmp is outside it, so a file tool's read or write there is no rule's to allow — the classifier's to judge in auto mode, a permission popup for you in Manual.

A Worker reaches the Leader with message, and only that way: what it says on its own panel lands there and nowhere else. Five tools go to every seat and one is the Worker's own, done; the ten that are the Leader's — confirm_status, stop_session, restart_session, stop_worker, restart_worker, park, hire, retire, permission, remove_rule — refuse a Worker in words, so a Worker that wants a rule proposes it to the Leader. When the task ships the Worker reports, writes its desk and calls done, with a one-line note if it likes; the Leader gives it the next thing or stops it. The desk stays, and hire on its name brings it back on the same desk if it is wanted again.

A Worker whose turn the service refuses — a model this Claude Code does not have, a sign-in missing, the service down — is ended at once when it was its very first turn, and the Leader is told what the service said. One that has worked before keeps running, since the failure may pass, and the Leader is told once.

Talking

Between sessions there is one way to talk: message, to a named seat. It is refused when the other seat has no process; a seat held by the quota gate has it and reads it when the window resets. A message between the Leader and a Worker is one line on the Leader's panel and a full row on the Worker's; a message from one Worker to another reaches both, and lands on the Leader's panel too as Paul → Jane: … — heard, not asked. A switch on the Leader's head hides these lines from its panel when you would rather read the Leader alone. A message whose markdown opens with a table, a list or a code block folds behind one line; a double click opens it.

When you type on a Worker's panel, the words are that Worker's own <user> turn — your authority, for a typed "go" — and the server tells the Leader the same moment: one line on the Leader's panel, Ana → Paul: …, and an event to its process. The Leader hears what you typed as you typed it, with the whole row of every reference you put in it, and the Worker does not have to pass it on.

Every one of these arrives in a frame the server set — <user>, <message from="Max">, <server-event> — so a session always knows who is speaking, and nothing inside a message can pose as somebody else.

Desks and handover

A desk is a person, and each seat is told its desk and desk file as whole paths, the instance directory joined. The desk file is edited in place, like any other file; its header line is written with write_desk — a title, one line, what the seat is on; a status, one line, where it stands — and calling it is what says the desk is current. It is how the User and the Leader see what everybody is on without opening every panel.

The Leader is told how big it has grown, and decides for itself what to do about it. Past 200,000 tokens in a request the server sends it a context event carrying the size it passed and the size it wraps up at, and tells it again every 20,000 above that — once per size, never twice for the same one. Nothing is ended for it: it carries on, keeps its desk current, and plans its restart for a moment that suits the work. Past 300,000 the same event says to wrap up now: write the desk, call restart_session, say "back in a moment", and there is nobody to tell. A successor starts on the same desk, in the same panel, with whatever was queued for it carried over. It is turned by a restarted event, reads the desk, goes on from what that says to do next, and announces the restart to nobody — the desk is the whole of what carried over, and the restart is in the log. Both restart_session and stop_session refuse until the desk was written after the event that asked, so the desk comes first, always.

A Worker is not told its size. The Leader is, naming the Worker, at 200,000 and at 300,000 only, and past 300,000 restarts it with restart_worker at a moment that suits the work — between two steps, or after the report it owes. The Worker is told its session is closing, writes its desk, and goes when that turn is over; its successor starts on the same desk the same way.

Models per seat

The instance was installed with a model for the Leader and one for the Workers. A Worker that should not run on the usual one is hired with a model beside its name, kept as written in desks/<Name>/MODEL — its own file rather than a line of the desk, because the desk file is written by its session, and a model kept in there would be a model that session could raise for itself. It goes away with the desk. Leaving the model out writes nothing down, so changing the installed model moves everybody who was never named one, from their next process. A model given at hire on a desk a Worker had before runs it on that model and is kept for the desk from then on; without one, the desk's own stands. ovai configuration lists every desk with what it resolves to. A model may name the effort it runs at, opus/high: the effort goes to Claude Code as --effort, and with none written Claude Code picks its own. A new instance runs its Leader on opus and its Workers on sonnet.

Idle and quota, from the team's side

A Worker that has been silent is reported to the Leader at 10 and at 50 minutes. At 55 the server closes it: it writes its desk and goes, and a desk not written within 5 minutes of the turn that read the close is taken as it was last written. The Leader is told either way. A seat on a turn — waiting on a permission popup included — is never idle.

When a usage window nears its limit every running seat is told: a Worker carries on; the Leader tells you which window and when it resets, stops the Workers whose work can wait, writes its desk and stays. No Worker is hired until the reset. When the window is spent, a Worker on it is interrupted and closed — do not resume, write your desk. At the reset the Leader is told, and started if it was stopped, and brings the Workers back with hire on their desks. The quota gate has the stages and the thresholds.