---
title: Overseers (the hub that runs your agent fleets)
---

# Overseers — every Overseer and its swarms in one place

## 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](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 session row marks the real thing: a **Shield**
> icon, riding in the same small group as the auto-archive mark, on any session
> whose own record says it is an Overseer. 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**. Nothing else: no
tags, no counts, no explanations.

**Crews in the list.** An agent crew — a team of sessions that registered themselves under a lead
(see [agent-crews.md](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.

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](overseers-part-2.md) — keeping one alive: waking up, copying one, giving it specific sessions to watch, and talking to it.
- [Overseers part 3](overseers-part-3.md) — the work it hands out, what it notices on its own, its settings and the internals.
- [overseer-worker-titles.md](overseer-worker-titles.md) — how a worker session an Overseer starts is named.
- [agent-crews.md](agent-crews.md) — mission teams of agents that register under a lead and are listed in this hub.

### 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](agent-driven-sessions.md) — how external AIs drive Omniscio sessions
- [ai-spend-alerts.md](ai-spend-alerts.md) — the user-facing spend alert system the Overseer's
  breaker integrates with