Skip to content

feat(fleet): add MCP channel server for real-time agent communication#642

Open
Wirasm wants to merge 2 commits intomainfrom
feature/fleet-channels
Open

feat(fleet): add MCP channel server for real-time agent communication#642
Wirasm wants to merge 2 commits intomainfrom
feature/fleet-channels

Conversation

@Wirasm
Copy link
Copy Markdown
Owner

@Wirasm Wirasm commented Mar 24, 2026

Summary

Adds a kild-fleet MCP channel server that watches inbox files and pushes notifications into Claude Code sessions via the channels protocol. Reduces fleet communication latency from ~1s (Claude inbox polling) to ~100ms (fs.watch + stdio notification). Also exposes MCP tools so agents can write status/reports/messages without shelling out to CLI commands.

Changes

  • New: integrations/channel.rs — installs channel server, patches .mcp.json, cleanup on destroy
  • New: kild init-channels CLI command — installs server.ts + bun deps at ~/.kild/channels/fleet/
  • New: FleetConfig in kild-config with [fleet] channels toggle (default: false)
  • Modified: fleet_agent_flags() appends --dangerously-load-development-channels server:kild-fleet when channels enabled
  • Modified: daemon_spawn.rs calls setup_channel_integration() in the spawn sequence
  • Modified: destroy.rs cleans up .mcp.json from project root for --main sessions

Architecture

Agent brain (Claude session)         Agent worker (Claude session)
  └─ kild-fleet MCP server            └─ kild-fleet MCP server
       │  fs.watch(KILD_FLEET_DIR)         │  fs.watch(KILD_INBOX)
       │                                   │
       └──── ~/.kild/inbox/<project>/ ─────┘
              (existing file protocol)

The channel server is a TypeScript/Bun MCP server embedded as a string constant in the Rust binary. It reads $KILD_INBOX and $KILD_FLEET_DIR from the PTY environment (already injected by the inbox module). The file-based inbox protocol remains the source of truth — the channel is a notification + tooling layer on top.

MCP Tools Exposed

Tool Role Action
report_status worker Write status + optional report.md
send_to_brain worker Write task.md to brain's inbox
send_to_worker brain Write task.md to worker's inbox
list_fleet both List fleet members with status

Files Changed

15 files changed (+616, -23)

File list
  • crates/kild-core/src/sessions/integrations/channel.rs (new, 442 lines)
  • crates/kild/src/commands/init_channels.rs (new, 59 lines)
  • crates/kild-config/src/types.rs — FleetConfig struct
  • crates/kild-config/src/loading.rs — merge logic
  • crates/kild-config/src/lib.rs — re-export
  • crates/kild-core/src/lib.rs — re-export
  • crates/kild-core/src/sessions/daemon_spawn.rs — wire channel integration
  • crates/kild-core/src/sessions/fleet.rs — channels flag in fleet_agent_flags()
  • crates/kild-core/src/sessions/destroy.rs — .mcp.json cleanup
  • crates/kild-core/src/sessions/daemon_helpers.rs — re-export
  • crates/kild-core/src/sessions/integrations/mod.rs — register module
  • crates/kild-paths/src/lib.rs — channels_dir(), fleet_channel_dir()
  • crates/kild/src/app/misc.rs — init-channels clap def
  • crates/kild/src/app/mod.rs — subcommand registration
  • crates/kild/src/commands/mod.rs — dispatch

Testing

  • cargo fmt --check && cargo clippy --all -- -D warnings passes
  • cargo test --all passes (0 failures)
  • cargo build --all succeeds
  • E2E: kild init-channels installs server + deps
  • E2E: Brain create gets .mcp.json + channels flag
  • E2E: Worker create gets .mcp.json + channels flag
  • E2E: kild inject → worker receives task, writes status + report
  • E2E: Brain destroy cleans up .mcp.json from project root
  • E2E: Graceful degradation when [fleet] channels = false (no .mcp.json, no flag)

Configuration

[fleet]
channels = true  # default: false (research preview)

Requires Bun runtime. Run kild init-channels to install dependencies.

Wirasm added 2 commits March 24, 2026 13:56
Add a kild-fleet MCP channel server that watches inbox files and pushes
notifications into Claude Code sessions via the channels protocol. This
reduces fleet communication latency from ~1s (Claude inbox polling) to
~100ms (fs.watch + stdio notification).

The channel server (TypeScript/Bun) is embedded in the Rust binary and
installed to ~/.kild/channels/fleet/ via `kild init-channels`. It exposes
MCP tools (report_status, send_to_worker, send_to_brain, list_fleet) so
agents can communicate without shelling out to CLI commands.

Gated behind [fleet] channels = true config flag (default: false).
Requires Bun runtime. Graceful degradation when unavailable.

New command: `kild init-channels` — installs server + bun deps.
New config: `[fleet] channels` — enables channel server for fleet sessions.
…tall

Channel server writes a .channel breadcrumb to the inbox dir after MCP
handshake completes. `kild inbox` surfaces this as [channel] next to the
status line, so you can confirm the channel server is actually connected.

Stale breadcrumbs are cleaned on session create/open (ensure_inbox).

Also skip `bun install` in `kild init-channels` when node_modules exists.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant