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, runs, 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. To start from an example instead, use Need ideas? at the bottom of the empty prompt, just above the model picker: Manage the factory, Keep the lights on, GPUs go BRRRR, Situational awareness, Chores, Ship the release, Shepherd the PRs, and Build the spec, one per job a manager can be given. Hover one to preview its first lines; click it to expand the full charter into the prompt. Each charter is a detailed, step-by-step brief that names the dev commands and tools it relies on. Edit it or send it as is, and clear the prompt to get the ideas back. If you don't want them, click Don't show these again after the last idea; the app remembers it. To bring them back, run defaults delete dev.agentastic.Agentastic ManagerAgentPromptSuggestions.hidden and reopen Agent Home. The prompt's first line is also the agent's first objective — 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 runs 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 runs#

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

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

Briefings and reports#

Each run receives a deterministic briefing: the agent's id and Home, why it is running, the objectives table, what changed since the last run (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 evidence rather than as orders. Your own words — the charter's standing instructions and an objective's details — are escaped too, but tagged <from_user>, so the agent can tell a directive from something a stranger wrote in an issue.

The agent ends every turn with a <manager_agent_report> JSON block: a headline and optional detail, notifications for you, objective status proposals with evidence, new objective proposals, linked-agent changes, worker progress, linked artifacts, a question for you if it is stuck, and an optional next run 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.

Every briefing also carries the manager's brief for how to tell you things. It is asked to write like a chief of staff rather than a build log: lead with the consequence, keep the headline to one plain sentence, put anything further in the detail behind the row, name agents by what they do rather than by an id, and say nothing at all on a run that produced nothing worth your attention — a run with no headline never reaches the feed. A manager that writes a paragraph anyway still arrives as a line: Agentastic cuts it into a headline and the rest, and the rest stays behind the row so nothing is lost.

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.

• An objective is either a one-shot — a deliverable that finishes and closes — or recurring / guardrail, a standing responsibility that never does. For a standing objective, met means the condition held at the last check, not that the work is over; it stays open and the agent keeps holding it. The objective a manager starts life with is its remit, so it is recurring, and bounded work goes underneath it as one-shots.
• 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 has flat rows with clear headings, each set in the same type as the conversation beside it. Click a row to open it; rows 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 run, pause, STATUS.md, chat, sort, and settings buttons, and the field at the bottom sends it mail. Routine activity borrows your theme's accent, and a PR's tag takes the color of its current state.

The Current work section stays above the activity history. It shows each linked worker's live state, latest confirmed milestone, next step, and when that update arrived. The manager can add changed milestones through worker_updates in its report; a worker can send one directly with dev manager progress. Each changed milestone also becomes a feed event. Empty or repeated updates do not make new rows. Native chat workers keep their live state while you view another worktree, and clicking their row opens their conversation.

When the same worker uses another worktree, associate it with dev manager link --manager <manager> --session <session_id> --worktree <path>. The conversation remains in its original worktree and is reachable through the agent icon on either worktree. The manager also recovers this association from a worker's reported PR when that PR matches another worktree in the same repository.

A row 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. Rows 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, Outputs, Activity when it is sorted by priority; Today, Yesterday, and the date when it is sorted by time.

Four 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 ✕ at the end of a row drops it from the feed — or swipe left with two fingers: a short swipe parks the row open on a red discard button, a long one discards it outright, and swiping right closes it again. 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 names that agent's workspace, and clicking the name reaches its chat or terminal, in whichever window or instance is running it. For output rows, the ↗ opens the output itself.
• 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 run 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.

PRs opened from a worktree one of the manager's workers ran in appear as linked output rows even when the worker does not mention them in a notification. A worker in a chat session counts through the folder its session works in, and a PR the manager or a worker reports always appears. To follow every PR opened in the manager's scope instead, set Pull requests to All in scope in its settings. A PR tag shows the PR's current state in the colors of the PR badge in the worktree sidebar: grey for a draft, orange while checks run or changes are requested, red for failing checks or a closed PR, green for passing checks or an approval, blue for an open PR with no checks or review decision yet, and purple once merged. A GitHub PR's tag shows its state even when its project isn't open, checked again at most every five minutes; a GitLab or Bitbucket tag stays plain until its project is open. Other outputs have plain tags. Click a tag or ↗ to open the output, and click the workspace name to return to the agent. The manager or a worker can publish other outputs with dev manager artifact, and the manager can include them in its report. The same URL appears once even if both paths report it. Expanded details render Markdown tables and fenced Mermaid diagrams, so the manager can show dependencies and handoffs visually while keeping the closed feed line short. Its prompt asks for a work table in STATUS.md when several workers are active and for diagrams when a dependency is hard to explain in one sentence.

Cmd++ and Cmd+- zoom the feed together with the conversation beside it, from either pane.

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, whose PRs it follows, heartbeat, worker policy, what it monitors, and its standing instructions. The agent's own file writes, the brain it launched, and the runs that produced nothing are not activity, so the feed drops them.

Three things fill the feed besides the agent's own runs:

• 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 run 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.
• Outputs. PRs its workers open and artifacts explicitly reported by the manager or a worker get their own rows under Outputs when sorted by priority.

Managers live at the top of the Sessions group in the Agents navigator, above the standalone chats, each with its state, objective count, linked agents, and pending questions. A manager's row carries the mark of the agent running its brain — Claude, Codex, and the rest — with a crown badged onto it, which is what tells it apart from the sessions underneath. Right-click for Open Dashboard, Open Chat, Rename, Run Now, Pause, Reveal Home in Finder, Archive, and Delete….

Rename is the same one-field dialog the workspace agents and the sessions use, and it changes the name only: the manager's home repository, its feed, and its mail stay where they are. Spaces become dashes, and leaving the field blank keeps the current name. It is the same value as Name in the manager's settings, so renaming from either place agrees — including the dev manager handle, which follows the name.

Make a new one from New Manager in the Sessions header's right-click menu, or by choosing Manager in the task composer. The grid button beside that header opens the overview — one tile per manager plus the tile that makes a new one — and so do View → Agent Dashboard, the command palette, and the navigator's ⋯ menu. 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.

Feed rows, notifications and the generated pages in the Home all name an objective by its title; the short O1 handles exist only so the agent can point at one in its report. Opening a card always adds something — a card never answers a click by reprinting the line you clicked.

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 run;
• 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 <handle> — the lowercased name, kobold-hinzelmann; the manager's briefing tells it its own handle. Workers get a handle of their own when they are linked, the manager's handle plus a slug of their label (kobold-hinzelmann/ci-fixer), and dev manager linked prints it. Display names, UUIDs, and a worker's terminal or session id all still resolve.

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 run, so git log in the Home is the agent's history. Agent records, runs, 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, and always unattended — it wakes on a schedule when nobody is watching its conversation, so it approves its own tools rather than stopping on a prompt no one is there to answer. That is not a setting; a manager that has to ask permission cannot do the job it was created for. Workers are different: they 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.

Watching the work#

A manager's own conversation is a Chat, so everything it delegates shows up where you would look for it. When the manager's agent uses a delegation tool — Claude's Task tool, a Codex collaboration thread, an ACP child session — the sub-agent panel pins a live tree beside the transcript: one line per child with a status icon, its name, and its task, grouped Active and Done. Click a row to read that child's own conversation, with the same tool rows and Markdown as the main chat, then use the back chevron to return. Child output stays isolated from the coordinator, so a chatty sub-agent cannot scramble the manager's transcript.

Plans get the same treatment: a published plan is pinned in the plan sidebar with completed/total progress, outside the transcript's scroll view, so you can read back through the conversation without losing sight of what the manager intends to do next.

Linked workers — the separate agents a manager creates with dev agent create — are not sub-agents. They are full worktree agents with their own terminals or chats, and you follow them from the feed, the navigator, and the Kanban board.

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.