Project Lead Session

A project lead is a normal top-level session with one extra job: it leads a single project’s work for you. It is not a working agent. You talk to the Project lead in its chat, and it hands out assignments to regular parent sessions, follows their progress, and reports back. It does not write the code itself; the parent sessions it starts delegate to their own child sessions exactly as before.

The feature is optional per project. A project without a project lead behaves exactly as it does today, and there is at most one project lead per project. A project lead is responsible for its project and for subprojects that do not have a project lead of their own.

With and without vord Brain

vord records each assignment the lead hands out (session, tickets, goal, start, end and the result the lead gives when it stops the session) in project memory. With vord Brain these are notes tagged pl-assignment in the project; decisions and preferences come on top. Without Brain the same entries live in .vord/project-lead/memory.jsonl, which is also the working copy.

The lead searches memory with lead_memory before it says what happened. It never loads memory whole.

Older brief.md/assignments.md stay as legacy and are only searched by ID.

The board question about preferred agents/models/accounts is now recorded as a preference.

Starting one on the Mac

Open the project menu and choose Start project lead…. A dialog asks for the agent, account, model, and thinking level, plus up to three optional start templates from a Start templates menu. The model list shows orchestrator models only. Automatic picks the account with remaining quota; Muse has no account choice. Confirm with Start. Without templates the session starts without a first prompt; with templates the lead first aligns on the kickoff questions and vord files the templates in project memory. Its chat opens in its own column between the sidebar and the main area. The sidebar shows a Project lead row above the project’s sessions — clicking it opens the column and puts the cursor in the input field (“Message the project lead”). The column header shows “Project lead · project” with status dot and agent, and you can switch it between chat and terminal like any tile. As the column narrows, the header drops the agent name, then reduces the work state to its icon, and finally reduces the Chat/Terminal switch to icons; the status dot stays visible throughout. A project without a project lead keeps the column, with an empty state and the button Start project lead…. Under All Sessions the column is visible as soon as any project has a project lead, and the header offers a menu of those projects. The empty state under All Sessions appears only when no project has a project lead, and then shows the selected session’s project, or otherwise the first project in the sidebar. It opens on the selected session’s project when that project has a lead, otherwise on the last project chosen in the header, otherwise on the first project in the sidebar; the latest action then wins, and a session in a project without a lead leaves the column where it is. While the sidebar is filtered to one project, the column still shows that project’s lead. A second start opens the existing project lead instead of starting another. In ⌘K and in History the project lead is listed as a project lead, and choosing it opens its column. History restores an archived project lead only when the project has no other active project lead.

One session per task

The project lead starts a new session for each task, with a clear assignment, and stops it after the report. There are no standing team roles, standing sessions, or alarm jobs. In former Cowork projects, .vord/teams remains as leftover files and is at most background for assignments.

Changing the project lead

Choose Change project lead… in the project menu or the column menu. The same dialog opens with the current settings filled in. Before you confirm, it shows which of the two paths the change takes:

The conversation continues. If the settings keep the same provider, the accounts share their history, and the current lead is running with a resumable conversation, vord moves that session to the new account or model. Assigned sessions, waiting reports, board items and scheduled jobs stay with it, and the button reads Continue.
A new project lead starts with a handover note. Otherwise vord starts a new lead with those settings and gives it a handover note about the previous conversation. It takes over all assigned sessions, waiting reports, board items and scheduled jobs; the current lead is archived. The button reads Hand over.

A handover names its reason in short form: the current lead has no saved launch settings, the provider changes, the provider cannot change the model while continuing a conversation, the current conversation cannot be resumed, the current lead is not running, or the selected account does not share the conversation history.

Chatting with the lead: attachments and line breaks

The chat input accepts file attachments and multi-line messages:

Attach files with the paperclip button or by dragging files onto the composer. Attached files travel as file paths in your message, which the lead can read.
Paste an image from the clipboard with Cmd+V, or drop an image file onto the input field. It appears as a small preview above the input field before you send it — remove it again with its ✕ button — and reaches the lead as an image, like pasted images in regular sessions. The input field itself never holds an image. In the chat, that pasted image shows up as an attachment with a small preview inside your message. Click the preview to open the image large.
Return sends the message. For a new line, use Shift+Return, Option+Return, or Command+Return.
Unsent text in a project lead’s composer stays when you switch views or projects. It is kept until you send it or quit vord; attachments are not kept. Automatic events, such as a lead started from your iPhone, don’t move the keyboard away from a composer you are typing in. The same holds for unsent text in board answers, the board note field, the Mesh chat, and the tile/peek inputs: switching keeps the draft until you send it or quit vord.

When a claude agent asks several questions at once, the Mac chat view shows them one at a time in the conversation, the project lead column, and both Code and Cowork modes. Each step is labelled Question 2 of 3 · short title (with the current question and total); choosing an answer opens the next question. After the last one, Review your answers lets you choose Submit answers or Cancel. The question box closes only after that review step. A multi-select question instead shows Multiple choice: please answer in the terminal; after you answer there, the chat shows the next question. Text typed in the chat composer while a question box is open is kept, with Sent once the open question is answered shown below it, and sent automatically when the box closes.

What it can do

The lead’s tools accept the vord project id, the Brain project id or the project tag, and lead_list_sessions always names the projects in the lead’s scope.
lead_list_sessions also names the paired hosts with their online status, the “Sessions” role, and whether a project-lead start is possible there.
Start new top-level sessions in its project and give them their first task, framed as coming from the project lead on your behalf. With host (name or device ID of a paired host) and workdir (absolute folder there), lead_start_session starts the session on that host instead of this Mac. This needs The project lead may start sessions on paired hosts in Settings and a current vord-headless on the host; account cannot be combined with host.
List the installed agents that can run parent sessions, their orchestrator models, and each account’s current usage and running sessions. It can choose a specific account for a new parent session; without a preference, vord chooses the agent’s orchestrator default on an account with headroom. The orchestrator default is your default model for that agent in Settings when it is an orchestrator model in its newest version; otherwise vord takes the newest version of the agent’s least expensive orchestrator family, for example claude-opus-5-5 for Claude and gpt-6.1-sol for Codex. Orchestrators run only on the newest version of a model family: the list names only that version per family, an alias such as opus starts it, and lead_start_session rejects an older version such as claude-opus-4-6 with model_outdated.
lead_list_sessions and lead_session_status show the model each session is actually running, taken from its transcript or status line. Before the first answer they show the explicit start model, never an alias.
Session rows from lead_list_sessions and lead_session_status include scheduled_child_count, the number of child starts scheduled for that session.
Send follow-up tasks to any top-level session in its project — including sessions you started yourself — and read their status and output. When lead_send_prompt is held by a target account’s personal weekly limit, it returns held_by_usage_brake with the account and usage details; the prompt stays queued until release.
Receive reports on its own: when a session it leads finishes a turn, errors, or hits a usage limit, the lead hears about it without you relaying anything. Sessions you never handed it stay quiet.
Stop sessions in its project. Project lead may stop all sessions is on by default — globally in Settings, and each project can override it (Follow setting, On, Off) — so the lead may stop every top-level session of its project, not only the ones it started itself. Never another project lead, a child session, or an archived session, and never a session that waits for you. The sole archived exception is a finished session still assigned to and started by that lead: repeating lead_stop_session succeeds idempotently, leaves it archived, and stops nothing. Stopping a session the lead did not start itself needs a reason, and the stop is written to the event log with it. Job sessions (automation runs) of its project it may stop regardless of this setting. With the setting off, the lead may only stop the sessions it started itself, plus those job sessions. A session the lead started itself stays stoppable for it even after it released the session and leads it again later — also for sessions from older vord versions. It can also release any session it leads back to you to end coordination; the session keeps running. Sessions a project lead starts stay attributed to the project lead role of that project, also after the lead is handed over, moves to another account, or vord restarts.
Answer open board questions and to-dos of sessions it leads. The answer is delivered like yours, but marked Answered by the project lead, so the session (and you, on the board) can tell who replied.
Search project memory with lead_memory before saying what was done, decided, or assigned. It never loads memory whole; older brief.md/assignments.md stay as legacy and are only searched by ID.

When vord is busy, the lead’s reading tools wait up to 25 seconds and try once more; the error then says whether vord is not running or is running but did not answer in time.

What it cannot do

Touch other projects, or sessions outside its project’s scope.
Answer board items of sessions it does not lead — those it can only read.
Answer board items without an origin session (for example an unassigned brain to-do) or its own board questions to you. Those stay with you.
Answer permission, plan, or question boxes. Boxes are yours alone; when one appears, the lead tells you instead of deciding.
Spawn child sessions or run workflows. It coordinates parent sessions; delegating further down is their job. vord blocks those tools for the lead. For larger multi-stage work, the lead can offer the parent workflow blueprints as an option in the assignment, not for small fixes; see Workflow Blueprints.

Board lanes and handovers

When its project shares one board between Code and Cowork (see Code and Cowork on one board), the lead sees its own side, Coordination entries, and anything handed to it. An open question or to-do can be handed to the project lead of either side from the entry’s right-click menu (Hand over); the lead gets a line in its terminal while it runs, otherwise it finds the entry marked as handed to it in its board context at the next start. The lead’s lead_board_list accepts an optional lane filter (code, cowork, both) to read one side only.

Open questions, to-dos, commitments, and notes can be assigned to a project member from the board item menu; open commitments also have this action in the Agenda context menu. Assignment for questions, commitments, and notes requires support from the linked vord Cloud server. If an item has no owner because its project has no lead, choose Start project lead and hand over from its menu. This opens the usual project-lead start flow, and the new lead takes the item automatically. The option is absent once the project has a lead; notes are never unowned. An active project lead receives one short context line for each new assignment.

What it focuses on

The lead keeps project memory current, talks with you, and manages the parent sessions it runs. With vord Brain connected, that memory is the project hub, the living open-points note, decisions, and learnings. At decision points — the results of lead_start_session, lead_memory, board_ask, board_todo, and claims — vord appends up to three matching learnings from vord Brain, each note at most once per session and again after a context compaction. Quick look-ups to answer you are fine. Multi-step diagnosis, measurements, implementation, builds, and tests go to a parent session the lead already runs or starts. That session plans and delegates to its own children. The lead does not start child sessions of its own. When a vord update changes the lead instructions, a continued lead receives the new instructions once on resume.

Your own instructions for project leads

Under Settings → Agents → Rules & Workflow, with global scope, the Session role additions card has a Project leads switch and text field. When it is on and not empty, vord adds that text after the built-in project lead role, for every agent that can run as a project lead. Project-specific instructions for project leads belong in the project’s CLAUDE.md or AGENTS.md. See Rules files.

Status rounds and work state

The project lead has a work state you can see and change in its sidebar row or at the top of its column: Working, Waiting for you, or Done. The lead can also set its own state, for example to Done when its work is finished.

vord sets the state to Working when the lead starts a session for you or receives an assignment, including from a scheduled job. When no led sessions remain active and no board question is open, the state becomes Done. If only board questions for you remain, it becomes Waiting for you and changes to Done when you answer them. A question, permission prompt, or plan approval in the lead’s own chat also makes its displayed work state Waiting for you immediately; after you answer the box, the saved work state appears again. Done stays until the lead receives another assignment.

While the lead is Working and has at least one active led session, vord wakes it for a status round at most at the configured interval (30 minutes by default), when the lead is otherwise idle — and only when a led session needs attention: it is idle or has an open box without a report since becoming idle, it is not working but still holds claims, or it has stalled. Without anything needing attention, no round comes; the next check waits a full interval. The round lists only the sessions needing attention (at most six) with status, idle time, open box, last report, held claims, and running children, and counts the rest as numbers. It marks sessions that have been idle beyond the configured threshold without a report since becoming idle, and sessions that are not working but still hold claims. A session that has reported since becoming idle and has stayed idle beyond that same threshold is listed too, so the lead can stop it or send the next step.

Two additional reasons trigger an immediate status round, once per idle phase: children done, parent idle when all children have stopped and the session has been idle for at least five minutes (up to three child ids are shown), and waiting on you when the session’s last report asks the lead a question or decision and it has been idle for at least five minutes. A session with a working child or its own build-queue entry does not count as stalled. The Children column shows working / done.

The lead checks what each listed session is waiting for and whether that event is likely to happen, then wakes it with a concrete next step. It never answers boxes intended for you; it reports them to you instead. Led sessions are instructed not to wait silently on something outside their control and to tell the lead what they are waiting for.

Overdue items on the board also wake the lead. When a commitment (V-n) or to-do (T-n) from this Mac passes its due date and is still open, vord sends the lead a short notice once for that item and due date, whatever its work state — also while it is Done or Waiting for you. The notice lists at most five items and points to lead_board_list for the rest. A busy lead gets it as soon as it is idle. Rescheduling an item gives it a new due date, so it is reported again if that date passes too. The notice does not depend on the Status rounds switch, and vord remembers what it reported across restarts. Waiting “Planned start” commitments and items without an owner are not part of it.

Separately, if a led session has been idle beyond the stall threshold (20 minutes by default), has not reported since becoming idle, and has no open box, vord wakes the lead immediately, once for that idle period. A report file modified at or after idle began counts as a report. A scheduled child is treated as working, so a session waiting on one is not marked stalled; scheduled_child_count shows those waiting starts in session rows. An open box or a usage limit never counts as a stall. Neither status rounds nor stall alerts create a notification; both go only to the lead’s session.

In Settings → Helpers & Workflows → Project lead, you can turn Status rounds on or off and set their interval from 5 to 240 minutes (default 30). Wake on stalled sessions can also be turned on or off, with a threshold from 5 to 120 minutes (default 20). These settings apply to all project leads.

Notifications

A project lead is an orchestrator: it ends its turn whenever it hands work off and waits for the answer. Its turn end is not a notification — no banner, no sound, no phone push, no inbox entry.

What does reach you:

A session the lead started reports its finish to the lead, not to you. Turn on Also notify when sessions started by the project lead finish (off by default) and such a session notifies you directly when it finishes, instead of only reaching the lead.
Questions, permission requests, and plan approvals from the lead or from a session it leads always reach you, because only you can answer them.
A stopped project lead is loud. If the lead stops and cannot continue on its own, you are notified — nobody else works on that project afterwards. The notice includes the cause when an error line is available in the terminal. A lead that vord restarted on its own stays quiet: that system notice lands only in the notification inbox, unless you turn on Show system notices as banners.

The rules that decide what reaches you are on Notifications & the Menu Bar.

Working alongside it

Nothing is routed through the lead. You start, message, and steer any session directly at any time, project lead or not. If you want a session out of its coordination, choose Release from project lead in the session’s context menu — it keeps running, just unmanaged. Whether the lead may still stop such a session depends on Project lead may stop all sessions: with it on (the default) the lead may stop it with a reason, never while it waits for you. A session the lead started itself stays stoppable for it either way — also after a release and a later takeover, and for sessions from older vord versions. Sessions the lead coordinates carry a small icon labelled “Managed by the project lead”.

Scheduling jobs

A project lead may create and update scheduled jobs with jobs_create and jobs_update. The same model rule as lead_start_session applies: the lead must use an orchestrator model. If no model is specified, vord uses the agent’s orchestrator default; with automatic model selection, a fixed model is allowed for a project-lead job. A small model is rejected.

When the job runs, vord starts the session through whichever project lead is leading the project at that moment. It does not use a session saved when the job was created. The new session belongs to that project lead, appears there, can be reached with lead_list_sessions and lead_send_prompt, and reports back to the lead. If no project lead exists at run time, the run fails with no_project_lead and you are notified. See Scheduled Jobs for the general job behavior and run states.

Planning sessions

Pass start to lead_start_session to plan a session instead of starting it now. when is now, next_slot, after_session, after_ticket, or at; ref carries the session ID, the ticket, or the ISO time for the last three, and priority is high, normal, or low (default normal). A time must lie at most 24 hours ahead. vord starts the plan once its condition holds and a session slot is free, then reports the start to you. Your waiting plans appear in lead_list_sessions as plan lines (at most ten, the rest as a count). Cancel a plan with lead_stop_session and the plan ID. A project-lead job that fires while your session limit is reached is queued as a next_slot plan instead of failing.

Every plan also appears on the project board as a commitment (V-n) titled “Planned start: …”, with the start condition in its waiting line. When the session starts, the commitment is marked done and names the running session, so the agenda never shows a started plan as overdue; when the session ends, the result the lead recorded replaces that note. Cancelling the plan drops its commitment. While a plan still waits, its due date moves along: once it passes, vord pushes it 24 hours ahead and records the waiting condition as the reason in the commitment’s history. A plan that could not start keeps its commitment open without the waiting line, so it turns overdue in the agenda and the lead gets an overdue notice. An open commitment whose plan no longer exists on this Mac is dropped with that reason. Dropping the commitment cancels the plan without starting it. The agenda lists plan commitments like any other commitment, but never acts on them — no session is woken or started from the agenda for a plan. A plan that waits longer than 24 hours is named once in the status round.

Required skills

Some tasks always need the same skill — for example your SEO workflow. The lead binds task labels to required skills and enforces them at start. Record a binding with lead_memory (action=record, kind=skill_binding, task with up to 60 characters and skills with 1–3 slugs); recording the same task again replaces the old binding, and action=search with kind=skill_binding lists the current bindings.

Every hosted session in that project — parents, children, and grandchildren, every agent kind — sees the current bindings once at start and again after compaction, as one line in the operating manual next to the skill names (Project skill bindings: SEO → machbar-skill). The line is not repeated each turn. If it is truncated, the rest is behind lead_memory search kind=skill_binding.

Pass skills (up to 3 slugs) or task (a bound label) to lead_start_session. vord appends one line per skill to the assignment (“Required skills: use skill …; read it before you start”). When a skill is neither installed nor in vord Brain, the start fails with skill_missing — unless allow_missing_skills is true, which starts without it. Missing skills found in vord Brain are installed globally to ~/.claude/skills/<slug>, where every Claude account finds them.

Ending it

Choose End project lead… in the project menu (or in the column’s menu) and confirm: “The session is archived; sessions it leads keep running.” Ending the lead never stops your work — the sessions simply lose their coordinator, and you can start a new project lead later.

vord resumes every project lead when it starts. If a lead never started a conversation — for example because startup failed before the first question — vord starts it fresh with the same settings and leaves a notice in the notification inbox. Project leads are never archived or parked automatically. If a lead stops, the notification and column notice show the cause when an error line is available in the terminal. Resume appears only when the conversation can continue; otherwise, Restart starts a new lead with the same settings. After a start failure, choose Change project lead… to switch to another agent or account. Assigned sessions stay assigned.

On the iPhone

When the connected Mac reports project-lead support, the project lead has its own accent-framed card with a clipboard icon, titled Project lead · project, never a regular session row or tile. The card shows its status and wait reason, any open question, and open board items. Tap it to open the lead’s chat; its menu (…) offers Open board and End project lead…. In Session Detail, the header reads Project lead · project and has a Board button. Banners and notifications identify it with the same Project lead · project title. A detail view for a session it leads offers Release from project lead. In the project header menu, Start project lead with an agent choice appears when the project has no lead. In Start project lead, pick up to three Start templates when the connected Mac offers them; older Macs show no template section. An older Mac without project-lead support shows the lead as a regular session.

The card also shows the lead’s work state — Working, Waiting for you, or Done — when the Mac supports it. Choose Work state in the card menu to change it. Older Macs without projectLeadWorkState show no work state and no switcher.

If the lead reaches its account limit, the card shows the limit as its status and wait reason. You can switch the lead to another connected account by clicking that account.

Under By project, the card sits directly below its project heading. Under By activity and in the Cockpit, a Project leads block at the top stacks one visible card for each project. Sessions led by a project lead carry a clipboard badge labelled Led by the project lead, including on Cockpit tiles. The chat uses the same composer as other sessions, so you can attach images and, with a current Mac, documents from Files there too (see Attaching documents from Files).

The Sessions list follows the Mac sidebar’s project order and groups. A group heading shows a folder icon and its path, such as Clients › Acme, above its projects. Within a project, sessions are sorted by status and then by last activity, as on the Mac. Search Search projects and sessions keeps the entire project visible, including its project-lead card, when the project name matches; otherwise it filters sessions by title. The project lead is found through its project name. The Cockpit has no search. An older Mac without project-structure support supplies alphabetical project order without groups.

On the project board, Hand over to… lists the project lead first with a clipboard icon, followed by eligible sessions alphabetically; child sessions are indented under their parent. Ended sessions and sessions shared by someone else are not handover targets.

On the iPhone, the All projects tab pages through every project lead chat — see All projects.

Limits

One project lead per project at a time — start is refused while one is already running. Project lead may stop all sessions is on by default: the lead may stop every top-level session of its project, not only the ones it started itself — never another project lead, a child session, or an archived session, except a finished session still assigned to and started by that lead: repeating lead_stop_session succeeds idempotently, leaves it archived, and stops nothing. It never stops a session that waits for you, and always needs a reason for a session it did not start itself, which is written to the event log with the stop. Job sessions (automation runs) of its project it may stop regardless of this setting. Turn the setting off globally under Settings → Agents → Helpers & Workflows and the lead may only stop the sessions it started itself, plus those job sessions. Each project can override the setting in its project menu (Follow setting, On, Off; Mac only).

Sessions the lead starts run on orchestrator models (the same orchestrator list as in Settings). The lead can inspect those models and every account’s usage before it starts work. If it omits model and account, vord uses the agent’s orchestrator default on an account with headroom. It can select another orchestrator model or ready account when your preference or the account usage calls for it. If the agent has no orchestrator model, nothing starts and the lead is told which agents have one. How many of those sessions can run at once is the child-session limit in Settings.

Project leads are exempt from your own usage limit and from the usage brake: reaching an own limit does not hold them, though their usage still counts toward the account’s windows, so other sessions on the same account can be braked earlier. At the hard provider limit, the lead stays on its account. vord shows the limit and reset time, then waits. Auto-Continue is off by default; when enabled, it continues after the reported reset time. You can switch the lead to another connected account by clicking that account. See Usage and Quotas.

Claude Code compacts a project lead that has been idle for about 54 minutes, before its one-hour prompt cache expires (Claude Code 2.1.299 or later, conversations from 200K tokens). vord leaves this on. Other agents compact when their context window fills.

Project leads compact at 200,000 tokens by default, and this is adjustable under Settings → Agents → Models (Project leads compact at).