Overseers (the hub that runs your agent fleets)
November 20, 2026: the Classic Overseer is being retired. The Overseers hub now shows only the V3 Missions view (the Overseer V1 / V2 toggle is gone). The classic /overseer/* slot routes, the /crew/*, /crew/v3/* and /missions/docs/* routes and the classic startup jobs (keeper, judgment, routing-first, sweeps, digests) are removed. seat:hub still works: it lives in group/hub-seat.ts. The inbox agent runs as a mission and keeps GET /overseer/gate/held, POST /overseer/gate/act|release|dispose and GET /overseer/hub. What is done and what is still held is in the retirement strategy; the sections below that describe the Classic Overseer, its crews and their routes are history. The generation names are Overseer V1 (Classic Overseer and the crew workflow historically called V2), Overseer V2 (Mission System V3 / Mission Core), and Overseer V3 (Missions built from general agent tools). Historical filenames, API routes and stored identifiers keep their existing names. The system selector has two modes: V1 / V2 (classic, formerly Old) and V3 (missions, formerly New); it does not select V1 and V2 independently. New work uses Overseer V3. Start a mission hands an outcome to one ordinary session that carries the overseer prompt and leads the work with the same tools every agent has; the hub opens on its Missions view (see Missions). Overseer V1 (Classic Overseer) is an always-on coordinator that watches sessions, hands out work, and tells you when something needs you — and its swarms and crews are the groups of workers it runs. It keeps running until each of its parts is retired. This is the overview: what one is, what the hub looks like on desktop and on a phone, and how you create one. For builders and agents: how a mission is built is in the missions map, what it is for is in the overseer vision, and how the Classic parts retire is in the retirement strategy. Everything from the next section down describes the Classic Overseer and its crews unless it says Missions. Classic crews move into missions on their own, once. The first app start after the update moves every live classic crew into a mission: its lead becomes the mission overseer in place (a sub-crew lead becomes a nested lead, also when its parent crew already moved), members keep who they report to, deliverables and open tasks carry over, and finished crew tasks stay in the task history, read-only, with one summary record in each mission. A lead that a previous lead handed over to is moved too: the old lead is recorded as handed over. A moved crew keeps running as a crew, with its own lead and members on it, for good: a restart in between loses nobody, and the switch of the overseer system to V3 (missions) never ends it, because that lead row is what the lead seat, GET /crew/mine, its T-<n> refs and its members' check-ins resolve through; once switched it is never switched back by the app, and a moved crew cannot be re-registered as a crew again. One card, "Your N overseers now run as missions", lists the crews that moved and any that did not. A crew that cannot move stays a crew and the next start tries again; a crew whose lead session has ended is left as a crew. The crewMigrationAutoRun setting (on by default) turns the automatic move off; GET /overseers/crew-migration is the dry run and POST /overseers/crew-migration moves crews by hand. A move run by hand after the system already runs missions never ends the crews it moved. A moved crew is recognised by its own moved mark, and for crews moved before that mark existed, by their members' "moved to missions" record or by the mission that holds the migration's history record. A lead registering on a moved crew again is told it already works on the mission. A new session taking a moved crew's post (by crew id or by name, at any age) while the mission's lead has ended takes over that same mission through mission succession, never a second mission; while the mission's lead is live it is refused. A move that finds the crew's lead already in its mission reuses it. A moved crew that was reopened as a crew before that refusal existed, with a second live lead, is never moved again: the dry run reports it as fold-into-mission, and the move ends that leftover crew and folds its live lead into the existing mission, as a member under the mission's live lead, or as its successor when the mission's lead has ended; its live members follow, and a re-run reports nothing to move. The Master Sync keeper counts a live lead of the moved Master Sync mission as the post being held. Writing a new mission's documents waits out a busy database instead of failing. POST /group/end (install-wide token only) ends one named mission group the way the End mission button does, archiving that group's live members. While the overseer system is missions, no classic crew is ever started or reopened: registering a new crew, reopening an ended one, or splitting off a sub-crew is refused with a pointer to POST /overseers/adopt. A crew an earlier cut ended that the next start hands back to its mission's holder is stamped as moved in the same step, so the dry run lists it as already-moved and never as one to fold. Only a crew the migration itself ended is handed back: one its lead or the owner ended later stays ended. A crew whose mission was ended on purpose (End mission, or POST /group/end) counts as moved too: the dry run lists it as already-moved and no start tries to make it a new mission. On the Overseers hub (GET /overseer/hub) a moved crew shows once, as its mission: its crew entry is left out, so its lead never reads as a second overseer with another name. GET /seats still lists its seat:crew:<id>, the one address its post answers to.
On this page
Crew workflow: ordinary builders, a leader's inbox
Overseer V1's crew workflow (historically called V2) keeps the same crew interface, numbered sessions, message boards and task lists. Builders run like sessions you start yourself, with their normal project context, cards, skills and Dev Pipeline. Every readable final, including routine progress, plans, questions and results, goes promptly to the overseer or the crew member appointed as its leader. The leader answers or escalates. Human-only security permissions still require you.
From the Omniscio source checkout, inspect the workflow with:
overseer:v2 status
The historical V2 workflow is the sole crew workflow within Overseer V1. A previously saved on/off choice is ignored. Existing crew data is preserved, and agents receive current instructions on their next turn without interrupting active work. The status command works while the app is running or stopped.
The overseer playbook is to maintain tasks, start ordinary sessions, answer their cards and keep work moving. The legacy charter, score and prescribed wake ceremonies do not apply.
In Overseer V1's crew workflow, the overseer ends every message with one tag,
[[OMNISCIO_TAG: <category> | <type> | <replace or new>]], and Omniscio follows it without
screening the wording. The category is the topic in the overseer's words (up to 120
characters; capitals, spacing and a hyphen in place of a space are ignored, so red burn-down and
Red-Burn-Down are one topic while red burndown is another); Overall is its standing update card.
| Type | Where it goes |
|---|---|
routine |
Crew conversation only; no inbox card. |
acknowledgement |
Only confirms the overseer received your message or is carrying out what you said or approved — your yes passed on, the work started or promised, or what will be built and how it will be tested. Skipped from attention surfaces however much detail it carries; never changes a card. |
correction |
Fixes or takes back something the overseer told you earlier — a claim, a timing or an estimate. Crew conversation only: never an inbox item, never changes a card. |
update |
Only news that changes what you know or do next: a finished result, a failure, a risk, a finding or a cost. An inbox card in its category. |
decision-needed |
A card in its category, marked as asking you something. |
report |
A card titled with the overseer's name alone, always added as its own card. |
The archive test is that in one line: if you would read a message and just archive it — nothing in it changes what you know or do next — it is an acknowledgement, however much detail it carries.
replace refreshes the newest open card in the category (never a report) and withdraws that
lead's older cards in the category; new adds its own card there and withdraws the older ones
too, so you see one live card per lead and category however the overseer tags it. A report is
always its own card, never withdrawn by a card in its category and never withdrawing one. In the lead's
conversation, each message that raised or refreshed a card carries a Card chip at the end of its
tag row saying what became of that card: in your inbox (with not opened yet or opened 2h
ago), archived with a Bring it back button, replaced later when a newer message on the
same topic took the card over, or withdrawn by the lead when the lead (or the app, on archiving
the lead) put it away. The chip shows even with Tags on agent messages switched off, and never
on the inbox card itself. Nothing is pinned at the foot of the conversation any more. A card
that still holds questions you have not answered is never overwritten or withdrawn unless the
reply restates every one of those questions; otherwise the reply goes on
its own card, so the questions stay until answered or withdrawn — and the next reply refreshes that
card rather than adding another, so a topic shows one live card beside the cards still asking you
something. A card sent through the /owner-cards tool follows the same rule, and a successor
overseer's first update collapses any stack it inherited. A missing or malformed tag, or a retired
single-word label (STATUS, ACK, CARD, LATEST, REPORT), keeps the message private until
the overseer corrects it. Mute choices, security alerts and human-only permission clicks keep
their normal rules. A due report is asked for as Overall | report | new.
The label itself is machinery, never something you read: it is removed from the message wherever it would be drawn — the transcript, an inbox card, the crew board and the Overseers board. What you see instead is what the tag says, spelled out. At the bottom of an agent message and of its inbox card, up to three chips spell the tag out: Topic followed by the topic, Type followed by the type in plain words (update, decision needed, report, correction, routine, acknowledgement), and Mode followed by whether the message replaced the open card for that topic or opened a new one. All three wear the same style — one border, one background, one weight — so each chip is read by its label rather than by its colour. A message whose tag is missing, malformed or a retired label draws no chips at all, so raw markup never appears in a card.
Right-click the chips for their settings without leaving the message: a checkable Tags on agent messages item that turns the chips on or off immediately, and Tag settings, which opens Settings → Inbox at that row. Right-click is a desktop shortcut — on a phone the chips read the same and the settings page is the way to change them.
The chips are on by default. Tags on agent messages (Settings → Inbox) turns them off, and the message then reads exactly as it always did. Separately, a developer-version build can reveal the raw label for diagnosis with the Overseer tag debug switch (Lab, off by default), which draws the label a message carried, the type the app read from it, and any label that was rejected or later corrected — it shows only when a message has no readable tag to draw as chips. A card reads its tag from the newest overseer message published to it; a card or report the overseer published without a message (a direct card request, or a card carried to a successor) shows no chips, and an older card the app cannot tell apart from a pre-V2 update shows none either.
The implementation and retained recovery paths are in the Overseer V1 crew workflow map.
What it is
This is the whole Overseer system on one page: what an Overseer is and does, the swarms one can run, and the Overseers hub — the single place in the app you reach any of it from.
One way in, on purpose. The hub is the only entry point for the Overseer system: no other screen, dialog or wizard opens it, and the Overseer's own session home is never offered as a hub you can start a session in. Everything that mentions Overseers elsewhere — the per-project section in a project's sidebar, the
Open Overseersshortcut, an inbox card's button — is a LINK into this one hub. That is written down as invariant O71 in the Overseer contract and held by a test, because this feature was previously built three different ways and grew three separate doors. A swarm is described on its own page too: swarm.md.
A new install's Overseer waits quietly. Overseers are switched on for everyone, but none runs until you approve it, because each one is a real session that costs money. The default Overseer does not ask: no "waiting for your approval" card appears on a fresh install. Start it whenever you like with Turn it on in the hub. A per-project or custom Overseer you switch on yourself still tells you once that it is waiting for your approval.
What it is — The Overseer is a permanently-alive AI session
The Overseer is a permanently-alive AI session that runs in the background alongside your agent fleet. It does three things:
Answers agent questions. When another agent needs guidance, it asks the Overseer over HTTP instead of interrupting you. The Overseer replies in seconds. A question is a real turn on the Overseer's own session, one at a time: a question that arrives while it is mid-turn gets an honest "busy" answer and the agent simply asks again, so nothing is queued behind a stuck turn.
Screens your inbox. Before a new alert card reaches your inbox, the Overseer holds it for a brief window (default 10 minutes). During that window it batches related cards, silences redundant ones, merges duplicates, and escalates the few that genuinely need your attention. When in doubt it always lets the card through. It leaves Omni's and Mission Control's cards alone unless you turn on Let my Overseer screen Omni and Mission Control cards (off by default); turning an Overseer off lets every card it was holding through at once.
Watches the fleet for patterns. On each wake-up the global Overseer reads recent session activity and surfaces recurring failures, wasted effort, or opportunities to improve your setup — but only when the finding is actionable, never to report noise.
The Overseer feature is on by default, and turning it on starts nothing — an Overseer runs
only after you approve it on its one-time approval card. Until it is approved it holds nothing
back either, so your cards arrive straight away rather than waiting out a hold window for a judge
that is not running. To switch the feature off, use
Settings → Lab or turn off overseerEnabled in config.json. That one switch also covers swarms — they
are part of Overseers and have no switch of their own, so turning Overseers off stops every swarm
until you turn it back on (your swarms are kept).
Internal names vs. user-facing names. The Overseer is simply called "the Overseer" everywhere — there is no rename split like the concierge/Chief-of-Staff pair. The sentinel project is
__overseer__, sessions carrysource = '__overseer__'(global) orsource = '__overseer__:<projectUUID>'(per-project), and these strings persist in the DB.
A session can be NAMED like an Overseer without being one. Only a real Overseer carries those source strings — every other session has an ordinary source, and nothing stops one being called "Verdict Road Overseer #13". So the app marks the real thing with a Crown that IS its status mark — on every session row (sidebar, phone list, inbox) and in the session panel header the round status dot is drawn as a crown in the same colour the dot would have carried and at the dot's own 8 px size, so it still says how the Overseer is doing and never shifts the row it sits on. The crown has two looks, and the surface picks it: it is SOLID everywhere a session is listed, and HOLLOW in the Overseers list (the sidebar section and its phone twin) — the same crown outline, with a see-through middle, so the list of Overseers reads as the roster it is. A resting Overseer whose crew is at work wears the green running crown: between check-ins a lead parks as a routine update, which is grey for every other session, but while at least one crew member is running or starting the lead's crown, its phone row and its header rail read Running. With no crew member working it goes back to grey. Its inbox cards show the crown in place of the robot on the sender line, and a needs-you card the Overseer itself placed wears the mini solid crown too — in the card's own colour — so the person can see whose card it is at a glance. Such a card still carries its dismiss button: the crown marks who raised it, it does not take the card away from you. A crew's Overseer (its lead, which spawns with an ordinary source) is recognised from the fleet roster, and outside the Overseers list it goes by "<Crew> Overseer" ("Help Desk Overseer") instead of its stored title "[Help Desk] Overseer #2"; inside the list it keeps just the crew name. The mark is decided from the record or the roster and never the name, so renaming a session "overseer" can never earn it one. Measured on the author's box the morning this shipped: 254 sessions were named like an overseer and only 135 ever were one, five of them running at once.
A team can wear its own glyph instead of the crown. The mark is still the Overseer's status mark — the same 8 px, the same position, the same colour that says how the Overseer is doing — but a team that has claimed a glyph shows that glyph inside it. The Help Desk teams wear a headset, and a team whose name opens with "Help Desk" gets it with nothing to configure. Any other team gets one when the person asks for it: the choice is stored per Overseer in
overseerTeamIcons, keyed by the same id the sidebar orders Overseers by, so it covers a configured slot, a registered crew and a live mission alike. Every row that already drew a crown draws the team's glyph instead — sidebar, phone list and the crew dashboard's lead avatar — and an explicit choice always beats the name rule. A Help Desk ticket wears the headset whatever crew is holding it, because the ticket itself is the link to that team. With no glyph claimed, nothing changes: the row keeps the crown exactly as before.
Where to find it
V3 missions: the view the Overseers door opens on
The Overseers door now opens on a plain list of your missions. A mission is one outcome you hand to one overseer: an ordinary session that carries the overseer prompt, leads the work through workers, and comes back to you only with a decision, a problem or real news.
- Start a mission. Press Start a mission, write the outcome you want in one or two sentences, give it a short name if you like, and pick the project. The app starts the overseer with your outcome as its first message, writes that outcome, in your words, as the first version of the mission's vision document (you approve every later change to it), keeps it alive through a full memory, and puts its reviews on a clock.
- How a mission and its overseers are named. The name you give a mission is the mission's own
name, and a long one is shortened to 60 characters at a word so it stays readable in the list. Each
overseer session is titled
[name] Overseer #N, so the sidebar tells you which mission it belongs to and which overseer it is: the first is #1, and when an overseer is replaced its successor takes the next number. That title is the app's to write — the automatic titler never overwrites it. - Delegate part of a mission. An existing direct report of an overseer-rooted group can adopt a
bounded outcome through the shared
/overseers/adopttool. The call comes from the session being promoted and remains subject to the existing session-start authority and owner-approval gate. It changes no owner permission setting; nested starts use the existing overseer authority and the group's bounded capacity rules. The promoted session stays in the same group beneath its current lead; its children, tasks and the root mission's shared documents stay where they are. The app gives it an explicit document scope seeded by the delegated outcome and schedules its own direction reviews and stay-alive responsibility. It remains one mission in the list. Nested leaders report through the live group tree to their immediate lead, who decides what reaches the owner. Normal owner approval rules still apply. - Overseer runs on. One more row under Project decides which engine and model the new overseer starts on. Whatever you pick is saved for every new mission, including ones an agent starts for you without naming an engine; Project default follows the project's own engine and is what a mission uses until you choose something. Each pick is saved as you make it: choose only an engine and missions use that engine's default model; choose a model as well and missions use exactly that one. Choosing Project default clears the saved choice. From this screen it is the same choice every time: to run one mission on a different engine, change it here, start the mission, then change it back. An agent starting a mission for you can name an engine for that one mission, which wins for it and leaves your saved choice alone. If the saved engine cannot run — its model belongs to a different engine or is no longer offered, or that engine is not switched on — no mission starts and the message names the saved engine and sends you back to this row. While only an engine is saved, the closed row shows the program that runs it (for example "Claude Code · Default"); open the row to see the engine itself.
- Waiting for your signature. When a crew has a stage it cannot prove for itself (a ticket board's "Tickets written" or "Ready for you to merge", say), it waits for you to sign it. Every such stage, from every running crew, is listed at the top of the Missions view with the crew's name and the reason it cannot be proven. Press Sign as unprovable on it, the same button as on the crew's Dashboard (V1 / V2 view → the crew → Dashboard tab), and it leaves the list. The list is hidden while nothing waits.
- The list. Active missions come first, each with its name, its outcome and a dot for whether its overseer is working. Ended missions sit folded under Ended. The list keeps itself up to date: a mission you start, or one that ends, shows up without reopening Overseers.
- Your mission's overseer in the sidebar. A running mission's overseer is also listed in its project's Overseers section, named after the mission, with the crown on its session row — so you find it where the other overseers are instead of hunting the session list. Replace overseer swaps the new one into the same place, and the row leaves the list when the mission ends — or as soon as its overseer session is gone, whether you stopped it, it crashed, or it was archived. The mission itself does not disappear: it moves under Ended on the Overseer V3 screen, where you can open it and end it properly. Message that session and it comes back to life, and its row returns with it.
- A mission page. Open a mission and its page shows a short header — its name and outcome,
whether the overseer is working, how many things need you (or All clear) and End
mission — over five tabs, each using the whole page:
- Overview — what needs you (open questions, and proposed document changes, with Review). A question that offers choices is answered right on the card: tap an option (the overseer's recommended one is marked) or write your own under Custom answer, then Send — the overseer gets the same reply as when you answer the card in your inbox, and the card leaves your inbox too. A question with no choices to pick has Answer in chat. The rest of Overview is the standing update, each deliverable with a progress bar and its tasks, the team, the latest scheduled review (and when the next is due) and staying alive with Replace overseer. An open page follows a replacement automatically, including a handover triggered by a full memory, so its chat addresses the current overseer.
- Chat — the conversation with the overseer, filling the page. Switching tabs keeps your draft.
- Team — everyone on the mission as a tree (the root, nested subleaders, ordinary workers and unknown roles). Pick someone to see their role, state and who they report to, with Open session; a ready nested overseer also shows its own documents and review there.
- Docs & reviews — the mission's documents, decisions, lessons and every past review, with a reader beside the list.
- Activity — every card the overseer sent you, including the ones kept out of your inbox, the open tasks and the deliverables with their tasks. The page remembers which tab you last used on each mission until the app restarts. On a narrow window or a phone the tab bar scrolls sideways and the columns stack. End mission asks once, then stops every session on the mission.
- Nested scope. A ready nested subleader remains part of the existing mission roster and may open its own document and review read. That scope is separate from the root's shared documents; inherited parent documents are read context. A missing binding or handover in progress is shown as incomplete or held until repaired. Ordinary nested reports go to the immediate lead, who decides what reaches the owner.
- The lead writes a sub-lead's vision and approves its plan. A lead promotes one of its own reports and writes that report's vision itself. The sub-lead then proposes its strategy, and its lead approves or declines it, so you get no card for a sub-lead's plan. If that lead is gone, the next live lead up decides; only when no lead above is left does the card come to you. A top-level mission's vision and strategy still come to you.
- A sub-lead sees the big picture and its team, not the whole tree. Its instructions always hold the same few parts, however deep the mission goes: the whole mission's vision, its lead's goal, its own vision and up to five teammates with what each is working on now. Leads in between appear by name only, so a mission can grow into many layers without any one session drowning in context. The team list is refreshed every time the sub-lead wakes on its schedule.
- The same look as a crew. A mission's sessions get the crew header bar and menu, the view switcher and the dashboard, the crown follows the overseer, and the sidebar count is the real number of sessions working on it.
- Docs, from any mission session. The crew header bar on every session in a mission has a Docs drop-down (Ctrl+Alt+0). It lists Vision, Strategy, Rules and the Latest review with its colour verdict; pick one and its full text opens in the session panel. A document the overseer has not written yet is greyed out as "Not written yet", and while a review is still running the menu says so instead of opening an empty report. All documents & reviews opens the full Docs page: every document, the newest 50 decisions and 50 lessons, and the newest 30 direction reviews, newest first, each opening to its full text or report. When a list holds more than it shows, it says "Newest 30 of 41". Reviews from before an overseer was replaced stay on the list. On a phone the list comes first and an item opens with a back control; on a narrow header the Docs button shrinks to its icon. While the Docs page is open the View menu shows Docs, and picking any other view leaves it. On the Dash, the Documents rows and the Reviews card's Read it and every past review link open the same page at that item. Inside the Vault's notes editor, Ctrl+Alt+0 keeps meaning "Normal text".
- The older view is still there: Overseer V1 / V2 at the top of the list opens the hub described below, and Overseer V3 missions takes you back. Whichever you picked last is remembered on this device, so the Overseers hub reopens on it after you navigate away or restart the app.
Overseer generations: V1 / V2 and V3
One switch picks which overseer system runs: Overseer system in the Overseers settings, set to V1 / V2 or V3. It starts on V1 / V2.
- V1 / V2 runs crews, Classic Overseers and Mission Core exactly as before. Missions still get every new piece below, whichever way the switch is set.
- V3 stands the V1 / V2 crew, Classic Overseer and Mission Core machinery down. Crew sessions keep running as ordinary sessions and their finished turns come straight to you. A crew's overseer that is still running keeps sending you its cards until that crew is retired, so switching never silences it. Flip back to V1 / V2 and it all comes back.
- Which cards interrupt you now lives in Settings → Sessions → Agent cards that interrupt you, because it applies to every agent's cards, an overseer's included. A mission's cards below your level still wait on its mission page. See Owner cards.
- Most workers per lead. A lead can have at most this many working sessions under it (five unless you change it). Starting or moving one more under a full lead is refused with the reason.
- Workers reach their lead through the app. A worker writes to its lead by role, and the app delivers it to whoever leads it now, so replacing an overseer loses nothing. Workers can still message any other session.
- Only you can change these settings; an agent that wants one changed asks you with a card.
Where it lives
A single Overseers row under the Agent Tools group in the sidebar. It carries no waiting-on-you number: a session an Overseer runs already counts in the project hub it lives in, so counting it here too would show the same thing twice. With Show only active hubs on, waiting sessions no longer keep this row in view — their own project hub carries that signal.
The row appears whenever the Overseer feature is on (it is by default; Settings → Lab, or
overseerEnabled, switches it off). While it is off you will see no Overseers row — and no
stray "Overseer" project row either. Swarms have no row of their own: turning the swarm feature on
adds them to this hub.
Two columns
The list, on the left. One row per Overseer — its name, its state line, and a dot: green while it has a live session, grey otherwise. No row shows a waiting-on-you number. A swarm is nested under the Overseer that owns it, marked with its own symbol; which Overseer owns a swarm follows from the project the swarm runs in. The list header has two controls: New (the +) and the gear for Fleet settings. Each row has a three-dot overflow menu (hover-revealed on desktop, always visible on touch) with Rename, Pop out, Switch off/on, and Delete (custom Overseers only — global and project slots can only be switched off). Double-clicking a row enters inline rename directly. A crew row's menu is shorter: Pop out, and Switch off while its lead is running, which asks first and then stops the crew's lead and the helpers working with it (the same as Stop crew on a crew session's right-click menu). A crew has no Switch on and no Rename here.
Pop out opens that one Overseer in its own window, so you can park it on a second monitor. It is the same kind of window every other panel pops out into — same title bar, same remembered size and position, and it reopens after a restart too — opened on the Overseer you chose. Each Overseer gets its own window, so popping out a second one does not steal the first one's; picking Pop out again for a window that is already open brings that window forward instead of opening a duplicate. The window shows the whole hub, list and all, so you can move between Overseers in it; if you delete the Overseer a window was opened on, that window closes itself rather than coming back on every launch. The item is not offered inside a popped-out window, which already is one. See pop-out-project-window.md.
Crews in the list. An agent crew — a team of sessions that registered themselves under a lead (see agent-crews.md) — is listed here too, with a people icon and its live count. Selecting one opens the crew's own pane: its lead's chat with you, its roster, its board and its Settings tab, where two cadences live. Heartbeat is how often the lead wakes; Status update is the ceiling on how often it may ask you for a report — every 1, 2, 4 (the default) or 8 hours, or Off. A report is asked for only when the crew's own record MOVED since the lead last reported: a task landed done, a deliverable moved, a review or an audit finished, or you are owed an answer. When nothing moved the ask is skipped and you hear nothing — aliveness lives on the overseer's status line, not in a report. A crew whose lead sits under another crew's lead reports on a doubled interval. When a report is owed it comes in one fixed shape: Done since last update, In progress, Blocked or needs you, Next. It may post that as its standing update or as its update message, and it may skip with a one-line "already told you" instead of filling the form. Your quiet hours hold those reports until the window ends rather than delivering them overnight. Inside that pane members read by role and number — "Overseer #1", "Fixer #7" — without the "[Crew] " badge their session titles carry, because the pane already names the crew (display only: the titles themselves are unchanged). The crew row of a crew session's Crew details menu (its role button) opens the hub straight onto that crew.
The pane, on the right. Whatever you selected: an Overseer, a swarm, the wizard, or the fleet
settings. The hub opens on the first Overseer; the sidebar row brings you back to the last one you
were on. Esc and the breadcrumb each step back one level.
How it behaves
An Overseer: four tabs
The pane header shows its name and a one-line status — awake or not, when it last woke, its cadence, and what it has spent today — plus Start a swarm….
| Tab | What it shows |
|---|---|
| Chat | your conversation with it, on its real session, drawn exactly like the session's own chat (the same bubbles, "N actions" headers and Plain Speak cards) — and it comes to rest the same way too: a reply taller than the window opens on its top, not at the end of the thread. Just us shows only what you two said to each other — the app's own briefings to it (wake-ups, inbox screening, agent questions) are not your messages and never appear there, and the Overseer can tag one of its own replies as a routine status update to keep that out too. Everything it does shows its whole transcript, tags and machinery included — minus the heartbeat wake-up itself, which is the app's own clock and never drawn as a message in either view (the row still exists, and the session's own "show system messages" toggle reveals it). A round that found nothing worth reporting stays out of the chat by itself, and the Overseer can end any routine round with [[OMNISCIO_HEARTBEAT_QUIET]] to keep that one out too — a round that found something is always shown. The choice stays while you look at other tabs; a freshly opened hub starts on Just us. Anything it proposes that costs money (a swarm to start, pause or delete) sits at the top as a card with Approve / Decline. |
| Sessions | the sessions it watches, as the normal session rows: Waiting on you first, then live ones, then its swarms under a Swarms heading (one row each, which opens the swarm), with idle ones behind Show N inactive sessions. Click a session and you are in the ordinary session view; the Overseers row brings you back. |
| Board | what has happened around it, newest first: what it did (and why), what agents asked it and what it answered, its swarms' boards, the shared agent board, and DMs among its sessions — including one still held on a busy recipient's queue. Filter by channel; post to its channel from the bottom. "I wanted this" on a row that kept something from you brings the alert back. |
| Settings | grouped under four headings. About: its name and purpose (the purpose auto-titles it until you name it) and its job description. What it watches: the sessions it watches, its wake-up cadence and its wake-ups. What it may do: the agent types it may run, how often it may interrupt you, and the jobs it runs on its own. Running: the switch that runs or stops it. While anything is unsaved, a bar pinned to the bottom says Unsaved changes beside Save; it goes away once the save lands. A custom Overseer can also be deleted here. |
Choosing the view it opens on. Right-click any of those tabs — the keyboard's menu key on a focused tab does the same — for a small menu. Set as default makes that tab the one every Overseer opens on from then on, with a short confirmation ("Sessions is now the default view"); Reset to default goes back to Chat, and a crew back to its Dashboard. A crew has Dashboard as a fifth tab and the same menu on its strip, so Dashboard can be the default too. The choice is remembered on this computer and survives a restart, and it only governs a fresh open: coming back to the Overseer you were just on still returns you to the tab you left. A slot Overseer never opens on Dashboard, which only crews have. The same menu is on a phone's strip only where the device sends a right-click; on a phone the default is best set from the computer.
When an Overseer is restarted
This is the Classic Overseer. A mission overseer hands over through staying alive instead: a fresh session takes over from its hand-over note, its brief and your messages, as the staying-alive page describes.
An Overseer restarts itself on a schedule: a fresh session takes over the job and the old one ends. The old session is then history. Its check-ins are switched off, so it is never woken again, and it cannot set a new wake-up for itself. If you answer an inbox card the old session raised, your answer goes to the current Overseer instead — your words unchanged, with a note telling it which old card you were answering — and the old session stays ended. Only one Overseer per slot ever runs, and you only pay for one.
The new session opens on a briefing the app writes from the live record, not from the old session's memory: who it is (addressed as the incoming seat, never as its predecessor), its hand-off note, the mission and its founding brief, the crew's memory with each section's newest rules, decisions, lessons and the current picture kept whole, the live team and who is stuck, the tasks already closed (marked dropped for the walls it must not re-run and done for what landed), your own recent words, and the recent conversation. The whole briefing fits a fixed budget (about 48,000 characters), the overseer skill is never pasted into it, and anything left out is named with how to fetch it. A message another agent sent the post and the old session never answered is carried across whole, as that agent's message, so it lands on the new session's unanswered list instead of dying with the conversation. Before this (2026-10-16, the Git Efficiency crew) a successor inherited a 178,000-character briefing with the skill pasted in, its memory cut mid-rule, finished work listed as "tried and failed", and the wrong seat number in its first line.
If the old session left you a card you have not opened yet, it is not filed away until you read it (or put it away): its last words stay in your inbox rather than being cleared with the session that raised them. Until then the old session's row sits in your Interrupted list — it is ended, not gone — and it leaves on its own once you have dealt with the card.
A question it asked you survives the restart too. While the Overseer's own question card is
still unanswered, the app does not start it fresh — the fresh start waits, however big the
conversation has grown, because the card is the only record of what it asked. When a restart has
to happen anyway (the daily restart, once the wait for an answer has run out), the question card
moves onto the new session instead of being put away with the old one: the question stays in your
inbox exactly as it was, and answering it reaches the Overseer that now holds the job. The switch
is overseerQuestionSurvivesRestartEnabled, on by default; turned off, a restart puts the
unanswered question away with the session that asked it, as it used to.
A question that no longer applies can be taken down by the post itself. A job outlives the session on it, so the Overseer that holds it now may put away a card an earlier session of the same job raised — the case where a question about handing the job to a fresh copy was still sitting in the inbox after the handover had already happened. Two different jobs never reach each other's cards, and a session with no job of its own still may not touch them.
A restart never cuts you off mid-sentence. If you are typing in the Overseer's own chat when a restart comes due — or your composer still holds an unsent draft — the app waits. It re-checks every half-minute and goes ahead once you have sent the message or paused for two minutes, so a restart is delayed rather than lost. This covers the daily restart, the size fresh start and the automatic tidy-ups that file a replaced session away; a size or card-based fresh start waits as long as it needs to, and the daily restart waits within the same eight-hour grace it already gives an unanswered question, so a slot is never left without a fresh session forever. Filing a replaced session away is what clears its draft, so waiting is the difference between your half-written answer surviving and being deleted with the session that held it.
A crash is not a restart. When an Overseer's Claude process dies mid-reply, the app's automatic recovery brings the same session back — usually within a minute — and the Overseer carries on with its conversation, its promises and your queued replies intact. Nothing starts a replacement while that recovery is still owed or its restart is on the way. A fresh session takes over only once recovery has genuinely given up (after its two automatic attempts, or when you have switched automatic recovery off), and that fresh session starts from its notes, not from the old conversation. Before this (2026-10-29) every crash started a brand-new Overseer straight away, which then filed the recovered one away: the Dev Ops slot was replaced eight times in one day, each time losing what the old session was in the middle of. A swarm's lead gets the same patience: when its process crashes, the swarm waits for the recovery to bring that lead back, with its plan and its queue of work, and starts a new lead only once recovery has given up.
A swarm: its own screen
Click a swarm in the list and the pane becomes the swarm's screen with six tabs: Overview (goal, owner, live workers against the cap, today's spend, pause / resume / stop), Workers, Chat (with the lead's session), Board, Queue (the work items waiting for a worker) and Settings (an About card for its name and goal, a Limits card for its worker cap and daily budget, and the same Save bar as an Overseer's Settings). The breadcrumb reads Overseers / <its Overseer>, and up goes back to that Overseer.
On a phone
The pane fills the screen, and the list moves into a sheet: the pane header's first row (the Overseer's name and status, with a ▾) is the switcher, and tapping it slides up an Overseers sheet listing every Overseer with its swarms indented under it. New (+) and Fleet settings sit on the sheet's own title row, beside "Overseers". The rest differs from the desktop layout because a 390px-wide screen has no width and no height to spare:
- The "Overseers / <name>" breadcrumb row is not drawn while you are looking at an Overseer — the sidebar header and the pane header already name both halves of it. It comes BACK the moment there is somewhere to go up TO: inside a swarm, the fleet settings, or the wizard. And there it names only the immediate parent ("Night watch /"), not the whole path, so the title of what you are actually looking at keeps the room.
- Buttons that would crowd a name become icons — Start a swarm on an Overseer, Pause and Stop on a swarm. Each keeps its full name for a screen reader and its tooltip, and Stop still asks before it does anything.
- The Chat tab's Just us / Everything it does choice is a filter button in the header row, shown on the Chat tab only, instead of a bar over the first message. On the Chat tab the status line's tail ("$4.21 today") gives way to it; the other tabs show the line in full.
- The Board's channels are one dropdown beside New group chat, instead of chips that wrapped onto two or three rows before the first post.
- A swarm's status line leaves out "run by …" — "Running · 3 of 4 workers" — because the breadcrumb right above it already names the Overseer.
- Number settings put the box under its description (Fleet settings, and the other settings screens built on the same row), so a long description can never squeeze the box.
- Every row and control clears 44px, the standard touch-target minimum.
Swarms work fully from a phone: see them on the hub, open one, read its board, create one from the wizard, retune it, pause it and stop it. (Before 2026-09-12 the wizard let you fill in all four steps and then refused on Review with "This action is only available in the desktop app" — that is fixed.)
The hub's own data is fetched only while the hub is on screen. Opening it reads the fleet once and then keeps it current while you stay there; closing it stops the traffic, so the hub no longer re-downloads the fleet on every count change in the background — on a phone that was tens of megabytes an hour for a screen nobody was looking at. The one thing that stays warm is the short list that marks which sessions belong to an Overseer, so an Overseer's own session stays out of your inbox with the hub closed. Asking an Overseer to REWRITE its standing guidance is still desktop-only.
Typing to an Overseer works the same, in the same box: the hub's Chat and Board tabs, a crew's Chat tab and a swarm's lead chat all use the app's one shared chat box — attach files, dictate, quick replies, the ⚡ bolt, big pastes collapsed into chips and Send Later on the ▾ — with your own Enter-to-send setting. Files and pasted blocks reach the Overseer with your words, and a pasted image shows on your message the moment it is sent, just as in regular chat. What you have typed and not sent is kept when you switch tabs or leave, separately for Chat and Board. When a Board filter or a missing session means you cannot post, the box says why instead.
New: the wizard
New opens a fork: An Overseer (keeps watch) or A swarm (gets one thing done).
- Overseer — four steps. Purpose (say what it is for in your own words, or pick one of five starter chips — Inbox screener, Fleet watcher, Release captain, Night watch and Dev ops overseer; a short name is derived until you type one) → Scope (everything, one project, or just these sessions) → Rhythm (how often it wakes, how often it may interrupt you, which agent types it may run) → Review. Start watching creates it and switches it on — that is the approval to spend. Save without starting keeps it configured but off.
- Its job sits under the purpose on that first step: the description the Overseer actually runs with, and the same field its Settings tab edits afterwards. Blank means the standard job. A starter chip fills it in — and you can read and change it before you save, so nothing is installed without you seeing it. Dev ops overseer is the only chip that also sets a rhythm: every 15 minutes, and a shorter list of agent types (builder, fixer and reviewer). Its job description is a template — the parts in square brackets are blanks for you to answer for your own machine, and the wizard will not let you past that step until you have answered them or cleared the box. The other four chips change nothing but the purpose and the name. Changing your mind between chips is safe: the chip you leave takes its own job description, cadence and agent types back out with it, so you never end up with an "Inbox screener" running a dev-ops job. Anything you have edited yourself is left exactly as you left it.
- Swarm — four steps. Goal → Where (the project; the note says which Overseer will run it) → Limits (workers at once, daily budget) → Review. Start the swarm spends budget the moment it is pressed. Not sure how big it should be? Ask the Overseer to size it instead sends the goal to that Overseer as a question and lands you on its Chat. The daily budget is optional: clear the box and the swarm runs with no spending limit (the field then reads "No limit", the same as the fleet-wide Shared daily ceiling). The Review step says so in words — "with no daily spending limit" instead of "at most $X a day" — so you always know which one you are about to start. An uncapped swarm still stops for everything else: the worker cap, the shared ceiling if you set one, the app-wide daily cap, a run of failed workers, and Pause. You can also clear or restore the budget later on the swarm's own Settings tab.
The wizard opens straight on the Overseer path from Prompt Tools ("Set up an Overseer for this
project") and from the empty state when you have no Overseers yet. Everything it creates goes
through the same writer as POST /overseer/slots and the swarm routes — and since the edit and
delete doors landed (PATCH and DELETE /overseer/slots/:slotId), the same is true of the two
Settings-tab buttons that used to be app-only. Every operation on an Overseer is now reachable
from an agent, each behind the approval card the operation deserves.
Starting an Overseer from an existing session
If an ordinary session has been doing Overseer work, use Use an existing session as a template in the hub's New Overseer wizard. This creates a real native Overseer; it does not relabel or modify the old session.
The template copies only editable basics—its name, a bounded purpose, and its project scope. It does not read or import the conversation, notes, files, hidden instructions, or other session content. Review the purpose, scope, sessions, rhythm, allowed agent types, interrupt budget, and cost before starting it.
Omniscio then performs the handoff in a safe order:
- It creates and starts the native slot through the normal approval and keeper path, without moving any watched sessions.
- The hub shows Starting until that exact slot has a canonical live session. A keeper failure changes the state to Needs attention; Running means the native session is live.
- Only after Running does it move the sessions you reviewed. Each move succeeds only if that session still has the same owner it had during review, so a concurrent reassignment always wins.
- Conflicts are reported and left untouched; successful moves are kept.
A startup failure or abandoned wizard leaves assignments unchanged. The old session is never messaged, stopped, archived, deleted, or rewritten automatically. Keep it as history until the replacement has completed whatever real operating proof you require, then archive it separately.
Custom Overseers still govern only sessions explicitly assigned to them. A specialist-sounding name does not grant project-wide or fleet-wide authority.
A mission lead taking an existing session
A mission’s lead can take a session that already exists — one running now, or one waiting in your
inbox — and put it on its mission. The lead calls POST /group/adopt {"session":"<the session>"};
the session keeps its transcript, its own workers and its tags, and from that moment its finished
work comes back to the lead and it appears in the mission tree.
The call starts nothing by itself, so an idle session stays idle until the lead messages it. The
answer carries a brief — the session’s “your place” block — and the lead opens its first message
with it so the session knows who it now reports to.
What is refused: a session already reporting to someone else (move it with POST /group/move
instead), a session that leads its own group or mission, the app’s own tool sessions, an always-on
Overseer slot, an ended group, and a lead already at the owner’s report limit. Only a lead — an
Overseer session or a mission root — can adopt, and only into its own tree; the machine-wide key
can adopt anywhere but must name the lead.
Adoption carries archive authority: as with any linked child, a lead can archive the session it took.
Per-project
A project's own Overseer is an ordinary session in that project. It runs in the project's own folder and appears in the project's session list beside your other sessions, wearing the same Overseer mark — so it is supervising the real repository rather than a throwaway copy of it, and you can find it where you would look for any other session in that project. It is never worktree isolated, because a supervisor that owns several workers cannot live in a copy of the tree.
Because it runs in the project folder, it automatically loads that project's CLAUDE.md and
.claude/rules/, and can open its .claude/memory/ docs and contracts — the same context any
session in that project gets. This is what makes a per-project Overseer able to understand and
enforce the project's own processes, conventions, and contracts.
The two exceptions are the global Overseer and any custom one: neither belongs to a project, so both keep the app's own data directory as their home and receive none of a project's rules or contracts.
Each project's sidebar carries its own small Overseers section, directly under Needs You, listing the Overseers that touch that project. Its heading names the section and how many Overseers there are — "OVERSEERS (2)", the same shape as Pinned and Interrupted beside it — and the heading counts the rows you can actually see. The phone carries the same section in the same place — open a project and it sits under Needs You, below Pinned. If a project has none, the section is not there at all, on either surface.
A custom Overseer chooses where it shows up: under one project, or across All projects, where it appears in every project's section at once. That choice only decides where it is listed. It never routes sessions, it never takes a project's own Overseer's place, and several custom Overseers may share the same project.
The section lists only Overseers that are actually on. One that is switched off drops out, and so does a crew once its overseer is archived. Archiving the lead takes the crew off the list, usually within a minute. A crew that has no overseer at all is also left out. Two things stay the same: the hub still lists the crew, and any Overseer still holding something for you keeps its row until you deal with it.
A row in that section is the Overseer's own session, so clicking it takes you straight to that
session rather than by way of the hub. An Overseer with no session to open yet — one that is
switched off but still holding something for you — keeps its row, and that row opens the hub
scoped to that project: the same hub, showing that project's Overseers rather than the whole
fleet, with the project named in its heading ("Overseers / <project>"). Every other way into the
hub — its sidebar row, the Open Overseers shortcut, an inbox card — opens the whole fleet, and
leaving the hub clears the scope.
Putting the section in your own order. Drag a row up or down and it stays where you drop it; on a phone, hold a row for a moment and then drag it, so a tap, a scroll and the swipe between sessions all still behave normally. That order is yours and it is used everywhere the Overseers are listed — the project's section, the same section on your phone, and the hub's own list, which keeps its one fixed rule that Overseers that are running come before the ones that are saved but stopped. Dragging in one project only moves the rows that project's section shows, so an Overseer listed elsewhere keeps its place, and an Overseer you have never placed waits at the end of the list rather than shuffling what you set.
Groups (folders). Select a few Overseers, right-click, and choose New group from
selection… to gather them under a named folder. A group header shows a plain grey folder, the
name and how many Overseers it holds; click it to fold or unfold. Right-click Overseers for
Move to group or Remove from group, and right-click a group header for Rename… or
Ungroup. Groups sit wherever you drag them among the other Overseers, and dropping a row onto
the middle of a group header puts it in that group. A folded group still tells you when something
inside needs you — its header shows the amber needs-you dot. Grouping only changes where an
Overseer is drawn: ungrouping (or emptying) a folder never stops, archives or deletes an Overseer,
and an emptied group disappears by itself. The same groups, members and folded state show on your
phone (tap a header to fold it there; making and renaming groups is a desktop job) and survive a
restart. The hub's own list does not show groups. Groups are stored in the overseerGroups
setting, so they can also be changed with PATCH /settings/overseerGroups.
Selecting several at once. <kbd>Ctrl</kbd>+click adds or removes one Overseer from the selection and <kbd>Shift</kbd>+click selects the range between two clicks — exactly as on any other session row, and a range can run from a Live row into the Overseers. Right-click any selected Overseer and the menu acts on all of them (pin, snooze, pause, stop, restart, archive, tags, plus the group commands). Dragging one of several selected Overseers moves them all together, keeping their order.
The section sits exactly where it is drawn, so walking the sidebar with <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> (or <kbd>J</kbd> / <kbd>K</kbd>) steps onto these rows between Needs You and Pinned, in the order you arranged — the cursor follows the list you are looking at rather than jumping to wherever those sessions would otherwise have sorted. It skips anything you cannot see: the Overseers inside a folded group, and the whole section while it is folded.
Fleet settings
The gear opens the knobs that apply to every Overseer at once: how they behave (inbox screening, the hold window, the wake-up cadence, the restart interval, the runaway-spending breaker), the shared daily ceiling (one budget for the Overseer and every swarm it runs; no limit until you set one), the swarm defaults (workers at once, daily budget per swarm, worker time limit, failures before pausing), and which projects get their own Overseer — a searchable list of your real projects with a switch each, plus the blanket "an Overseer for every project".
The waiting-on-you number
The Overseers hub shows no waiting-on-you number at all — not on its sidebar row, not on any row of its list. A session an Overseer runs that needs you is counted where it lives: its project's hub.
The backend still works out, per Overseer, how many of its sessions wait on you, and sends it to the app as a number. A project's own Overseers section uses it to sort by needs you, to filter to waiting Overseers, and to light the amber dot on a collapsed group; the phone receives the same numbers. That section's heading counts Overseers rather than things waiting on you, and the number in brackets after each row's name is how many live sessions that Overseer owns (archived and interrupted ones are left out), the same sessions its expand arrow shows.
Because the backend cannot see a few things the app knows about (a session mid-retry, one in its notification grace period, or a badge you have already read), the count can occasionally sit one higher than what you would tally by eye. That is expected and is documented as invariant O40 in the Overseer contract.
Related
- Overseers part 2 — keeping one alive: waking up, copying one, and giving it specific sessions to watch.
- Overseers part 3 — the work it hands out, what it notices on its own, its settings and the internals.
- Overseers part 4 — talking to it: asking it a question, and telling it an alert should have reached you.
- overseer-worker-titles.md — how a worker session an Overseer starts is named.
- agent-crews.md — mission teams of agents that register under a lead and are listed in this hub.
- concurrent-multi-session-orchestration.md — the capability underneath all of this: many sessions at once, each its own process, with the dashboard and attention-first inbox that keep a large fleet manageable.
Related — simple-mode.md
- simple-mode.md — the concierge / Chief of Staff (a different always-alive session aimed at non-technical users; separate code path and workdir)
- agent-driven-sessions.md — how external AIs drive Omniscio sessions
- ai-spend-alerts.md — the user-facing spend alert system the Overseer's breaker integrates with
Last verified 2026-11-20