# Orchestrators

> A chat you drive that sees the projects you link to it, and the sessions of its account.

An orchestrator is a chat you drive that works across projects. It reads their boards, sees the Claude Code sessions of its account running now, and can hand a card's work to a new session — on the board like any other. It is for the question a single project cannot answer: where does everything stand, and what should go where next.

![An orchestrator's chat beside its Sessions panel: it has started a session on a flaky test, and that session's question waits above the composer under Waiting on you.](/docs/images/01M3YX76TTV3GZMM9T5XHRC4JR)

It is still you deciding. It never moves a card into a lane that runs a step, nothing it does on a timer starts work, and nothing it sends approves anything in another session. See [What it never does](#what-it-never-does).

## Making one

**Orchestrators** is a group at the top of the project rail. Its **+**, or the **New orchestrator** row, asks for two things:

| Field | What it is |
|---|---|
| **Name** | what the rail calls it, e.g. `Work` |
| **Runs as** | the Claude Code account it speaks as — one of your [profiles](/docs/profiles), or **New profile…** |

An orchestrator runs on Claude Code only, and an account can have several. Right-click one in the rail for **Edit…** (name, icon and colour), **Runs as…** (its next turn starts under that account; conversations so far stay with the one they began with), **Reveal folder** and **Remove…**. Removing it takes it off the rail; its folder stays on disk.

## Its folder

Each orchestrator gets a folder of its own, `~/.devpit/orchestrator/<name>/`, named after it in lower case. It is not a git repository.

| Path | What it holds |
|---|---|
| `.devpit/orchestrator.md` | devpit's brief: what it may do and how. Rewritten when devpit updates. |
| `.devpit/assistant.md` | the brief for [Assistant mode](/docs/assistant), only while that is on |
| `CLAUDE.md` | yours. It imports the brief, and what you add is left alone. |
| `context/projects/` | what it learns about each project |
| `context/preferences.md` | your preferences, and its **Rules for sessions** |
| `decisions/`, `docs/`, `artifacts/` | decisions, documents and files it keeps |

Which account it runs as, and which projects it reaches, are kept by devpit, out of reach of its own chat.

## Linking projects

An orchestrator reaches only the projects you link to it. Its right panel opens on **Sessions**; **Boards** beside it lists the linked projects with their lanes and how many cards each holds, a lane opening to its cards and a card opening on its project's board.

**Link projects** lists every project as a checkbox, grouped; a group's own checkbox links all of it at once. **Save** keeps the choice. Only linked projects show in Boards, only their folders are open to its chat, and only they are in reach of its tools. **Add a project, and link it here** picks a folder, names it, puts it in a group and links it, in one screen.

### Proposals

Asked to — *"add ~/Workspace/x to the ASC group"* — it proposes a project rather than adding one. The proposal waits as a card above the composer, such as *Add `~/Workspace/x` as `x`, put it in ASC, link it here?*, with **Yes**, **Edit** and **Drop**. **Yes** does it; **Edit** opens the name, group and link first. A project it tries to reach without a link is refused, and it is told to propose the link instead.

## The chat

A new orchestrator opens on *"What should we orchestrate?"*, with starters such as *Where does every project stand?* and *Add a rule for every session you start:*. It opens in **Accept edits** unless you picked another mode for that account before. In **Supervised** its process does not stay between turns, so a session writing back cannot wake it.

## Asking a project

An orchestrator can ask a linked project's [agent](/docs/project-agent) about it — how something works, where something lives — and have it write the brief a card's session starts with, without starting a session.

## Its sidebar

Beside its chat, an orchestrator's sidebar has **Schedules**: every reminder it reaches and every routine you set. See [Assistant mode](/docs/assistant).

## Rules for sessions

Whatever `context/preferences.md` keeps under a heading **Rules for sessions** goes with the brief of every session it starts, so a rule you would otherwise repeat in every hand-off is said once. Its first screen says where they live. Ask it to add one, or edit the file yourself.

## What it never does

- **It never moves a card into a lane that runs a step.** Entering such a lane starts work, so it is refused and asks you to move the card. See [Moving cards](/docs/moving-cards).
- **Nothing on a timer starts work.** It acts when you write to it, or when a session it follows writes back. A [reminder](/docs/reminders), a routine and the [Assistant mode](/docs/assistant) heartbeat only tell you things, and a schedule it proposes waits for your click.
- **It approves nothing in another session.** Answering a question, typing a reply and renaming are yours, from the window; its tools can read a session's screen and transcript, never answer for you.
- **It stops a session or sends a reply in your name only with your word or your click.** See [Orchestrator sessions](/docs/orchestrator-sessions).
  [Guardrails](/docs/guardrails) can change that per orchestrator, and a chat in **Full access** is not asked twice.
- **It types no control characters** into a terminal, and reaches only linked projects and its own account's sessions.

What it does with sessions — handing work, hearing back, drafting replies — is in [Orchestrator sessions](/docs/orchestrator-sessions).
