Coordinator
The main control agent. The user's primary point of contact; routes requests to the appropriate specialized agent, manages sessions and memory, and surfaces results.
Status
Implemented. The Coordinator is the always-on entry point for the user. It is the only agent the user interacts with directly in the natural-language flow.
Role
The Coordinator is responsible for:
- Receiving the user's natural-language request.
- Understanding the intent (research, coding, media, web, mixed).
- Routing the request to the appropriate specialized agent (Research Worker, Coding Assistant, Media Agent, Web Agent).
- Managing the session (state, memory, context).
- Surfacing the result back to the user.
- Asking clarifying questions when the intent is ambiguous.
The Coordinator does not execute tasks directly. It is a router, state manager, and user interface — not an executor.
Architecture
The Coordinator runs in the main gateway process. It has the following components:
| Component | Purpose |
|---|---|
| Gateway | The HTTP/gRPC interface that receives user requests. |
| Request Parser | Tokenize and parse the request. |
| Intent Resolver | Map the request to one or more agents. |
| Router | Dispatch the request to the selected agent(s). |
| Memory Layer | Read/write the long-term and daily memory. |
| Session Store | Maintain the session state. |
| Skill Loader | Activate the relevant skills. |
| Result Aggregator | Combine results from multiple agents when needed. |
Ports and processes
The Coordinator runs in the main gateway process. The ports are:
| Port | Process | Purpose |
|---|---|---|
| 18789 | Main gateway | The Coordinator's HTTP API. |
| 18790 | Scout gateway | The Research Worker's gateway. |
| 18800 | Browser CDP | The browser automation's CDP port. |
The Coordinator can reach the Research Worker through its
gateway on 127.0.0.1:18790. The browser automation is
reached through the browser tool on the CDP port.
The gateway is supervised by launchd on macOS or
systemd on Linux. Restart command (macOS):
Configuration
The Coordinator is configured by the framework's main configuration file. The relevant fields:
| Field | Type | Default | Purpose |
|---|---|---|---|
coordinator.port | integer | 18789 | The gateway port. |
coordinator.max_concurrent | integer | 1 | Max concurrent user requests. |
coordinator.session_timeout_s | integer | 3600 | Idle session timeout. |
coordinator.memory_enabled | boolean | true | Whether the memory layer is active. |
coordinator.skills_enabled | boolean | true | Whether the skill loader is active. |
Configuration changes require explicit user authorization.
Routing
The Coordinator's router maps a request to one or more agents. The routing rules are:
| Intent keyword | Agent | Notes |
|---|---|---|
| "research", "find", "search" | Research Worker | "research X for Y" → Research Worker. |
| "code", "implement", "build" | Coding Assistant | "implement X in repo Y" → Coding Assistant. |
| "play", "stream", "cast" | Media Agent | "play X on TV" → Media Agent. |
| "browse", "open", "navigate" | Web Agent | "go to URL" → Web Agent. |
| Mixed intents | Multi-agent | Split by intent; aggregate results. |
When the intent is ambiguous, the Coordinator asks a clarifying question. The question is phrased to be informative without being verbose.
The router is implemented by the IntentResolver and the
Router components. The router can be configured with
custom rules; the default rules cover the common cases.
Multi-agent requests
Some requests span multiple agents. For example, "find a hotel in Barcelona for September and add it to my calendar" is a research + calendar request. The Coordinator:
- Splits the request by intent.
- Routes each part to the appropriate agent.
- Aggregates the results.
- Surfaces the combined result to the user.
The aggregation is naive (concatenation with separators) unless a more sophisticated aggregation rule is configured. The Coordinator is not expected to reason across agents; it delegates that to the result aggregator.
Memory
The Coordinator owns the long-term memory layer. The memory layer is documented in Memory and Context. The summary:
MEMORY.mdis the long-term, curated memory. It is loaded in the main session only.memory/YYYY-MM-DD.mdis the daily log. One file per day.- Skill artifacts (SKILL.md, TOOL.md) are loaded by the skill loader when the skill is activated.
The Coordinator decides what to write to memory and when. The default policy is: write significant decisions, write lessons learned, do not write secrets. The policy is configurable.
Sessions
The Coordinator maintains the session state. A session is a continuous conversation between the user and the Coordinator. The session has:
- A unique
session_id. - A start time and last activity time.
- A pointer to the current memory context.
- A list of in-flight agent requests.
Sessions are stored in the session store. The default backend is the local filesystem; the Coordinator can be configured to use a database.
The session timeout is configurable (default 1 hour of idle time). After the timeout, the session is archived.
Skills
The Coordinator uses the skill loader to activate
relevant skills. A skill is a markdown file
(SKILL.md) that describes a capability and its
workflow. The skill loader is in
{workspace-root}/.agents/skills/.
The Coordinator activates a skill when:
- The request matches the skill's trigger phrases.
- The skill is in the user's allowlist.
The skill loader returns the skill's instructions, which the Coordinator follows. The Coordinator does not modify the skill's instructions; it executes them as written.
Request lifecycle
A request flows through the Coordinator as follows:
The Coordinator logs the request and the result in the
session log. The session log is in
{workspace-root}/sessions/<session_id>/log.jsonl.
User interface
The Coordinator exposes a small CLI for ad-hoc operations. The CLI is the framework's main entry point. The documented commands are:
| Command | Purpose |
|---|---|
{cli} session list | List active sessions. |
{cli} session resume {id} | Resume a paused session. |
{cli} session end {id} | End a session. |
{cli} memory search "{query}" | Search the memory layer. |
{cli} memory write "{content}" | Append to today's daily log. |
{cli} skill list | List available skills. |
{cli} skill activate {name} | Activate a skill. |
The full cheatsheet is in Cheatsheet → Coordinator.
Failure modes
| Failure | Coordinator response |
|---|---|
| The gateway is unreachable | Return a "service unavailable" error to the user. |
| The Research Worker is unreachable | Surface the error; offer to retry later. |
| The Coding Assistant is killed by timeout | Apply the Coding Assistant killed by timeout procedure. |
| A request is ambiguous | Ask a clarifying question. |
| The session has expired | Offer to resume the session. |
| The memory layer is full | Apply the retention policy. |
| The skill loader fails | Log the error; continue without the skill. |
The full failure catalog is in Failure Catalog.
Future work
- Multi-user sessions. Allow multiple users to share a Coordinator (with per-user sessions).
- Voice interface. Add a voice-based interface.
- Proactive suggestions. Surface relevant information to the user based on context.
- Cross-session memory. Share memory across sessions in a controlled way.