Multi-Claude orchestration — OpenHuman as master coordinator across 5–10+ simultaneous Claude sessions #4418

Summary

Enable OpenHuman to orchestrate and coordinate multiple Claude (and later Codex/other) instances simultaneously. OpenHuman acts as the master coordinator — the user has a single master chat with OpenHuman and never talks to individual Claude sessions directly. From that master chat, OpenHuman can address any session by name, inspect its state, send it instructions, and aggregate responses across sessions.

Deliverable for this issue: a working POC that spins up multiple Claude instances, lets OpenHuman list them, send a command to one, and return the result to the master chat.

Problem

OpenHuman can already:

• Run Claude via the claude_agent_sdk provider (subprocess, PR feat(inference): add claude_agent_sdk provider (Claude CLI subprocess) #2746)
• Pair with session identities over tiny.place contact edges (PR [codex] Add tiny.place orchestration pairing flow #4400)
• Show pairing status and approval controls in the Brain tab (PR [codex] Add tiny.place orchestration pairing flow #4400)

What does not yet exist:

• A session registry that tracks N named Claude instances with their state, last output, and inbox
• A multi-instance lifecycle manager — spinning up, naming, and tearing down sessions
• Master orchestrator routing — the user says "go to instance 1 and do X" in a single chat; OpenHuman resolves the session, forwards the command, and brings the result back
• Cross-session operations — compare outputs from two sessions, fan out a task across all sessions, aggregate results
• The IPC inbox pattern — one message inbox per session, OpenHuman coordinates by reading/writing inboxes rather than direct coupling

Solution (optional)

Architecture

User
  ↓  (single master chat)
OpenHuman (master orchestrator)
  ├── Session Registry  { id, name, status, last_output, inbox }
  ├── Claude Session 1  ← inbox_1 (claude_agent_sdk subprocess)
  ├── Claude Session 2  ← inbox_2
  ├── Claude Session N  ← inbox_N
  └── tiny.place contact edge per session (PR #4400 pairing)

Session naming: sessions are addressable by ordinal ("instance 1", "session A") and by tiny.place identity (the contact edge from PR #4400).

Scope — POC

1. Session registry (src/openhuman/agent_orchestration/registry.rs)

• SessionRecord { session_id, display_name, status: Idle|Running|Awaiting, last_output, inbox_id, tiny_place_identity: Option<String> }
• SQLite-backed; CRUD + list_active_sessions
• Maps to claude_agent_sdk subprocess instances (or tiny.place paired sessions for remote Claude)

2. Session lifecycle (src/openhuman/agent_orchestration/lifecycle.rs)

• spawn_session(name) → session_id — starts a claude_agent_sdk subprocess, registers it
• terminate_session(session_id) — tears down subprocess, marks Ended
• Support 5–10+ concurrent sessions (process pool or async subprocess management)

3. IPC inbox per session (src/openhuman/agent_orchestration/inbox.rs)

• Lightweight queue per session: send(session_id, message), recv(session_id) → Option<Message>
• OpenHuman writes commands to an inbox; session reads and responds; OpenHuman collects responses
• No direct session-to-session coupling — all routing goes through OpenHuman

4. Master orchestrator routing (src/openhuman/agent_orchestration/router.rs)

• Natural language resolution: "instance 1" → session_id, "session A" → session_id
• Commands: inspect(session_id), send(session_id, instruction), compare([session_id, ...]), broadcast(instruction)
• Results surface in the master chat thread

5. RPC surface (wired via src/core/all.rs)

• openhuman.orchestration_session_spawn { name } → { session_id }
• openhuman.orchestration_session_list → [SessionRecord]
• openhuman.orchestration_session_send { session_id, message } → { response }
• openhuman.orchestration_session_inspect { session_id } → { last_output, status }
• openhuman.orchestration_session_terminate { session_id }

6. Master chat UX

• Brain tab: session list with status badges (Idle / Running / Awaiting), last-output preview, Send / Inspect / Terminate actions per session
• Master chat understands orchestration intents and routes: "Open Human, compare outputs from instance 1 and 3 and summarize" → fan-out → aggregate → reply

Tiny Place / remote Claude integration

For remote Claude sessions (not local subprocess): reuse the tiny.place contact edge from PR #4400 as the transport. The session inbox becomes a tiny.place DM inbox for that contact. Local subprocess sessions use the IPC inbox directly. The registry abstracts over both.

POC acceptance criteria

• Spawn — orchestration_session_spawn starts a claude_agent_sdk subprocess and registers it; 5+ can run concurrently.
• List — orchestration_session_list returns all active sessions with display names and status.
• Send — orchestration_session_send forwards a message to a named session via its inbox and returns the response to the master chat.
• Inspect — orchestration_session_inspect retrieves the last output and status of a session by name or id.
• Natural language routing — From the master chat, "go to instance 1 and do X" resolves and executes correctly.
• Compare — OpenHuman can fan out the same prompt to two sessions and return a comparison summary.
• Brain tab — Session list with status visible; Send / Inspect / Terminate actions work.
• Tiny place pairing — Sessions linked via PR [codex] Add tiny.place orchestration pairing flow #4400 contact edges appear in the registry alongside local subprocess sessions.
• No master chat pollution — Raw session stdout/logs do not appear in the master chat; only OpenHuman's synthesized response does.
• Diff coverage ≥ 80% — POC PR meets the changed-lines coverage gate.

Related

• claude_agent_sdk provider (subprocess, the session runtime): PR feat(inference): add claude_agent_sdk provider (Claude CLI subprocess) #2746
• tiny.place orchestration pairing (contact edges, Brain tab, pairing store): PR [codex] Add tiny.place orchestration pairing flow #4400
• Sub-agent execution context tech-debt (to clean up alongside): tech-debt: make sub-agent execution context explicit (retire the current_parent() task-local footgun) #4336
• Multi-agent visibility layer feature request: Feature Request : Concurrent orchestrator visibility layer — live multi-agent status, cost, hallucination, and model health in a unified dashboard #1840
• Epic: Epic: Google Meet Meeting Assistant — proactive join, notes, summaries & in-call agency (Phase 1 + 2) #3505 (meeting assistant — same orchestration patterns apply)