Orchestrator & Claude Code

Worker agents and Claude Code sessions for autonomous, parallel task execution.

Overview

The orchestrator lets Edward spawn lightweight worker agents that run autonomously within his process. Each worker is a mini-Edward with full tool access, memory retrieval, and conversation persistence. For coding tasks, Edward can also delegate to Claude Code sessions via the claude-agent-sdk.

Worker Agents

Workers are spawned via chat_with_memory() — the same function used for normal conversations. This means workers have:

Full access to all enabled tools (messaging, search, code execution, etc.)
Memory retrieval and extraction (they can remember and recall)
Their own conversation thread, visible in the sidebar
State persistence via LangGraph checkpoints

Worker conversations are tagged with source: "orchestrator_worker" so they appear distinctly in the sidebar.

Context Modes

When spawning a worker, you can control how much context it receives:

Mode	Description
`full`	Worker gets the complete parent conversation as context
`scoped`	Worker gets only the task description and relevant snippets
`none`	Worker starts with a blank slate — task description only

Claude Code Sessions

For coding tasks that require file editing, test running, and iterative development, Edward delegates to Claude Code via the claude-agent-sdk. Claude Code sessions:

Run as separate processes with their own context
Can read, write, and execute code in the repository
Stream events back to the frontend in real-time
Are tracked in the claude_code_sessions database table

The frontend renders Claude Code session events inline in the chat UI via the CCSessionBlock component.

Concurrency

Workers and Claude Code sessions use separate concurrency semaphores to prevent either from starving the other:

Pool	Default Limit	Description
Workers	5	Internal mini-Edward agents
Claude Code	2	External Claude Code sessions

Task Lifecycle

pending → running → completed
                  → failed
                  → cancelled

Tasks start as pending and move to running when picked up by a worker or Claude Code session. They resolve to completed, failed, or cancelled. Failed tasks include error details. Cancelled tasks are stopped gracefully when possible.

Configuration

Orchestrator settings are managed via PATCH /api/orchestrator/config or the settings UI:

Field	Default	Description
`enabled`	`true`	Master switch for the orchestrator
`max_concurrent_workers`	`5`	Maximum parallel worker agents
`max_concurrent_cc`	`2`	Maximum parallel Claude Code sessions
`auto_recover`	`true`	Recover crashed tasks on startup