# How jcode Implements Swarm Coordination for Multiple Agents: Event-Driven Architecture Explained

> jcode implements swarm coordination for multiple agents using an event-driven architecture. Discover how shared plans and member status synchronize across clients in this repository.

- Repository: [Jeremy Huang/jcode](https://github.com/1jehuang/jcode)
- Tags: architecture
- Published: 2026-04-30

---

**jcode implements swarm coordination for multiple agents by treating each session as an independent Agent attached to the same repository, automatically broadcasting server-side events that synchronize shared plans and member status across all connected clients.**

The `1jehuang/jcode` repository provides a terminal-based coding agent that supports collaborative editing through an event-driven swarm coordination system. When multiple users open the same repository simultaneously, jcode automatically detects the overlap and forms a swarm that enables real-time synchronization of plans, alerts, and conflict detection. This article examines the actual source code to explain exactly how jcode implements swarm coordination for multiple agents across its three-layer architecture.

## The Three-Layer Architecture of Swarm Coordination

### Agent Core: The Pending Alerts Buffer

At the foundation of the system lies the `Agent` struct defined in [`src/agent.rs`](https://github.com/1jehuang/jcode/blob/main/src/agent.rs). Each agent maintains a **`pending_alerts`** buffer (lines 94-100) that receives notifications generated from swarm events. According to the `1jehuang/jcode` source code, when the agent prepares the next provider request via `Agent::messages_for_provider`, it appends these alerts to the system prompt using `current_turn_system_reminder`. This injection mechanism ensures the LLM sees the latest swarm plan without requiring separate API calls.

### Protocol Layer: Server-Side Event Streaming

The coordination mechanism relies on two primary server-pushed event types dispatched through [`src/tui/app/remote/server_events.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/server_events.rs). The server emits **`ServerEvent::SwarmStatus { members }`** as a heartbeat containing a `Vec<SwarmMemberStatus>` that lists every participant and their lifecycle state. Additionally, **`ServerEvent::SwarmPlan`** transmits a diff of the shared plan, including additions, deletions, and re-orders. The client stores this data in a **`RemoteSwarmPlanSnapshot`** managed by [`src/tui/app/remote/swarm_plan_core.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/swarm_plan_core.rs), which parses events and synchronizes both the UI and local state.

### UI Layer: Visual Feedback and Conflict Detection

The presentation layer aggregates swarm data through `SwarmInfo` structures defined in [`src/tui/info_widget.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/info_widget.rs). This component collects `SwarmMemberStatus` entries and the latest `RemoteSwarmPlanSnapshot` to render a concise status bar showing each member's role, conflict flags, and plan summaries. The background rendering logic in [`src/tui/info_widget_swarm_background.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/info_widget_swarm_background.rs) (lines 245-254) refreshes this display whenever new `SwarmStatus` or `SwarmPlan` events arrive, providing immediate visual feedback when conflicts emerge.

## Step-by-Step Swarm Coordination Flow

1. **Session Initialization**: When a user executes `jcode start`, `Agent::new` creates an independent agent instance in [`src/agent.rs`](https://github.com/1jehuang/jcode/blob/main/src/agent.rs).

2. **Automatic Swarm Detection**: The backend recognizes existing sessions on the same repository and transmits an initial `SwarmStatus` event containing a `Vec<SwarmMemberStatus>` that enumerates all participants.

3. **Event Processing**: The dispatcher in [`src/tui/app/remote/server_events.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/server_events.rs) matches incoming events, updates `App::tui_state.swarm_info`, and instantiates `RemoteSwarmPlanSnapshot::new` to maintain local copies of the shared plan.

4. **Alert Generation**: The system pushes textual alerts (e.g., "⚡ Swarm plan updated") into the `Agent.pending_alerts` buffer, ensuring the next LLM turn receives current context.

5. **LLM Context Injection**: During `Agent::messages_for_provider`, pending alerts append to the system prompt, allowing the model to generate conflict-aware responses based on the latest swarm state.

6. **Conflict Resolution**: Each `SwarmMemberStatus` carries a `conflict` flag that the UI highlights; the backend rejects conflicting file writes and broadcasts updated `SwarmPlan` events to resolve discrepancies across the swarm.

## Practical Configuration and Usage Examples

### Enabling Swarm Mode via Configuration

Configure the swarm-specific model in your `~/.jcode/config.toml`:

```toml
[agents]
swarm_model = "gpt-4o-mini"   # model used for the swarm sub-agent

```

### Starting a Multi-Agent Swarm

Launch two sessions pointing to the same repository to automatically form a swarm:

```bash

# Session A

jcode start myproj

# Session B (separate terminal)

jcode start myproj

```

Both clients receive `SwarmStatus` events listing both participants and begin exchanging plan updates immediately.

### Accessing Swarm Plan Data Programmatically

Inspect pending alerts from within an agent turn:

```rust
use jcode::agent::Agent;

// Inside an agent turn
if let Some(plan) = agent.pending_alerts.last() {
    println!("Latest swarm plan: {}", plan);
}

```

### Runtime Model Selection

Switch the swarm model without restarting sessions using the TUI picker:

```rust
app.open_agent_model_picker(jcode::tui::AgentModelTarget::Swarm);

```

This updates the configuration and applies the new model to subsequent swarm turns.

## Key Source Files for Swarm Coordination

- **[`src/agent.rs`](https://github.com/1jehuang/jcode/blob/main/src/agent.rs)**: Core `Agent` struct with `pending_alerts` field and injection logic for `Agent::messages_for_provider`.
- **[`src/tui/app/remote/server_events.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/server_events.rs)**: Event dispatcher handling `ServerEvent::SwarmStatus` and `ServerEvent::SwarmPlan`.
- **[`src/tui/app/remote/swarm_plan_core.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/swarm_plan_core.rs)**: Helper for storing `RemoteSwarmPlanSnapshot` and generating user-visible notifications.
- **[`src/tui/info_widget.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/info_widget.rs)**: `SwarmInfo` definition and rendering logic for member status display.
- **[`src/tui/info_widget_swarm_background.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/info_widget_swarm_background.rs)**: Background widget implementation for swarm status visualization.
- **[`src/tui/app/remote/key_handling.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/key_handling.rs)**: UI commands for toggling swarm features and updating configuration.
- **[`src/tui/app/inline_interactive/openers.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/inline_interactive/openers.rs)**: Picker logic for launching swarm-specific targets from the command palette.

## Summary

- jcode treats each session as an independent `Agent` attached to a shared repository, automatically forming swarms when multiple sessions connect to the same codebase.
- Coordination relies on **`ServerEvent::SwarmStatus`** heartbeats and **`ServerEvent::SwarmPlan`** diffs transmitted through [`src/tui/app/remote/server_events.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/app/remote/server_events.rs).
- The **`pending_alerts`** buffer in [`src/agent.rs`](https://github.com/1jehuang/jcode/blob/main/src/agent.rs) injects swarm context into LLM requests via `Agent::messages_for_provider` and `current_turn_system_reminder`.
- **`RemoteSwarmPlanSnapshot`** maintains local copies of shared plans while `SwarmInfo` renders real-time status in the terminal UI.
- Conflict detection uses boolean flags in `SwarmMemberStatus`, with the backend rejecting conflicting writes and broadcasting resolution updates to maintain consistency.

## Frequently Asked Questions

### How does jcode detect when multiple agents form a swarm?

When a client opens a session with `jcode start`, the backend checks if other active sessions exist for the same repository. If detected, it automatically creates a swarm and broadcasts a `SwarmStatus` event containing a `Vec<SwarmMemberStatus>` to all connected clients, as implemented in the server event handling logic.

### What types of events are exchanged between swarm members?

The protocol transmits two primary event types: `ServerEvent::SwarmStatus` serves as a heartbeat listing all members and their lifecycle states, while `ServerEvent::SwarmPlan` carries diffs of the shared plan including file additions, deletions, and re-ordering operations.

### How does the LLM stay synchronized with the swarm plan?

The `Agent` struct maintains a `pending_alerts` buffer that receives notifications from swarm events. When preparing the next provider request in `Agent::messages_for_provider`, the system appends these alerts to the prompt via `current_turn_system_reminder`, ensuring the model receives the latest plan context without additional API calls.

### How are conflicts handled in a jcode swarm?

Each `SwarmMemberStatus` includes a `conflict` flag that the UI highlights in the status bar. When conflicting file writes occur, the backend rejects the operation and broadcasts an updated `SwarmPlan` event that resolves the conflict, with visual feedback rendered through `SwarmInfo` in [`src/tui/info_widget.rs`](https://github.com/1jehuang/jcode/blob/main/src/tui/info_widget.rs).