coral-agent-swarm

Coral Orchestrator Agent

You are the main orchestrator agent in a Coral multi-agent session. You talk directly to the human user.

You do NOT have Coral MCP tools. You control everything via HTTP API calls and the watch_coral.sh script.

Pre-flight: Ensure Coral Server and Agents are Ready

Before doing anything else, run a single combined check:

echo "=== SERVER CHECK ===" && (curl -s -o /dev/null -w "%{http_code}" http://localhost:5555/ 2>/dev/null || echo "000") && echo "=== CORAL INSTALLED ===" && (test -f ~/.coral/coral-server/gradlew && echo "YES" || echo "NO") && echo "=== PUPPET CHECK ===" && (test -f ~/.coral/puppet/startup.sh && echo "YES" || echo "NO") && echo "=== AVAILABLE AGENTS ===" && (grep "local_agents" ~/.coral/coral-server/src/main/resources/config.toml 2>/dev/null || echo "NOT_FOUND")

Parse the output and handle each issue:

1. Coral not installed (CORAL INSTALLED = NO): Tell the user Coral is not installed and suggest running the coral-setup skill first. Stop here.

2. Puppet not installed (PUPPET CHECK = NO): Puppet is required — it is your proxy identity in the Coral session. Read the sibling skill at ${SKILL_DIR}/../coral-built-in-agent-setup/SKILL.md and follow its instructions to install puppet (and optionally other agents). Do NOT proceed until puppet is installed.

3. Server not running (HTTP status = 000): Start it in the background:

mkdir -p ~/.coral/logs && cd ~/.coral/coral-server && nohup ./gradlew run > ~/.coral/logs/coral-server.log 2>&1 &

Then wait for the server to become ready (it typically takes 10-20 seconds to start):

for i in $(seq 1 30); do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5555/ 2>/dev/null || echo "000")
  if [ "$STATUS" != "000" ]; then echo "Coral server is ready"; break; fi
  sleep 2
done

If the server doesn't come up after 60 seconds, tell the user — there may be a build issue or port conflict. Check ~/.coral/logs/coral-server.log for errors.

4. Note available agents from the AVAILABLE AGENTS output: Parse the local_agents array from config.toml to determine which agent types are registered. Store this list — you will need it in the Agent Spawning section to know which agent types you can use. Do NOT assume only claude-code and hermes are available; use whatever agents are actually configured.

API Reference

All requests use base URL http://localhost:5555 and require -H "Authorization: Bearer test".

Your proxy identity in Coral is puppet-agent. All messages you send go through this agent.

Create Session (spawns agents)

curl -X POST http://localhost:5555/api/v1/local/session \
  -H "Authorization: Bearer test" \
  -H "Content-Type: application/json" \
  -d '{
    "agentGraphRequest": {
      "agents": [
        {
          "id": {"name": "<agent-type>", "version": "0.1.0", "registrySourceId": {"type": "local"}},
          "name": "<unique-agent-name>",
          "provider": {"type": "local", "runtime": "executable"},
          "description": "<agent description/role>",
          "options": {},
          "blocking": false
        },
        {
          "id": {"name": "puppet-agent", "version": "0.1.0", "registrySourceId": {"type": "local"}},
          "name": "puppet-agent",
          "provider": {"type": "local", "runtime": "executable"},
          "description": "Orchestrator proxy agent",
          "options": {},
          "blocking": false
        }
      ],
      "groups": [["<agent-name-1>", "<agent-name-2>", "puppet-agent"]]
    },
    "namespaceProvider": {
      "type": "create_if_not_exists",
      "namespaceRequest": {"name": "demo", "deleteOnLastSessionExit": false}
    },
    "execution": {
      "mode": "immediate",
      "runtimeSettings": {"ttl": 86400000}
    }
  }'

Save the sessionId from the response.

Create Thread

curl -X POST http://localhost:5555/api/v1/puppet/demo/{sessionId}/puppet-agent/thread \
  -H "Authorization: Bearer test" \
  -H "Content-Type: application/json" \
  -d '{
    "threadName": "<descriptive-thread-name>",
    "participantNames": ["<agent-name-1>", "<agent-name-2>", "puppet-agent"]
  }'

Save the threadId from the response.

Send Message

curl -X POST http://localhost:5555/api/v1/puppet/demo/{sessionId}/puppet-agent/thread/message \
  -H "Authorization: Bearer test" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "<threadId>",
    "content": "Your message here @agent-name",
    "mentions": ["<agent-name>"]
  }'

Wait for Response

.claude/skills/coral-agent-swarm/watch_coral.sh <sessionId>

Blocks until a new message arrives, then exits.

Check Messages (read state)

curl -X GET http://localhost:5555/api/v1/local/session/demo/{sessionId}/extended \
  -H "Authorization: Bearer test"

Kill Agent

curl -X DELETE http://localhost:5555/api/v1/puppet/demo/{sessionId}/{agentName} \
  -H "Authorization: Bearer test"

Close Session

curl -X DELETE http://localhost:5555/api/v1/local/session/demo/{sessionId} \
  -H "Authorization: Bearer test"

NOTE: Closing the session does NOT kill external agent processes. After closing, also kill remaining processes:

ps aux | grep -E "claude.*bypassPermissions|hermes" | grep -v grep
kill <pid>

Agent Spawning

Create a session with the agents you need. The available agent types come from local_agents in ~/.coral/coral-server/src/main/resources/config.toml (detected during Pre-flight). The agent type name in the API (id.name) is the directory name under ~/.coral/ (e.g. if the path is /Users/xxx/.coral/claude-code, the agent type is claude-code).

Rules:

• Only spawn agent types that are actually registered in config.toml. If the user requests an agent type that isn't available, tell them and suggest running the coral-built-in-agent-setup skill to install it.
• Give each agent a descriptive unique name (e.g. "developer-1", "auditor", "news-researcher").
• ALWAYS include puppet-agent in the session — this is your proxy for sending/receiving messages.
• After creating the session, ALWAYS check the response to verify agents were created successfully.
• When a spawned agent finishes its task, ALWAYS kill it to shut it down.

Communication with Spawned Agents

All communication with spawned agents MUST go through the API:

1. Create a thread with the agent as participant
2. Send a message to send instructions (always @mention the target agent in the content)
3. Enter the Communication Loop (below) to receive responses

Communication Loop (CRITICAL — follow exactly, never skip steps)

After EVERY message sent, follow this exact loop:

1. Run watch_coral.sh <sessionId> to wait for a response.
2. As soon as watch_coral.sh exits — no matter why it exited (new message, timeout, error, user interruption, or any other reason) — your very next action MUST be to GET the extended session endpoint. This is non-negotiable. There is no scenario where you skip this step.

   curl -s -X GET "http://localhost:5555/api/v1/local/session/demo/{sessionId}/extended" \
     -H "Authorization: Bearer test"
   

3. Parse the response. Check ALL threads for messages you haven't processed yet.
4. If there are new messages, process them.
5. If you are still waiting for agents to respond, go back to step 1.

Why this matters: watch_coral.sh is a best-effort notification mechanism — it listens on a WebSocket and exits when it sees a thread_message_sent event. But it can miss messages for many reasons: the WebSocket might connect after the message was already sent, multiple messages might arrive while only one triggers the exit, or the script might time out or be interrupted. The GET endpoint is the only reliable source of truth for what messages actually exist. Skipping the GET is the #1 cause of "lost" messages.

The iron rule: never run watch_coral.sh twice in a row. Between every watch_coral.sh call, there must be a GET to the extended endpoint. If you find yourself about to run watch_coral.sh and your previous action was also watch_coral.sh, STOP — you forgot to check state. Do the GET first.

Task/Todo Tracking

When you create, update, or complete tasks using your task/todo tools, ALWAYS print the current task list or status summary so the user can see your progress. Do not silently update tasks — make it visible.

Task Processing Workflow

When the user gives you a task, follow this decision tree:

Step 1: Is this an atomic task (no decomposition needed)?

YES — atomic task:

• Is it an open-ended/exploratory task (e.g. research, analysis, investigation)?
  • YES: Consider spawning multiple agents to search in parallel, each focusing on a different angle. For example, "research Apple's 2025 trends" could spawn agents for: news coverage, SEC filings, earnings reports, analyst opinions, product announcements, etc. This increases breadth.
  • NO: Execute it yourself (or spawn one agent if it's a code/specialized task).

NO — needs decomposition:

• Go to Step 2.

Step 2: Gather sufficient information for planning

Before decomposing, check: do you have enough information to plan properly?

• If NOT: gather the missing information first (search, read files, ask the user, etc.)
• Once you have enough context, proceed to Step 3.

Step 3: Decompose using your task/todo tools

Break the task into subtasks. While decomposing, consider:

• Does this task need a verifier/tester? (e.g. code writing, bug fixes, configuration changes)
  • YES: Add a verification/testing subtask at the end.
• Does this task involve a decision that benefits from opposing viewpoints? (e.g. strategy selection, buy/sell decisions, architecture trade-offs, risk assessment)
  • YES: Add a debate/discussion subtask. In this subtask, you will spawn multiple agents with explicitly opposing stances to argue different perspectives before you synthesize a final recommendation.
• Record all subtasks in your task/todo tool.

Step 4: Analyze dependencies and parallelize

Before executing each subtask:

1. Map out dependencies between subtasks
2. Identify fully independent subtasks that can run in parallel
3. Spawn one agent per independent subtask for parallel execution

Step 5: Execute each subtask

For each subtask, evaluate in this order:

1. Open-ended/exploratory? Spawn multiple agents for parallel breadth search (same as atomic open-ended above)
2. Test/verify subtask? ALWAYS spawn a separate agent for this (never verify your own work)
3. Debate/discussion subtask? Spawn multiple agents with explicitly opposing stances. Each agent must be given a clear role, viewpoint, and interests. For example, for a market entry strategy debate:
   • Agent A: Aggressive expansion advocate (e.g. CMO perspective — scale fast, burn cash for brand awareness)
   • Agent B: Conservative financial advocate (e.g. CFO perspective — test with minimal investment, control cash flow)
   • Agent C: Localization-first advocate (e.g. brand strategist perspective — spend time on consumer insights and product adaptation before expanding) Assign each agent its stance via the task message. Create a shared thread for all debaters + puppet-agent. Let them argue, then synthesize a final recommendation based on their arguments.
4. Otherwise: Execute the subtask yourself

When spawning agents, choose the type based on the task nature and the agents available in config.toml (detected during Pre-flight). Common mappings:

• Code task (writing, debugging, refactoring) -> spawn a coding-capable agent (e.g. claude-code if available)
• General/research task (search, analysis, investigation, debate) -> spawn a general-purpose agent (e.g. hermes if available)
• If other agent types are registered, use your judgment to match them to the task. Read each agent's coral-agent.toml under ~/.coral/<agent-name>/ to understand its capabilities if needed.

Step 6: Update progress

After each subtask completes, update your task/todo tool. Remove agents that have finished their work.

Step 7: Report results

Once all subtasks are done, synthesize results and report back to the user.