> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Managers

> Long-lived orchestrators that delegate a domain's work to ship workspaces.

A Manager is a named workspace dedicated to one domain, such as billing or onboarding. It plans and delegates: each piece of work goes to a ship, while the Manager keeps its own context lean and reports back as its ships finish.

Use a Manager for a project with several related tasks, like a list of tickets or a feature that needs a few pull requests. You talk to the Manager and follow the [board](#board); open a ship only to see its code or step in. For a single task, use a [workspace](https://docs.replicas.dev/features/workspaces/overview.md).

## Create a Manager

1. Click **+** next to **Managers** in the left sidebar and pick an [environment](https://docs.replicas.dev/features/environments.md). The Manager is created right away and opens. Before your first one, **+** explains what a Manager is and asks you to confirm, with **Use a workspace** if you meant to start a workspace.
2. In its first chat, rename it and describe what it's for, like "Owns the mobile app: Expo, TestFlight releases, mobile bugs". It reads the description in every chat. Click **Skip** or just send a message to leave it out. To change either later, click its name in the header, or press and hold it in the [mobile app](https://docs.replicas.dev/features/mobile-app.md). If you don't rename it, its description names it, or else your first message.
3. Send it work in any of its chats. It replies right away with what it delegated, then acts on each result as it arrives.

The first time you open a Manager you created, a short tour shows what it does and how it works with Slack and Linear.

Every chat in a Manager runs as its orchestrator.

To create one from the [API](https://docs.replicas.dev/api-reference/replica/create-replica.md) or the `create_replica` [MCP](https://docs.replicas.dev/features/mcp.md) tool, set `kind` to `manager` and use a personal API key.

## Convert a workspace

To turn one of your own workspaces into a Manager, right-click it in the sidebar and choose **More** → **Make Manager**, or press and hold it in the [mobile app](https://docs.replicas.dev/features/mobile-app.md) and tap **Make Manager**. You can also use the [API](https://docs.replicas.dev/api-reference/replica/make-replica-a-manager.md) or the `make_manager` [MCP](https://docs.replicas.dev/features/mcp.md) tool.

* It keeps its chats, sandbox and history. Its next turn in every chat runs as the Manager; a turn already running finishes as it started.
* Ships, archived workspaces and environment setup workspaces can't be converted.
* A `delete_when_done` or `archive_when_done` workspace switches to the default lifecycle so it isn't removed after its next turn.
* It can't be turned back into a regular workspace.

## Ship updates

After delegating, the Manager replies and ends its turn. News from its ships starts a new turn, or reaches it mid-turn if it's still working: a finished turn, or pull requests that are ready or need attention.

## Board

The **Ships** tab opens on the board: one ticket per task, grouped under **Needs you**, **Ready to review**, **Working** and **Done**. Replicas files each ticket from its ship and pull requests, so the groups stay current on their own. Once every pull request on a ticket has merged and deployed, the ticket moves to **Done**, unless it still has a question for you. It shows under **Working** while the deploy runs, and under **Needs you** if the deploy fails or waits on an approval.

Each ship writes its own ticket: a short summary of what it did, the screenshots and recordings that show it, and any question only you can answer. The Manager keeps the board in order, leaves a short note on a ticket when it adds something, and writes one overview line at the top.

Click a ticket to open it. Answer a question with one of its options or your own words: the answer goes straight to that ship, or to the Manager for its own questions. When a ship stops on a question in its chat, the ticket shows the whole question with its options, and your answer goes to that chat as your own message. The ship's reply comes back on the ticket under **Activity**, with a box to keep the conversation going, and a row in the Manager chat links to it. The derived list of ships and pull requests stays under **All ships and pull requests**, below the board.

## Chat

The chat shows your messages, the Manager's replies to them, and what it sends with `send_to_chat` after a ship event: work you asked for, or a blocker that needs you. While it works on your message, it posts short updates and a live status line saying what it's doing. Status like merges and deploys goes to the [board](#board). To see its tool calls and ship updates, turn on **Show activity** in the new chat menu, or in the chat menu in the [mobile app](https://docs.replicas.dev/features/mobile-app.md).

A Manager doesn't write code itself, so it has no **Files** or **Terminal** pane, diffs or editor and branch actions. Open a ship for those. It keeps the **Desktop** tab and previews, so you can run a dev server or sign into a site from it.

## Sidebar

The **Managers** section lists your Managers with their status: needs attention, working (the Manager or any of its ships is working or following up pull requests), ready, or idle. Drag a Manager to reorder the section, the same way as **Pinned**; the order syncs across your devices, and new Managers join at the bottom. Managers always stay in this section, so they can't be pinned or moved to another one.

## Avatar

Each Manager gets a Pixel Crew avatar when it's created. Click it in the Manager's header to pick another preset, an emoji, an uploaded image, or one you added from the gallery. To share yours, open the **Avatars** tab in [Appearance](https://docs.replicas.dev/features/desktop-app.md#themes).

## Slack

Give a Manager its own Slack channel from the Slack button in its header, or by asking it, like "link #team-alerts" or "create a Slack channel for yourself". It uses its [Slack tools](#tools); from outside, use the `add_manager_slack_channel` [MCP](https://docs.replicas.dev/features/mcp.md) tool. Mention @Replicas in that channel to message it, and it replies under its own name and icon. See [Manager channels](https://docs.replicas.dev/features/slack.md#manager-channels).

## Texting

Text a Manager from your phone, and it texts you back when work is done or it needs you. See [Texting a Manager](https://docs.replicas.dev/features/workspaces/manager-texting.md).

## Linear

Send [Linear](https://docs.replicas.dev/features/linear.md) tickets to a Manager by telling it which ones you want, like "send me support-labeled tickets in the current REP cycle", or from the Linear button in its header. Pick a team and, optionally, the current cycle, labels, a project and an assignee; a ticket must match all of them, and have at least one of the labels. New tickets that match, and tickets that start matching later (moved into the cycle, labeled, assigned), arrive once each with their description. Finished tickets and tickets already delegated to an agent are skipped. The rule is an [automation](https://docs.replicas.dev/features/automations.md#linear-triggers) that runs in the Manager: choose **Open automation** in the Linear menu to change its prompt, pause it, or see its runs.

## Sharing

[Share](https://docs.replicas.dev/features/workspaces/overview.md) a Manager to run it together. Teammates you share it with see it in their **Managers** section with its ships, get its notifications, and can reach its ships from the [API](https://docs.replicas.dev/features/api.md) and CLI.

To share it with your whole organization, including people who join later, turn on **Everyone in** your organization in its **Share** dialog. Anyone can then message it, from the app or its [Slack channel](https://docs.replicas.dev/features/slack.md#manager-channels).

A ship runs as the person who asked for it: for a task from Slack, whoever started the thread; otherwise, the last person who wrote in the chat that started it. It gets that person's coding agent login, GitHub account, and environments, so their pull requests open from their own account. Ships started from a chat with no one in it, such as one fed only by a [Linear rule](#linear), run as the Manager's creator.

## Notes

A Manager keeps notes on its domain and its decisions in `~/.replicas/canvas/manager-notes.md`. It reads them when a chat starts and before it delegates work, and updates them when it learns something lasting. The status of ships and pull requests lives on the [board](#board). The file survives the workspace sleeping, and you can read it in the [Canvas](https://docs.replicas.dev/features/workspaces/canvas.md).

## Ships

Each ship is its own [workspace](https://docs.replicas.dev/features/workspaces/overview.md) with its own sandbox, built from its Manager's environment. To change that environment, open the Manager's info panel and click **Change** next to **Environment**. Ships you spawn afterwards use the new environment; existing ships keep theirs, and the Manager's own sandbox keeps the repositories it started with. A Manager can also start a ship in another environment the person who asked can use, their personal ones included, such as a backend-only one for a backend task: ask it to, or it picks one whose repositories and services fit the task. To send a kind of work to the same environment every time, add the rule to the [system prompt](https://docs.replicas.dev/features/environments.md#repository-binding) of the Manager's environment, like "Start ships for mobile work in the mobile-ios environment." Set it before you create the Manager: an existing Manager keeps the system prompt it started with. The Ships pane shows a ship's environment on hover when it isn't the Manager's. It receives only the task the Manager writes for it, and it does not see uncommitted changes in the Manager.

Ships are not listed in the sidebar: find them in the **Ships** tab. A ship's question shows on its ticket on the [board](#board); the Manager's sidebar row only needs you when the Manager itself asks you something.

Under **All ships and pull requests**, below the [board](#board), ships and their pull requests are grouped under **Open PRs**, **Working**, and **Shipping** (merged and deploying), followed by the other **Ships** and the ones that are done. A pull request is ready for review once its ship finishes its turn, even while CI runs; hover it to see its checks, and click it to review it. Click a ship's name to open it in the right pane, where you can follow its work, message it directly, or open its full workspace. On smaller screens, use the **Ships** button in the header. Replies to your own messages stay in the ship's workspace, and so does what the ship reports on its own afterwards, until the Manager messages it again.

A Manager can hold up to 20 ships that are not archived. The Manager archives a ship once its pull requests are merged or closed, and messaging an archived ship restores it. Ships cannot spawn their own ships.

## Pull request follow-through

A ship that opens a pull request is not done until the pull request is ready. [CI failures](https://docs.replicas.dev/features/github.md#ci-failure-response) and [review comments](https://docs.replicas.dev/features/github.md#auto-respond-to-review-bots-and-users) are still fixed automatically in the ship's workspace, and the Manager tracks them instead of calling the work finished.

Once activity settles, the Manager gets one report per ship:

* **Ready**: CI passes, automatic fixes are done, and nothing but a human review or branch protection blocks the merge. The report summarizes what was fixed along the way.
* **Needs attention**: CI still fails with no fix running, the pull request is a draft, has conflicts or another merge blocker such as requested changes, or fixes have not settled within an hour. The Manager messages the ship or asks you.
* **Merged or closed**: the ship's task is done, and Replicas archives it. The archive notice reaches the Manager with its next update rather than waking it. The Manager acts on it only when other work waits on it, such as starting the next task once a pull request merges.

Each report is sent once: a later check that finds the same state stays quiet until something changes.

Ask the Manager to merge a pull request when it's ready, and Replicas merges it once it's approved and CI passes, using the repository's merge method. CI, here and in the reports above, is the checks GitHub requires plus the repository's GitHub Actions runs, so optional checks from other apps, such as preview deploys, don't hold it. If it can't merge, for example because of conflicts or a dismissed approval, the Manager hears why and has the ship fix it.

The Manager tracks each one on the [board](#board) and replies in chat only to what you ask. Replicas also notifies you when a pull request is ready for review or the Manager needs you: a toast in the dashboard, or a notification from the [desktop app](https://docs.replicas.dev/features/desktop-app.md) when it is in the background.

## Tools

The Manager manages ships with these tools from the [Replicas MCP server](https://docs.replicas.dev/features/mcp.md). They are not available in Cursor chats.

| Tool | Description |
| - | - |
| `spawn_subagent` | Start a ship with a self-contained task, and its ticket from `title` and `task`, or pass `ticket` to continue an existing one. It uses the Manager chat's coding agent, model, and thinking level unless `coding_agent`, `model`, or `thinking_level` is set. `service_tier` (`fast` or `ultrafast`) and `goal_mode` set its speed and mode |
| `message_subagent` | Send a follow-up to a ship, waking it if it is asleep. The message is delivered once the ship is up, and if it can't be, the Manager gets a `needs_attention` event with the message. A working ship is steered mid-turn when its agent supports it, unless `queue` is set, a setting changes, or goal mode is on. `coding_agent`, `model`, `thinking_level`, `service_tier`, and `goal_mode` change how it runs from that follow-up on |
| `list_subagents` | List active ships with their state, settings, pull requests, CI status, and pending fixes. `include_archived` adds archived ships |
| `read_subagent` | Read a ship's settings, pull request status, and latest response, with the screenshots and GIFs it links attached as images. Long responses come in pages; `offset` reads the next one |
| `archive_subagent` | Archive a finished ship. Refuses one that is working or has open pull requests unless `force` is set |
| `merge_when_ready` | Merge a ship's pull requests once they're approved and CI passes. `pr_url` picks one, `cancel` stops it |
| `get_board` | Read the [board](#board): its overview and tickets |
| `update_board` | Order tickets, set a ticket's note, title or Linear issue, archive tickets, set the overview, or add tickets of its own |
| `update_ticket` | Used by ships: write their ticket's summary, media, questions or blocker |
| `reply_on_ticket` | Used by ships: answer you on their ticket when you write to them there, with an optional follow-up question |
| `send_to_chat` | Post a Markdown message, with images and links, to your chat |
| `get_slack_channel` | Show the Manager's [Slack channel](#slack) |
| `link_slack_channel` | Link an existing Slack channel by name or ID. Replicas joins a public channel; invite @Replicas to a private one first |
| `create_slack_channel` | Create a public `#manager-<name>` channel, invite you, and link it |
| `unlink_slack_channel` | Unlink the channel. It stays in Slack |
| `set_slack_channel_level` | Change the channel's level, which decides which untagged messages reach the Manager, when someone asks there, like "be more proactive here". The same people can change it as [anywhere else](https://docs.replicas.dev/features/slack.md#proactivity) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.