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

> Learn how to make agents hive-aware in Munder Difflin. This technical guide explains injecting environment variables and more via HiveManager.ensureAgent for seamless coordination.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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

```typescript
{
  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

```typescript
{
  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

```typescript
// 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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/identity.md) and [`memory.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.