How to Make Agents Hive-Aware in Munder Difflin: The Complete Technical Guide

Munder Difflin transforms standard LLM processes into hive-aware agents by injecting environment variables, command-line flags, and protocol seeds through the HiveManager.ensureAgent method in src/main/hive.ts, enabling coordination via the on-disk hive file system regardless of whether the provider natively supports Claude-Code hooks.

Munder Difflin is an open-source multi-agent orchestration framework that coordinates disparate LLM providers through a shared "hive" coordination layer. When spawning agents, the system must bridge the gap between standalone Claude-Code or Codex instances and the hive's message routing, blackboard, and task ledger infrastructure. The framework achieves this through a sophisticated injection system that modifies the spawn environment of every child process.

The Core Initialization Pipeline in HiveManager

The central mechanism for creating hive-aware agents resides in HiveManager.ensureAgent within src/main/hive.ts. This method performs two critical operations when preparing an agent for execution.

First, it creates the agent's workspace on disk under <harnessHome>/hive/agents/<agentId>/. This directory contains the agent's identity configuration, semantic memory storage, inbox/outbox message queues, and cursor state files.

Second, it constructs a SpawnInjection object containing the precise args and env values that must be passed to the child process. This injection ensures that when the LLM provider launches, it possesses the necessary context to communicate with the hive's Unix-domain socket (or Windows named pipe) and access its own file-based storage.

Wiring Native Hive-Aware Providers

For providers that natively support Claude-Code's extension system, the framework leverages direct hook integration. The system detects these providers via isClaudeProvider in src/shared/agentProvider.ts.

Claude-Code Specific Configuration

When spawning Claude-Code compatible agents, the SpawnInjection receives:

• The --append-system-prompt flag followed by a generated protocol seed from HiveManager.injectedPrompt
• A per-agent settings.json file generated by HiveManager.hookSettings (lines 449-491) that configures the hook system to connect to hooks.sock
• The --settings <path> argument pointing to this configuration file

Environment Variable Injection for Claude Providers

The following environment variables are injected into every Claude-Code process:

• AGENT_ID and AGENT_NAME: Identity metadata for the agent
• HIVE_ROOT: Path to the hive repository root
• AGENT_DIR: Path to the specific agent's workspace folder
• HIVE_NODE: Absolute path to the bundled Node.js launcher (hive-node), ensuring helper scripts execute even when node is not on the system PATH
• HIVE_SOCK: Path to the Unix-domain socket or named pipe that the hook shim uses to push events into the main process

Bridging Non-Hive-Aware Providers

For providers lacking native Claude-Code hook support—such as Codex, Grok, or Agy—the framework implements alternative bridge mechanisms within the same ensureAgent flow. These providers still receive full hive capabilities through protocol injection and external bridge processes.

Protocol Injection for Hook-Less CLIs

Instead of relying on the provider's extension system, Munder Difflin delivers the protocol text as an initial prompt (positional argument or flag) through HiveManager.injectedPrompt. This ensures the agent understands its hive identity without requiring special CLI flags.

Hook Bridge Installation vs. Proxy Sidecars

Based on the provider's bridgeOf descriptor defined in src/shared/agentProvider.ts, the manager selects one of two bridge strategies:

• Hook Shim Installation: Functions like installAgyHooks or installCodexHooks install shim layers that translate the provider's native hook callbacks into the hive socket protocol.
• Proxy Sidecar: For providers with no hook system, startProxyBridge (lines 549-610) spins up a proxy process that observes the provider's HTTP traffic and synthesizes equivalent hook payloads.

Both approaches populate HIVE_SOCK and provider-specific variables such as CODEX_HOME or PI_CODING_AGENT_DIR in the spawn environment.

Argument Handling for Unsupported CLIs

The SpawnInjection adapts to provider limitations through:

• Pre-args: For example, Codex receives --dangerously-bypass-hook-trust to enable the bridge functionality
• Seed Delivery: Providers requiring TUI interaction receive a seedPrompt with seedDelivery: 'type-into-tui' to simulate keyboard input

File System Structure and SpawnInjection Examples

Claude-Aware Agent Configuration

{
  args: [
    '--append-system-prompt',
    '...protocol seed...'
  ],
  env: {
    AGENT_ID: 'agent-123',
    AGENT_NAME: 'Researcher',
    HIVE_ROOT: '/home/user/.munder-difflin/hive',
    AGENT_DIR: '/home/user/.munder-difflin/hive/agents/agent-123',
    HIVE_NODE: '/home/user/.munder-difflin/hive/bin/hive-node',
    HIVE_SOCK: '/home/user/.munder-difflin/hive/hooks.sock'
  }
}

Non-Hive-Aware Provider (Codex) Configuration

{
  args: ['--dangerously-bypass-hook-trust', '...protocol seed...'],
  env: {
    AGENT_ID: 'agent-456',
    HIVE_SOCK: '/home/user/.munder-difflin/hive/hooks.sock',
    CODEX_HOME: '/home/user/.munder-difflin/hive/agents/agent-456/.codex',
    HIVE_NODE: '/home/user/.munder-difflin/hive/bin/hive-node'
  }
}

Basic Agent Initialization

// In the main Electron process
const hive = new HiveManager(() => config.harnessHome);
await hive.ensureAgent(
  {
    id: 'agent-123',
    name: 'Researcher',
    provider: { name: 'claude' },
    cwd: '/path/to/project',
  },
  { semanticMemory: true }
);

This call creates the agent's file structure, writes identity.md and memory.md, and returns the SpawnInjection containing the exact arguments and environment variables required for hive participation.

Summary

• HiveManager.ensureAgent in src/main/hive.ts is the sole entry point for agent initialization, creating workspaces and building injection payloads for all provider types.
• Environment variables (AGENT_ID, HIVE_ROOT, HIVE_SOCK) provide the runtime context necessary for agents to locate their inbox/outbox and communicate with the orchestrator.
• Claude-Code providers receive native hook configuration via --append-system-prompt and dedicated settings.json files.
• Non-hive-aware providers require bridge shims (for Codex/Agy) or proxy sidecars (for HTTP-based providers) to achieve equivalent functionality.
• Protocol seeds ensure every agent understands its identity and capabilities regardless of the underlying LLM platform.

Frequently Asked Questions

What does "hive-aware" mean in Munder Difflin?

Hive-aware refers to an agent process that has been configured to recognize and interact with the Munder Difflin coordination layer. Such agents can read from their file-based inbox, write to their outbox, and emit hook events to the central orchestrator via the HIVE_SOCK socket connection.

How does Munder Difflin handle providers without native hook support?

The framework implements bridge strategies based on the provider's bridgeOf descriptor. For CLI tools like Codex, it installs hook shims that intercept native callbacks. For API-only providers, it launches a proxy sidecar via startProxyBridge that monitors HTTP traffic and synthesizes equivalent hook payloads into the hive socket.

What is the purpose of the HIVE_NODE environment variable?

HIVE_NODE provides the absolute path to the bundled Node.js launcher (hive-node) shipped with Munder Difflin. This ensures that agents can execute helper scripts and bridge code even in environments where Node.js is not installed globally or available on the system PATH.

Where is the agent workspace created on disk?

Each agent receives a dedicated directory at <harnessHome>/hive/agents/<agentId>/, established by HiveManager.ensureAgent. This workspace contains the agent's identity metadata, persistent memory files, inbox/outbox message directories, and cursor state, enabling durable coordination across process restarts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}