Agent Threads documentation

Project and Portfolio Orchestrators

The bundled thread-orchestrator skill — a supervisory agent that tracks peer threads and proposes replies for human approval.

The thread-orchestrator bundled skill supports two roles: one Project Orchestrator per Project and one Portfolio Orchestrator for unassigned work and Project-level rollups. Open the portfolio role with Open Portfolio Orchestrator; create/open a Project role from its Settings row. Project activity also creates its orchestrator automatically on the first completed turn unless that Project’s orchestrator was intentionally archived.

What it does

Each orchestrator uses the thread-coordination tools inside its scope. Project Orchestrators own their Project notes and proposals. Portfolio cross-Project raw access is explicit per call, and elevation does not transfer Project-note ownership.

Goal intake before coordination. For each new thread, the orchestrator first looks for an explicit /goal, the initiating request, and a concrete completion condition. Clear requests are recorded as user-stated and proceed without another interview. If the intended outcome or definition of done is ambiguous, the orchestrator records that it is awaiting direction and asks one focused question in the orchestrator conversation before proposing execution, inspection, or verification. A later answer can make the goal user-confirmed; an inferred goal may guide explicit work already underway but cannot expand its scope.

Structured notes. For each thread it’s watching, the orchestrator maintains a goal contract, current status, confidence, disposition, and the exact updatedAt value from its last review. These are shown in a collapsible “Manager Notes” panel in the Chat view, but are never injected into that thread’s own session context, so they don’t pollute the conversation the orchestrator is watching. A Project’s context prompt can provide the parent goal contract with a desired outcome, current priority, definition of done, constraints, non-goals, and risk tolerance.

Pure manager boundary & 5-channel action contract. Referenced Portfolio and Project orchestrators receive a pinned system-prompt Orchestrator Charter (surviving context compaction across Claude, Codex, OpenCode, and Antigravity) and a non-inherited role tool lockout: Bash, Edit, Write, Agent, AskUserQuestion, and ScheduleWakeup are disabled on the orchestrator itself without restricting worker threads spawned via threads_create. Orchestrators coordinate through five explicit channels: threads_create (one bounded task/PR per board card), threads_send_message (tactical handoffs strictly inside an already-authorized campaign goal), threads_set_proposed_reply (staging replies for questions waiting on you), threads_post_decision (genuine forks and all irreversible gates such as merges, releases, deploys, or migrations), and threads_set_notes (Manager notes v2 with Strategy:).

Two-tier memory & 30+ thread scale. Per-thread state lives in Manager notes v2 on each card (read in O(1) via threads_get on event pings and scanned via threads_list({ view: "triage" }) with a 6-thread deep-review cap on heartbeats). Cross-thread campaign state (multi-PR waves, merge ordering, shared blockers) lives in Products/<Project>/orchestrator-ledger.md (read and written via threads_get_ledger and threads_set_ledger) so you can run Reset orchestrator session (fresh context) on an idle orchestrator at any time without losing state or replaying pre-reset transcript history.

Before proposing a reply, the orchestrator requires new evidence, a clear connection to the desired outcome, useful decision value, and a stopping condition. Verification is limited to one additional orchestrator-requested pass for a substantive implementation state unless a new failure, external change, user direction, or concrete risk justifies another. Concluded or unchanged work stays quiet.

Decisions. When the orchestrator needs a directional choice from you before acting, it calls threads_post_decision to post a decision card (2–4 options plus an optional free-text Other answer, labeled with the posting orchestrator’s title) shown inline in both the thread’s Chat (conversation) view and on its Agent Board card. Clicking Send answer routes your choice back to the posting orchestrator thread as a user message — never into the watched thread’s own context. If a question becomes moot, the orchestrator withdraws it with threads_clear_decision; manually sending a message directly to that thread yourself also dismisses any pending decision cards on it (while automated or agent sends such as threads_send_message, wakeups, and heartbeats leave pending decisions intact).

Identifying the orchestrator thread

Portfolio and Project orchestrators carry distinct bot-badge classes and tooltips in Agents List rows, Agent Board cards, and the thread switcher. Closing, archiving, reassigning, or automatically archiving a referenced orchestrator is protected; explicit archive still requires confirmation. That includes the right-click Archive thread action in the Agents List and on Agent Board cards — archiving an orchestrator there asks first, and it still asks only once when the orchestrator is swept up in a bulk archive.

Disabling and re-enabling a Project Orchestrator

Intentionally archiving a Project Orchestrator disables automatic orchestration for that Project. The plugin removes its hourly heartbeat, discards queued or in-flight thread-completion wakeups, and does not recreate or message a replacement when another Project thread finishes.

This disabled state is persisted in data.json, so it remains in effect after an Obsidian restart or plugin reload, including when the settings file was synced from another device. Deliberately choosing Create/Open for that Project re-enables orchestration and creates or reuses its orchestrator. This lifecycle applies to Project Orchestrators; the Portfolio Orchestrator remains managed separately.

Wake-up cadence

The orchestrator doesn’t need to be manually re-triggered. It runs on two wake-up patterns with different scopes:

  • An hourly heartbeat reconciles activity across watched threads, including changes an event may have missed. Threads whose updatedAt cursor is unchanged are not reread or rewritten.
  • Thread-completion wakeups include the named threads and their exact updatedAt values. They review only those targets, so one completion does not trigger an unrelated Project-wide scan.

Both are implemented with ScheduleWakeup, the same session-tool primitive available to any thread — see Session tools.

When to use it

The thread-orchestrator is most useful once you’re routinely running more threads in parallel than you can watch directly — a handful of agents working on different parts of a project, or a fan-out where one task spawned several sub-tasks across peer threads. Instead of clicking through each tab to check status, you check the orchestrator thread and its proposed replies.