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

> Discover registry.json the central roster for the Munder Difflin hive. Learn how it tracks agent status and capabilities for seamless orchestration without an external state store.

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

---

**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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) + their state in [`fleet.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```typescript
// 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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) and returns a typed object reflecting the current hive population, as implemented in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts).

### Updating Agent Status

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

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

```typescript
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/index.ts), which prevents unnecessary agent proliferation by checking existing entries in [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/fleet.json) in [`src/main/index.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/fleet.json). According to the source in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/index.ts), checks the **live roster** (active agents listed in [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) plus their state in [`fleet.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.