Understanding registry.json in the Munder Difflin Hive: Purpose and Implementation

registry.json acts as the central roster for the Munder Difflin hive, maintaining a live snapshot of every agent's identity, role, capabilities, and current status to enable the orchestrator to monitor the team and route requests without requiring an external state store.

Within the chaitanyagiri/munder-difflin repository, registry.json serves as the single source of truth for agent metadata. This JSON file lives at the root of the on-disk hive directory and eliminates the need for separate databases by providing atomic, filesystem-based state management. According to the documentation in HIVE.md, it records "every agent, role, capabilities, status, seat" to create a deterministic view of the entire system.

What is registry.json?

registry.json functions as the roster that captures a complete snapshot of the hive's population at any given moment. Unlike hidden in-memory state, this file provides a transparent, persistent record that both the orchestrator and external tools can read to understand the current composition of the agent fleet.

The file enables safe, deterministic routing by allowing the orchestrator to validate that existing agents are in appropriate working states before assigning tasks. Because it is written atomically on every change, processes always read consistent data without race conditions.

Core Responsibilities of the Registry

Agent Lifecycle Tracking

Every time an agent enters or leaves the system, src/main/hive.ts updates the registry. The ensureAgent function demonstrates this pattern by writing to the JSON file immediately after populating fields such as role, status, cwdValid, and sessionId. This approach ensures that agent metadata persists across orchestrator restarts and remains accessible to external monitoring tools.

Routing and Load Balancing

The orchestrator, implemented in src/main/index.ts, consults the live roster before making routing decisions. The source explicitly describes checking "the live roster first (active agents in registry.json + their state in fleet.json)" to determine whether to reuse an existing agent or spawn a new instance. This design prevents resource waste and eliminates duplicate agent proliferation.

File Structure and Location

The registry resides at the root of the hive directory alongside fleet.json. Tools such as tools/agent-env.cjs read only these two files to construct the environment variables and context for an agent's process, demonstrating the file's role as the minimal interface for agent introspection.

A typical entry contains:

• agent identifier: Unique name or ID within the hive
• role: Functional classification (e.g., "worker", "god/orchestrator")
• capabilities: Available skills or permissions for task routing
• status: Current state (e.g., "active", "busy", "archived")
• cwdValid: Boolean flag for working directory validation
• sessionId: Session tracking identifier for lifecycle management

Working with registry.json Programmatically

The Hive class in src/main/hive.ts provides the primary interface for registry operations. These patterns demonstrate how to interact with the roster safely.

Reading the Current Roster

To load the current snapshot of all agents:

// Load the current registry snapshot
const hive = new Hive();                 // Hive class defined in src/main/hive.ts
const registry = hive.registry();        // Returns the parsed JSON object

for (const [agentId, meta] of Object.entries(registry.agents)) {
  console.log(`${agentId}: ${meta.role} – ${meta.status}`);
}

The registry() method parses registry.json and returns a typed object reflecting the current hive population, as implemented in src/main/hive.ts.

Updating Agent Status

When modifying an agent's state, always write the JSON atomically to prevent corruption:

const hive = new Hive();
const reg = hive.registry();

// Mark agent "bob" as busy
if (reg.agents['bob']) {
  reg.agents['bob'].status = 'busy';
  hive.writeJson(hive.joinRoot('registry.json'), reg);
}

The writeJson helper ensures that updates to fields like role or sessionId persist to disk immediately, matching the atomic write pattern used in ensureAgent.

Routing Decisions Based on Registry State

Before spawning new agents, check the roster to avoid duplicates:

function shouldSpawnNewAgent(requestedName: string): boolean {
  const reg = new Hive().registry();
  // If an active agent already matches the requested name, reuse it
  return !Object.values(reg.agents).some(
    a => a.name === requestedName && a.status !== 'archived'
  );
}

This logic mirrors the orchestrator's approach in src/main/index.ts, which prevents unnecessary agent proliferation by checking existing entries in registry.json first.

Summary

• registry.json serves as the authoritative roster for the Munder Difflin hive, eliminating the need for external databases by providing filesystem-based state management.
• The file tracks agent identifiers, roles, capabilities, status, and session metadata in a single JSON structure at the hive root.
• Atomic writes in src/main/hive.ts ensure the orchestrator always reads consistent state without race conditions during concurrent agent lifecycle events.
• The orchestrator uses this file to route requests and prevent duplicate agent spawning, consulting it alongside fleet.json in src/main/index.ts.

Frequently Asked Questions

Where is registry.json located in a Munder Difflin hive?

The file resides at the root of the on-disk hive directory, alongside fleet.json. According to the source in src/main/hive.ts, the Hive class provides the joinRoot() method to resolve this path, while tools like tools/agent-env.cjs read it directly from this location to configure agent environments.

What information does registry.json store about each agent?

Each entry records the agent's identifier, role, capabilities, current status, working-directory validation (cwdValid), and session ID. As documented in HIVE.md, this comprehensive metadata allows the orchestrator to determine precisely who is available, what they can do, and what they are currently doing.

How does the orchestrator use registry.json to route requests?

The orchestrator, implemented in src/main/index.ts, checks the live roster (active agents listed in registry.json plus their state in fleet.json) before processing incoming requests. If an active agent with matching capabilities exists, the orchestrator routes the request to that agent rather than spawning a new instance, optimizing resource utilization.

Is registry.json safe for concurrent access?

Yes, because the Hive class writes the file atomically on every change. The writeJson method used in src/main/hive.ts ensures that updates to agent metadata, such as those performed in ensureAgent, complete fully before the orchestrator or other processes read the file, preventing partial or corrupted states during concurrent agent lifecycle events.

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