Overseer Mode
Overseer Mode lets one Agent session coordinate other sessions. The overseer can follow their progress, read their conversations, give follow-up instructions, and help resolve questions within the authority you granted. You can keep working from one coordinating conversation while specialist sessions handle separate parts of a larger task.
Why use this if you are new to RepoPrompt?
An ordinary RepoPrompt session works with a coding agent on a task. When a project grows beyond one focused conversation, you may want an investigation in one session, implementation in another, and an independent review in a third. Without coordination, you have to carry status and instructions between them yourself.
An overseer provides a coordinating conversation for that work. You describe the goal and boundaries, let it assign or follow separate tasks, then review its conclusions. You can still open every session and inspect its messages and tool activity. Start with one or two clearly separated tasks; you do not need a large group of agents to benefit.
If you are learning the composer first, see Agent Mode. In particular, choose execution locations deliberately: separate conversations can still share the same checkout.
Open the oversight control
The composer toolbar includes an oversight control between Workflow and Interview. Open it to enable Overseer mode, add an existing session, inspect relationships in both directions, and manage wake behavior. The captured control uses a branching symbol; newer interfaces identify oversight roles with eye marks and counts.
Use a loaded, user-owned top-level Agent session. If the composer has never sent a message, send an initial coordinating request first. For example: “Help coordinate an implementation and independent review. First establish the tasks and checkouts with me.” An unavailable control explains whether the session is still loading or is ineligible.
Choose how to begin
Create managed lanes. Choose Enable overseer mode, then ask the coordinating agent to create named lanes for defined tasks. A lane is a separate top-level Agent session created for this overseer and linked to it. Activation alone grants no access to your existing conversations. See Lanes.
Link existing sessions. Choose a session through the sidebar oversight menus or paste its session ID into Oversee a session. Review the confirmation naming the overseer and target. This is useful when several conversations already contain work you want coordinated. See Linking Sessions.
The explicit Enable overseer mode activation lasts for that session until its binding or ownership changes or the app restarts. Linking and saved relationship recovery have their own lifecycle; check the current popover rather than assuming an earlier activation grants access after a restart.
What the overseer can do
For a properly linked target, the confirmation describes access to status and conversation, instructions, steering, stopping the current run, applicable questions and one-time approvals, context compaction, and updates that can wake the overseer. Session-wide approvals, hook trust, merge reviews, and secret inputs stay with you.
An overseer can coordinate work across RepoPrompt windows, but it does not combine every session into a single conversation or automatically merge their file changes. Review results and integration decisions in the target checkout.
Organize sessions with delegated permissions
An overseer can also administer sessions through a delegation scope. A scope defines the sessions it covers, permitted actions, and limits. It is separate from an oversight link, which carries conversation updates and coordination between a pair of sessions.
Ask for the outcome and boundaries in ordinary language, for example:
Organize this workspace's completed investigations into groups, pin the active implementation, and archive finished sessions. Leave running work alone.
When the request needs authority the overseer does not already hold, RepoPrompt presents a scope approval card. Review its coverage, capabilities, and limits; you can narrow the proposed grant. Existing standing consent can cover a later request. The optional Overseer full access setting grants broader authority and can avoid these scope cards; enabling Overseer mode alone does not grant that access.
| Capability | What it permits within the scope |
|---|---|
| Observe | List, search, and inspect sessions and progress. |
| Organize | Rename, pin, reorder, group, archive, and unarchive sessions. |
| Control | Send or steer work, answer eligible prompts, stop runs, compact context, and change available model or effort choices. |
| Restructure | Manage links and session organization, release sessions, and retire eligible work. |
| Spawn | Create or fork sessions and delegate to nested overseers. |
| Worktree | Create and manage session worktree bindings, prepare merge previews, and request a merge review. |
Scopes can cover one exact session, a session tree, a workspace, or all sessions. An ordinary all-sessions scope supports observation, organization, and restructuring; it does not by itself grant control over every running task. Session deletion remains a user action under ordinary scopes; Overseer full access allows session deletion without confirmation cards, subject to the remaining target and run-state checks. Removing or pruning worktrees, changing provider permission modes, approving MCP clients, and changing app settings remain user actions. Oversight can manage eligible approvals within a task without granting permission to change those underlying controls.
Nested delegation
An overseer with the required scope can give a member session a narrower scope to coordinate part of the work. The nested scope cannot expand its parent's capabilities, membership, or limits. Session, depth, and worktree limits apply across the delegated tree; a nested overseer does not receive a fresh unrestricted budget.
Releasing a scope revokes its nested scopes too. Moving a session in the sidebar or linking it to another session does not grant new scope membership. Use explicit tasks and review the scope status when a nested coordinator cannot perform an operation.
Worktrees on behalf of linked agents
With the required authority, ask the overseer to create or bind a worktree for a target session, inspect its worktrees, or prepare integration. RepoPrompt resolves the repository from the target session; when it has several worktree bindings, specify which repository or worktree you mean. A bind can be deferred until the target reaches an idle boundary.
Releasing a worktree unbinds it and marks it for user cleanup; it does not delete the checkout. Merge application still uses the target session's user review. See Worktrees for setup and integration.
Keep coordination visible
The dashboard distinguishes Idle, Running, Waiting for input, and Unavailable. Open a session to inspect its actual result; an idle state alone does not prove its goal is complete. Pending updates and New indicators help you spot changes since the overseer last handled them.
Automatic wake controls can start additional model turns, consume usage, and produce further updates. Configure them around the task's needs, and use Unlink to end a relationship when coordination is finished. Best Practices explains work boundaries, wake settings, result review, and recovery.