Live Collaboration (Collab-Web)
Relevant source files
The following files were used as context for generating this wiki page:
Live Collaboration within the Oh My Pi (OMP) ecosystem facilitates real-time interaction between human developers, autonomous agents, and subagents. This system enables synchronized session sharing, multi-agent coordination via internal communication protocols, and visual rendering of agent activities through specialized web interfaces. It bridges the gap between the terminal-based CLI and a distributed, collaborative environment where multiple entities can work on the same codebase simultaneously.
Sources: packages/coding-agent/DEVELOPMENT.md:121-122, packages/coding-agent/src/prompts/system/subagent-system-prompt.md:40-52
Architectural Overview
The collaboration architecture is built on a hierarchy of agents orchestrated by a main host. The system utilizes a "Worker-Host" dispatch model where the CLI can spawn specialized processes and subagents to handle parallel tasks. Collaboration is exposed through various modes, including a TUI (Terminal User Interface) and the collab-web environment, which provides specialized React tool renderers for visual oversight.
Component Breakdown
| Component | Responsibility | Source |
|---|---|---|
| AgentSession | Manages JSONL session trees, storage, and history persistence. | DEVELOPMENT.md:83 |
| InteractiveMode | Handles the TUI event loop for real-time human-agent interaction. | DEVELOPMENT.md:65 |
| Orchestrator | Decomposes tasks, dispatches subagents, and verifies results. | orchestrate-notice.md:6-12 |
| Subagents | Specialized entities (e.g., reviewer, designer) performing atomic tasks. | subagent-system-prompt.md:1-10 |
| IRC Tool | Internal communication channel for subagent coordination. | subagent-system-prompt.md:40-52 |
Sources: packages/coding-agent/DEVELOPMENT.md:65-83, packages/coding-agent/src/prompts/system/orchestrate-notice.md:6-12, packages/coding-agent/src/prompts/system/subagent-system-prompt.md:1-10
Communication and Coordination (IRC)
Subagents operating within the same session utilize an internal communication protocol referred to as IRC. This allows for quick coordination and discovery of peers to prevent overlapping edits or redundant work.
The diagram above illustrates the peer-to-peer discovery and messaging flow between subagents via the internal IRC service.
Sources: packages/coding-agent/src/prompts/system/subagent-system-prompt.md:40-52
Coordination Rules
- Discovery: Agents use
ircwithop: "list"to refresh the roster of visible peers, their roles, and current activities. - Conflict Prevention: Agents MUST message peers before editing files that a sibling might already own to avoid collision.
- Messaging: Supports addressing specific peer IDs or using
"all"for broadcasts.
Sources: packages/coding-agent/src/prompts/system/subagent-system-prompt.md:45-52
Task Orchestration Workflow
The orchestration system manages the lifecycle of collaborative tasks through a structured phase-based approach. The orchestrator is responsible for decomposing high-level requests into parallelizable units for subagents.
Orchestration Phases
- Ingest: Reading referenced files, audits, and plans to understand current state.
- Plan: Materializing the work surface into
todoitems and ordered phases. - Dispatch: Launching parallel
tasksubagents in unified batches. - Verify: Running gates (e.g.,
bun check,bun test) after each phase. - Commit: Performing git commits upon successful verification.
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:37-47
The sequence diagram shows the lifecycle of a task from initial assignment to final verification and commitment.
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:37-47
Specialized Agent Roles in Collaboration
Collaboration involves several specialized roles that provide specific output formats and capabilities:
The Reviewer Agent
The reviewer specialist identifies bugs and security issues. It uses tools like git diff or gh pr diff and records findings incrementally.
- Cross-Boundary Analysis: The reviewer MUST trace dispatch points (routers, switches) outside the immediate diff to ensure integration correctness.
- Yield Protocol: Uses
type: ["findings"]for incremental yields.
Sources: packages/coding-agent/src/prompts/agents/reviewer.md:1-85
The Subagent Environment
Subagents operate in isolated working trees to prevent interference with the original repository until work is verified and yielded.
- Contract: Subagents MUST report results via
yieldand continue work until the ticket is closed. - Isolation: Subagents NEVER modify files outside their assigned working tree.
Sources: packages/coding-agent/src/prompts/system/subagent-system-prompt.md:33-70
Visual Rendering (Collab-Web)
The collab-web module (located in packages/collab-web/) provides the UI components for the collaboration environment. It uses React to render tool views, allowing human collaborators to see agent activities visually. Developers modify renderers in collab-web/src/tool-render/ and must rebuild them using bun run gen:tool-views for them to be available in the coding-agent session.
Sources: packages/coding-agent/DEVELOPMENT.md:27-28, packages/coding-agent/DEVELOPMENT.md:121-122
Summary
Live Collaboration in Oh My Pi is a multi-layered system that combines structured task orchestration, real-time peer-to-peer communication via IRC, and web-based visual oversight. By utilizing specialized agents like the reviewer and subagents operating in isolated environments, the system ensures high-quality, parallelized code production while maintaining session integrity through rigorous verification gates.
Sources: packages/coding-agent/DEVELOPMENT.md:121-122, packages/coding-agent/src/prompts/system/orchestrate-notice.md:14-35