Overseers (the hub that runs your agent fleets)

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 Overseers shortcut, 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.

What it is

The Overseer is a permanently-alive AI session that runs in the background alongside your agent fleet. It does three things:

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

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

3. 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 is in development and off by default. Enable it at Settings → Lab or by turning on overseerEnabled in config.json.

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 carry source = '__overseer__' (global) or source = '__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: in the session row, riding in the same small group as the auto-archive mark; and in the session panel header, where the Crown is the status mark — drawn in the same colour the plain status dot would have carried, and in place of that dot on a phone. The mark is decided from the record 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.

Where to find it

Where it lives

A single Overseers row under the Agent Tools group in the sidebar. It carries one number: how many sessions across all your Overseers are waiting on you.

The hub is in development, so the row appears only once the Overseer feature is turned on (Settings → Lab, or overseerEnabled). 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, a dot for its state, and a number only when something is waiting on you. 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, 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.

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 heartbeat settings. 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.

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.) Asking an Overseer to REWRITE its standing guidance is still desktop-only.

Typing to an Overseer works the same, except the message box grows as you type (capped, so the Send button can never end up under the on-screen keyboard).

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, or pick a starter chip; 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.
• 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.

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.

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.

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, above Pinned. If a project has none, the section is not there at all, on either surface.

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.

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.

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 count on the sidebar row and on each row of the hub's own list come from the same number, calculated in the backend and sent to the app as a number. They can never disagree with one another.

A project's own Overseers section is the one place that number does not appear: its rows carry no tally of their own, and its heading counts Overseers rather than things waiting on you.

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, giving it specific sessions to watch, and talking to it.
• Overseers part 3 — the work it hands out, what it notices on its own, its settings and the internals.
• 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.

Related

• 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