# Captains (https://docs.capy.ai/captains)

> Run a long-lived Captain that directs a crew of threads, keeps a digest of what needs you, and stores its plan and rules in its own Drive.

A Captain is a long-lived agent that runs other threads for you. Use it for work that outgrows one [thread](/threads), such as a feature with many PRs or a queue of requests. You tell it what it's for, and it starts threads for the work, reads their reports, and tells you only what needs you.

<Screenshot name="captains-crew" alt="Captain Overview with its crew and Needs you list" caption="A Captain tracks its crew and the decisions that need you." />

The threads a Captain runs are its crew. Each crew thread is a full thread with its own [subagents](/subagents). The Captain hears from a crew thread each time the thread finishes a turn or needs something. It keeps its plan and rules in its own [Drive](#captain-drive), so it continues where it stopped. Use one Captain per area or feature.

## Turn on Captains [#turn-on-captains]

Enable the **Captain** experiment to add Captains to your sidebar.

<Screenshot name="experiments" alt="Experiments settings with the Captain switch" caption="Your experiment setting overrides the organization's default." />

An admin can turn Captains on by default for every member under **Org**. Each member can still turn the experiment off for themselves.

## Create a Captain [#create-a-captain]

- **New Captain** sets its name, face, project, machine, model, and access. Crew threads use that model unless you or the Captain pick another.
- **Promote to Captain** turns a thread into a Captain and makes you its owner. It keeps its history, pull requests, machine, Slack thread, project, model, and members, and takes the Captain's name.
- Promoting a folder you own adds its threads to the crew and removes the folder. Confirm its access and the threads that stay out before proceeding.
- **Ask any thread or Captain.** Say "Make a Captain called Mobile for the iOS and Android work." The new Captain is yours, runs in the cloud, and is separate from the thread that created it.

In your first message, tell the Captain what it's for. It writes your answer into its rules and plan.

## Demote or delete a Captain [#demote-or-delete-a-captain]

The owner can turn a Captain back into a thread with **Demote to thread** in its menu. **Archive** puts the Captain and its crew to sleep and keeps everything, and **Unarchive** brings them back. **Delete** removes the Captain and returns its crew threads to your thread list.

## Manage the crew [#manage-the-crew]

Every thread a Captain starts joins its crew. Add existing threads by dragging them onto the Captain, using **Move to**, or the threads page's **Captain** action. A folder's **Add to Captain** adds its threads together. You can also ask, "Take CAPY-412 and CAPY-415 into your crew."

A crew thread must be in the Captain's project, and it can't be a subagent or a Captain. A thread can be in one crew at a time. It keeps its project, machine, model, and Slack thread, and its access follows the Captain's.

The Captain removes or archives its threads when their work is done. To release one yourself, drag it out, use **Remove from crew**, uncheck the Captain under **Move to**, or ask "Release CAPY-412." The thread keeps its history and pull requests.

Crew threads open beside the Captain's chat. The Captain sees their replies and updates its plan without repeating them to you.

To see every pull request the crew opened, filter the **Pull requests** page by **Captain**.

## Read the digest [#read-the-digest]

Each Captain keeps a digest of what needs you, what's new, and what's in progress. It rewrites the digest when the crew's state changes.

Read the whole digest in the **Digest** tab. The top of the **Overview** shows the first five items under **Needs you**. When a report changes the digest, the Captain pastes its **Needs you** section into the chat. It tags you when a decision or a blocker is yours, and the tag notifies you like any mention.

To answer an item, reply in the Captain's chat, for example "merge capy#3780" or "hold the migration until Monday". The Captain acts on it and drops the item on its next rewrite. If a crew thread asked you a question itself, answer in that thread.

To change the layout, tell the Captain: "Group the digest by project and add a Shipped this week section." It saves that as a rule.

## Captain Drive [#captain-drive]

Each Captain has its own Drive, where it and its crew keep plans, rules, and reports. It's separate from your [other drives](/drive) and counts toward your organization's [storage limit](/drive#storage-limits). Open it from the Captain's **Drive** tab or its **Overview**.

| File | What it holds |
| --- | --- |
| `AGENTS.md` | The Captain's own rules, such as which models to use and what needs your approval. Crew threads don't read it. |
| `CREW.md` | Rules that every crew thread reads on every turn, such as "open PRs as drafts". |
| `NOTES.md` | The Captain's plan and working notes. |
| `DIGEST.md` | The digest you read in the **Digest** tab. |
| `skills/` | Procedures the Captain and its crew follow, such as a release checklist. |
| `reports/`, `renders/`, `handoffs/` | Reports, screenshots, and data that crew threads leave behind. |

To change a file, tell the Captain, for example "From now on, run the e2e suite before calling a PR ready." It writes the rule in the right file and confirms.

## Share a Captain [#share-a-captain]

A Captain has an owner and an access setting, like a thread. Set access when you create the Captain, or later from **Share** in its menu.

- **Everyone at your organization.** Every member can read the Captain, its crew, and its Drive, and message it.
- **Only specific people.** Only the people you name can see the Captain, its crew, and its Drive. This option needs **Private work** turned on in **Settings → Org → General**.

Crew threads have the same access as their Captain. Sharing the Captain shares its crew, and removing someone from a private Captain removes them from its crew. If a joining thread is shared, it narrows to the Captain's people after you confirm. If it's private, it opens to more people only when its owner confirms. A private Captain can't take a thread whose owner isn't one of its people, so share the Captain with them first.

A Captain always acts as its owner, whoever messages it. It creates crew threads as the owner, with the owner's GitHub access and [connected subscriptions and keys](/models-and-pricing#connections).

| Action | Owner | Anyone who can see it |
| --- | --- | --- |
| Message the Captain, manage its crew, archive and unarchive it | Yes | Yes |
| Rename it, change its face or alias, set **Crew runs on** | Yes | No |
| Change access, transfer ownership, demote, and delete | Yes | No |

## Projects and machines [#projects-and-machines]

You set a Captain's project when you create it. The Captain takes crew threads from that project only. Each crew thread gets the project's repositories as they are when the thread starts.

A Captain runs in the cloud by default, and its machine sleeps between turns. A cloud Captain uses [machine time](/models-and-pricing#machine-pricing), which comes out of your credits even when the model runs on a connected subscription.

A Captain can also run on a paired device that's yours or shared with your organization. Pick the device under **Run on** in **New Captain**, promote a thread that runs there, or use **Continue on** in the machine menu.

The owner picks where crew threads run with **Crew runs on** in the Captain's **Profile**: the cloud or one paired device. To pick a machine for one thread, name it: "Run this one on my Mac mini."

## Steer a Captain from Slack [#steer-a-captain-from-slack]

Add `captain=<name>` to a message to Capy in Slack. The message goes to that Captain instead of starting a new thread.

```text
@Capy captain=Mobile the TestFlight build is crashing on launch, take a look
@Capy captain="Platform Captain" !queue add the retry fix to the next release
```

Put quotes around a name with spaces. You can also use the start of the name, a whole word from it, the thread code (`captain=CAPY-210`), or the Captain's **Alias**. The owner sets the alias in the Captain's **Profile**. If more than one Captain matches, Capy asks you to pick one.

The message interrupts the Captain unless you add `!queue` or `!steer`. Capy replies in Slack with a button that opens the Captain. The Captain answers in the app, not in Slack. A private Captain takes `captain=` messages only in a direct message with Capy. See [Slack](/integrations/slack) for the other directives.

## Automations and the API [#automations-and-the-api]

To wake a Captain on a schedule, ask it to set up an [automation](/automations): "Every weekday at 9am, check the open PRs and update the digest." An automation can also send a Captain new tickets, and so can `@Capy captain=<name>` in Slack.

The [public API](/api-reference/overview) lists and creates Captains, and reads a Captain's crew and digest. To message a Captain, use the thread message endpoint with its thread id.

## Example setups [#example-setups]

### Feature Captain [#feature-captain]

One Captain per large feature, with every PR for that feature in its crew.

```text
You're the Captain for the new billing dashboard. The spec is in docs/billing-dashboard.md. Split it into PRs that merge independently, with one crew thread each, and stack the ones that touch the same files. Every crew thread opens a draft PR, runs the tests, and reports back with the link. Nothing merges without my word.
```

### Triage Captain [#triage-captain]

One crew thread per bug report, feature request, or ticket.

```text
You handle small incoming work for the web app. Never do the work yourself. Start one crew thread per item, and ask me first if an item is unclear or bigger than a day. Add a rule to CREW.md that every thread reproduces the bug first and opens a PR with a test.
```

### Janitor Captain [#janitor-captain]

Upkeep nobody owns, such as flaky tests and stale PRs.

```text
You're the janitor for this project. Every Monday at 9am, look for flaky tests, dependency updates, and PRs with no activity for a week. Start a crew thread for each small fix, and send me anything bigger as a suggestion.
```

## Good to know [#good-to-know]

- Turning the experiment off hides the Captain actions and stops Captains from starting crew threads. Nothing is deleted.
- A thread leaves your folders when it becomes a Captain or joins a crew. Captains and crew threads can't go in folders.
- To move a crew thread to another crew, pick the other Captain under **Move to**.
- An archived crew thread leaves the sidebar but stays under **Archived** on the threads page.
- A Captain acts on its own. To limit it, give it a rule, such as "Ask before starting more than two threads at once."
- Captains can read and message each other. To stop status messages between them, add a rule: "Don't message other Captains unless I ask. Read their digest instead."