Orchestrator

The Intelligent Manager is the heart of every Agenties project. It is a persistent Claude process that never writes code itself — its only job is to read the current state of the project, decide what needs to happen, and delegate to the right specialist via spawn_agent. Understanding the orchestrator is key to getting the most out of Agenties.

Session lifecycle

The orchestrator does not run as a daemon. It is a turn-based process — it wakes up, does its thinking, spawns agents, then exits. The next time it needs to run, it resumes using the same Claude session ID, which gives it access to its conversation history.

What triggers a turn

User messageYou type a message in the Chat tab. The orchestrator starts immediately.

task-done mailbox eventA sub-agent posts a task-done message. The orchestrator auto-wakes to process the result and decide what to do next.

HeartbeatA scheduled cron heartbeat fires. The orchestrator starts a proactive turn without any user prompt.

Routine triggerAn API call, GitHub webhook, or schedule fires a routine. The orchestrator receives the issue context.

What happens at turn start

At the beginning of every turn, before doing anything else, the orchestrator reads:

Turn start context

1. Shared state         (.agenties/shared/state.json)
   — current phase, active objective, open work items, recent decisions

2. Mailbox              (unread messages via read_messages MCP tool)
   — task-done results, review outcomes, questions from sub-agents

3. Open issues          (list_issues MCP tool, status=open|in_progress)
   — backlog items waiting to be delegated

4. Vault context        (CONTEXT.md, decisions.md via read_vault_note)
   — long-term architectural context and project description

This context loading is automatic — the orchestrator's system prompt instructs it to always start turns this way. You don't need to remind it of the project state.

Delegation via spawn_agent

The orchestrator's primary action is calling spawn_agent. This creates a new Claude Code process with a specific role, task, and context. The orchestrator itself never edits files, runs tests, or executes commands.

spawn_agent example

// Orchestrator calling spawn_agent
spawn_agent({
  memberId: "tm_builder_alex",        // team member to use
  role: "builder",
  task: "Implement the /api/health endpoint as described in issue #12. Write Jest tests.",
  context: "Project uses Express.js + TypeScript. Tests go in src/__tests__/.",
  issueId: "issue_12",               // optional: links agent to an issue
  parentSessionId: "sess_abc123"     // orchestrator's own session for coordination
})

Note:The orchestrator can spawn multiple agents in parallel within a single turn by calling spawn_agent multiple times before any of them complete. The agents run concurrently and report back via the mailbox.

Agent roles the orchestrator delegates to

Role	Purpose	Typical tasks
builder	Implements features and fixes bugs	Write code, run tests, create PRs, fix lint errors
reviewer	Reviews code and provides feedback	Read diffs, check against requirements, post review-result
scout	Researches codebase and external sources	grep for patterns, read docs, summarise findings to vault
coordinator	Manages multi-step sub-tasks (up to 10 turns)	Break down complex tasks, delegate to builders, aggregate results

Autonomous hiring

If you enable Autonomous hiring in Settings → Team, the orchestrator can call hire_team_member to create new team members on the fly when no suitable existing member is found for a task. It picks the model, effort level, and writes role-appropriate base instructions.

Hired members persist in team.json and are available for future tasks. They accumulate XP just like manually created members.

Warning:Autonomous hiring can create many team members quickly if left unchecked. Review your roster in the Team tab regularly and fire members you no longer need to keep the roster clean.

Stopping agents

Clicking Stop in the UI triggers a cancel cascade:

1. The orchestrator receives a cancel signal and stops spawning new agents.

2. All running agents receive a cancel message via the mailbox.

3. Agents check for cancel at the start of each tool call. Leaf agents (no children) stop first.

4. The cancel propagates up the tree using BFS (breadth-first, leaves first) to avoid orphaned processes.

5. Each stopped agent posts a task-cancelled message so the orchestrator knows the final state.

Session resumption

The orchestrator's session ID is stored in .agenties/shared/state.json under the keyorchestratorSessionId. When the orchestrator starts a new turn, it passes this ID to Claude Code via the --resume flag, restoring the full conversation history.

You can start a fresh orchestrator session at any time with /clear in the chat. This discards the old session ID and starts from scratch, but the vault memory and shared state are preserved.

Session compaction

Long-running orchestrator sessions are automatically compacted by Claude Code when the context window approaches its limit. The compacted summary is seamlessly injected at the start of the next turn. The orchestrator also supports manual compaction via /wrapup, which saves a structured summary to the vault before starting a new session.

← PreviousQuickstart Next →Agents & Roles