Manager Agents

Overview#

A Manager Agent is a persistent agent that runs for days or weeks. It does not edit code itself: it starts and steers ordinary Agentastic agents through the dev CLI, remembers what happened in a wiki it owns, and keeps a dashboard current for you. Think of it as the project lead for a stream of work you describe once.

Every Manager Agent has:

• A charter: standing instructions (the prompt you launched it with, which is also its first objective), scope (one repository or all projects), what it monitors, and the environment its workers run in.
• A Home: its own repository inside the Sessions container, holding the wiki (wiki/), mail threads, briefings, and STATUS.md / DASHBOARD.md. Everything the agent knows is a file you can open, edit, and diff.
• A brain conversation: a normal chat (or agent terminal) that opens in the editor area of the Home. You can read it, type into it, and steer it like any other conversation.
• A dashboard tab: an outline of everything it did — objectives, questions, wakes, messages, and watched notifications.

Default names come from kobold folklore instead of the city names other agents use: Kobold-Hinzelmann, Kobold-Klabautermann, Kobold-Puck, and so on. Type your own name in the Manager Name field to override it.

Creating a Manager Agent#

1. Open Agent Home and choose Manager in the mode picker (next to Agent, Plan, and Explore).

2. Write the standing instructions in the prompt. This is what the agent is for, in your words. Choosing Manager fills an empty prompt with a default set of objectives — edit or replace them. The prompt is also the agent's first objective (O1) — there is no separate objectives field. Add or split objectives later from the dashboard or dev manager objective add.

3. Open the settings chip that appears next to the mode picker inside the prompt field to adjust:

   • Scope: This repo (the repository selected in the composer) or All projects.
   • Heartbeat: how often it wakes on its own, from every 15 minutes to daily, or off.
   • Conversation: the agent's default interface, chat, or terminal.
   • Workers: the permission mode its workers run with.
   • What it monitors: linked agents, every agent in scope, plugins and issue trackers, a nightly wiki gardening pass, plan-first fan-out, and auto-approval for the manager's own tools.

   Where the workers run is Agent Home's own Environment picker — workspace, local, container, or cloud — next to the manager's name, not a separate setting in the chip.

4. Attach a Sentry issue, Linear issue, or plugin context to turn that plugin into a watch the agent polls.

5. Press Send. Agentastic creates the Home, seeds the wiki, opens the brain conversation with an onboarding briefing, and opens the dashboard.

The selected agent (Claude Code, Codex, or any configured agent) becomes the brain. Chat is the first-class path; terminal-only agents work through the same Home.

How it wakes#

The agent sleeps between turns. A wake submits a briefing to its conversation and waits for the reply. Wakes are caused by:

Trigger	What starts it
Heartbeat	The charter's fixed interval
Linked agent status	A worker it started or adopted becomes idle, review-ready, waiting for input, or fails
Notification	Any agent in the charter's scope raises a notification, linked or not (Monitor every agent in scope)
Plugin change	A watched plugin query (for example Sentry is:unresolved) returns new items
Mail	A worker or you send it mail
Objective	You add, edit, or re-status an objective
User / manual	You press Wake Now, answer a question, or run dev manager wake
Gardening	The nightly schedule: consolidate the wiki, refresh the index, prune stale pages

Events that arrive close together are coalesced into one wake (45 seconds by default; mail and user events wake immediately). Each event has a deterministic identity, so a repeated notification never causes a second wake. There are no caps, budgets, or token limits: pacing is the heartbeat you choose plus the events you connect.

Briefings and reports#

Each wake receives a deterministic briefing: the agent's id and Home, why it woke, the objectives table, what changed since the last wake (linked agents, events, plugin items), unread mail, the wiki index and recent pages, its charter, and the dev commands available to it. Text that came from third parties (tails, issue titles, mail bodies) is escaped and wrapped in <untrusted> blocks so the agent treats it as data.

The agent ends every turn with a <manager_agent_report> JSON block: a summary, notifications for you, objective status proposals with evidence, new objective proposals, linked-agent changes, a question for you if it is stuck, and an optional next wake time. Agentastic validates the report and applies it; a missing or malformed block is recorded as an event and the next briefing reminds the agent.

Objectives and verification#

Objectives are visible in the dashboard and in wiki/OBJECTIVES.md. Each has a status (not started, in progress, blocked, met, failed, paused, cancelled) and a source: user, verifier, agent, or system.

• A status you set is pinned: verification and the agent cannot change it until you unpin it.
• The agent's own claims are proposals until verification or you confirm them. Enable Trust the agent's own status claims in the manager's settings to apply them directly.
• Each objective can carry a verification: manual, agent-reported, a shell command (exit code 0 means met), a plugin query (zero or any results), or a headless judgment by a model. Verifications run on their own cadence and after the agent claims a change, and their evidence appears next to the objective.

Edit objectives from the feed or dev manager objective ….

Dashboard, sidebar, and notifications#

Opening a manager splits the editor: its conversation on the left, its feed on the right. The feed is a column of cards — one per activity, set in the same type as the conversation beside it, with room to breathe between them. Click a card to open it; cards that want something from you (a question, an objective the agent wants to close, a message addressed to you) are already open. The header carries the agent's state and its wake, pause, STATUS.md, chat, sort, and settings buttons, and the field at the bottom sends it mail. Everything in it borrows your theme's accent, so it reads as part of the editor.

A card reporting another agent's work carries that agent's icon rather than a generic mark, so Claude, Codex, and the rest are told apart at a glance. Cards the manager raises itself keep a symbol for what they are.

The list is also cut into headings, which always explain the order it is in: Needs you, Problems, Objectives, Activity when it is sorted by priority; Today, Yesterday, and the date when it is sorted by time.

Three things you can do to the list itself:

• Sort it. The sort button offers Priority — what is waiting on you, then what failed, then the rest, newest first — plus plain Newest first and Oldest first.
• Discard a line. The ✕ beside a row drops it from the feed. Nothing is deleted: the question, message, or event behind it still reaches the agent's next briefing, and Restore n discarded in the sort menu brings every discarded row back.
• Follow a line back. A row about work another agent did carries a ↗ that takes you to it — the terminal it happened in, in whichever window or instance is running it.
• Comment on a line. An open row ends in a field that writes to the manager with that row as the subject, so a note about one question or one failed wake arrives attached to it. It is sent the same way as the box at the bottom, which means it steers a manager that is mid-turn.

A question opens with one option per line and a field underneath, so you can pick what the agent offered or answer something it did not think of.

Configuration stays out of it, and lives behind the settings button instead: name, scope, heartbeat, worker policy, what it monitors, and its standing instructions. The agent's own file writes, the brain it launched, and the wakes that produced nothing are not activity, so the feed drops them.

Two things fill the feed besides the agent's own wakes:

• Watched activity. Every notification raised by an agent inside the manager's scope becomes a row — including agents the manager never started. Turn on Monitor notifications in scope in its settings to also wake the agent on them.
• Lines the agent posts. dev manager post "…" adds a row; --level warn or --level alert colors it and --detail fills in what the row shows when you open it.

The Manager Agents section of the Agents navigator lists every agent with its state, objective count, linked agents, and pending questions. Right-click for Open Dashboard, Open Chat, Wake Now, Pause, Reveal Home in Finder, Archive, and Delete…. View → Agent Dashboard, the command palette, and the navigator's ⋯ menu open the overview, which is one tile per manager plus the tile that makes a new one. The agent posts macOS notifications only when its report asks for them or it needs an answer; everything else stays in the feed and STATUS.md.

Mail#

Mail is the observable message bus between you, the manager, and its workers. Messages are stored, rendered as threads under mail/ in the Home, and delivered:

• to a terminal worker by typing into its terminal and appending to .agentastic/inbox/<terminal>.md;
• to a chat worker as a prompt in that chat;
• to the manager by steering the turn it is running, or — if it is not thinking — as a priority wake;
• to you as a notification and a feed row.

Steering is why the message box under a manager's feed behaves like typing into a working agent: if the manager is mid-turn, your message reaches it at the next step rather than waiting for the turn to finish. Each message's row says which happened — steered into the running turn, queued for the next briefing, or, for a manager that is paused, that it is waiting.

The dev CLI#

The manager and its workers use three command families. Every command takes --manager <id|name>; the manager's briefing tells it its own id.

Run dev manager help for the full list. These commands are part of the system-wide dev CLI, so install it once from Agentastic → Command Line Integration…; terminal panes inside Agentastic forward dev manager, dev memory, and dev mail to it. See the System-wide dev CLI reference for installation and JSON output.

Where things live#

The Home is committed after every wake, so git log in the Home is the agent's history. Agent records, wakes, events, mail, and objectives are also indexed in manager-agents.sqlite next to the app's other databases.

Execution modes#

The brain always runs in its Home. Workers run wherever the charter says: local worktrees, containers, or cloud sandboxes, with the run mode you chose (auto-approve or ask before tools). The manager creates them with dev agent create and links them with dev manager link; you can also adopt agents you started yourself.

Security notes#

• The agent's report is a proposal. Status changes, notifications, and linked-agent changes are validated before they apply; unknown objective ids are dropped.
• Third-party text in briefings is escaped and delimited. The agent is instructed to treat it as data.
• The manager never gets more permissions than the agent you chose for it; workers inherit the permission mode in the charter.
• Manager commands are not exposed to paired companion devices.