@inixiative/hivemind 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aron Greenspan / inixiative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# Hivemind
+
+Multi-agent coordination for Claude Code. Shared event log, plans, and tasks across multiple Claude sessions.
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g @inixiative/hivemind
+```
+
+Then add to Claude Code:
+
+```bash
+claude mcp add hivemind -- hivemind-mcp
+```
+
+Or manually add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "hivemind": {
+      "command": "hivemind-mcp"
+    }
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/inixiative/hivemind.git
+cd hivemind
+./setup.sh
+```
+
+Restart Claude Code and hivemind is active.
+
+On startup, Claude receives context about the hivemind state:
+```
+hivemind: agt_7a3f2b joined myproject (main)
+  session: abc123-def456
+  active: agt_c4d5e6_alice
+```
+
+This info goes into Claude's system context (not printed to terminal). Claude knows its agent ID and can see other active agents.
+
+## How It Works
+
+Agents are tracked by **process ID (PID)**, not heartbeats:
+- SessionStart hook registers agent with Claude's PID
+- Coordinator monitors PIDs every 30 seconds
+- When Claude exits, coordinator detects dead PID and marks agent dead
+- No polling or heartbeats required
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
+
+## Tools
+
+| Tool | Description | Auto |
+|------|-------------|------|
+| `hivemind_status` | Get status (agents, plans, events) | ✓ |
+| `hivemind_events` | Get recent events | ✓ |
+| `hivemind_query` | Query events with filters | ✓ |
+| `hivemind_claim_task` | Claim a task | ✓ |
+| `hivemind_start_task` | Mark task in progress | ✓ |
+| `hivemind_complete_task` | Mark task done | ✓ |
+| `hivemind_worktree_cleanup` | Clean up stale worktrees | ✓ |
+| `hivemind_setup` | Initialize project | ✓ |
+| `hivemind_register` | Register this agent | ✓ |
+| `hivemind_emit` | Emit event to log | ✗ |
+| `hivemind_reset` | Reset database | ✗ |
+
+Tools marked ✓ are auto-approved after `./setup.sh`. Tools marked ✗ require confirmation.
+
+## CLI
+
+```bash
+hivemind install    # One-time global setup
+hivemind init       # Register current project
+hivemind status     # Show project status
+hivemind watch      # Live tail of events
+hivemind join       # Join as an agent
+```
+
+## ID Format
+
+`{type}_{6hex}[_{label}]`
+
+- `agt_7a3f2b_alice` - Agent
+- `pln_e9d2c1_auth` - Plan
+- `tsk_e9d2c1_001` - Task (inherits plan hex)
+- `evt_f1a2b3_00001` - Event
+- `wkt_a1b2c3` - Worktree
+
+## Event Types
+
+```
+agent:register/unregister
+plan:create/join/complete
+task:create/claim/start/complete/block
+decision, question, answer, note
+```
+
+## Database
+
+Stored at `~/.hivemind/claude_hivemind_{project}/hivemind.db`
+
+Tables: agents, plans, tasks, events, worktrees
+
+## Timestamps
+
+Format: `yyyy/mm/dd hh:mm:ss TZ`

package/dist/agents/agents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/agents.test.js

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach, afterEach, afterAll } from 'bun:test';
+import { createTestDb, cleanupAllTestDbs } from '../test/setup';
+import { buildAgent, buildTask } from '../test/factories';
+import { registerAgent } from './registerAgent';
+import { getAgent } from './getAgent';
+import { getActiveAgents } from './getActiveAgents';
+import { markAgentDead } from './markAgentDead';
+import { markAgentIdle } from './markAgentIdle';
+import { updateAgentContext } from './updateAgentContext';
+import { updateAgentTask } from './updateAgentTask';
+import { unregisterAgent } from './unregisterAgent';
+describe('Agents Module', () => {
+    let testDb;
+    beforeEach(() => {
+        testDb = createTestDb();
+    });
+    afterEach(() => {
+        testDb.cleanup();
+    });
+    afterAll(() => {
+        cleanupAllTestDbs();
+    });
+    describe('registerAgent', () => {
+        it('creates a new agent with generated id', () => {
+            const agent = registerAgent(testDb.db, {});
+            expect(agent.id).toMatch(/^agt_[a-f0-9]{6}$/);
+            expect(agent.status).toBe('active');
+            expect(agent.created_at).toBeDefined();
+        });
+        it('creates agent with label', () => {
+            const agent = registerAgent(testDb.db, { label: 'main' });
+            expect(agent.id).toMatch(/^agt_[a-f0-9]{6}_main$/);
+            expect(agent.label).toBe('main');
+        });
+        it('creates agent with context summary', () => {
+            const agent = registerAgent(testDb.db, {
+                context_summary: 'Working on auth feature',
+            });
+            expect(agent.context_summary).toBe('Working on auth feature');
+        });
+    });
+    describe('getAgent', () => {
+        it('retrieves existing agent', () => {
+            const { agent: created } = buildAgent(testDb.db, { label: 'test' });
+            const retrieved = getAgent(testDb.db, created.id);
+            expect(retrieved).toBeDefined();
+            expect(retrieved.id).toBe(created.id);
+            expect(retrieved.label).toBe('test');
+        });
+        it('returns null for non-existent agent', () => {
+            const agent = getAgent(testDb.db, 'agt_nonexistent');
+            expect(agent).toBeNull();
+        });
+    });
+    describe('getActiveAgents', () => {
+        it('returns only active agents', () => {
+            const { agent: agent1 } = buildAgent(testDb.db, { label: 'one' });
+            const { agent: agent2 } = buildAgent(testDb.db, { label: 'two' });
+            markAgentDead(testDb.db, agent2.id);
+            const active = getActiveAgents(testDb.db);
+            expect(active).toHaveLength(1);
+            expect(active[0].id).toBe(agent1.id);
+        });
+        it('returns empty array when no active agents', () => {
+            const active = getActiveAgents(testDb.db);
+            expect(active).toHaveLength(0);
+        });
+    });
+    describe('markAgentDead', () => {
+        it('sets status to dead', () => {
+            const { agent } = buildAgent(testDb.db);
+            markAgentDead(testDb.db, agent.id);
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.status).toBe('dead');
+        });
+        it('releases claimed tasks back to pending', () => {
+            const { agent } = buildAgent(testDb.db);
+            const { task } = buildTask(testDb.db, {
+                agent,
+                status: 'claimed',
+                claimed_by: agent,
+            });
+            markAgentDead(testDb.db, agent.id);
+            const updated = testDb.db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(task.id);
+            expect(updated.status).toBe('pending');
+            expect(updated.claimed_by).toBeNull();
+            expect(updated.claimed_at).toBeNull();
+        });
+        it('releases in_progress tasks back to pending', () => {
+            const { agent } = buildAgent(testDb.db);
+            const { task } = buildTask(testDb.db, {
+                agent,
+                status: 'in_progress',
+                claimed_by: agent,
+            });
+            markAgentDead(testDb.db, agent.id);
+            const updated = testDb.db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(task.id);
+            expect(updated.status).toBe('pending');
+            expect(updated.claimed_by).toBeNull();
+        });
+        it('clears agent current_task_id and current_plan_id', () => {
+            const { agent } = buildAgent(testDb.db);
+            const { task, plan } = buildTask(testDb.db, { agent });
+            updateAgentTask(testDb.db, agent.id, plan.id, task.id);
+            let retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.current_plan_id).toBe(plan.id);
+            expect(retrieved.current_task_id).toBe(task.id);
+            markAgentDead(testDb.db, agent.id);
+            retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.current_plan_id).toBeNull();
+            expect(retrieved.current_task_id).toBeNull();
+        });
+        it('does not affect done tasks', () => {
+            const { agent } = buildAgent(testDb.db);
+            const { task } = buildTask(testDb.db, {
+                agent,
+                status: 'done',
+                claimed_by: agent,
+            });
+            markAgentDead(testDb.db, agent.id);
+            const updated = testDb.db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(task.id);
+            expect(updated.status).toBe('done');
+            expect(updated.claimed_by).toBe(agent.id);
+        });
+    });
+    describe('markAgentIdle', () => {
+        it('sets status to idle', () => {
+            const { agent } = buildAgent(testDb.db);
+            markAgentIdle(testDb.db, agent.id);
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.status).toBe('idle');
+        });
+    });
+    describe('updateAgentContext', () => {
+        it('updates context summary', () => {
+            const { agent } = buildAgent(testDb.db);
+            updateAgentContext(testDb.db, agent.id, 'New context');
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.context_summary).toBe('New context');
+        });
+    });
+    describe('updateAgentTask', () => {
+        it('updates current plan and task id', () => {
+            const { agent } = buildAgent(testDb.db);
+            const { task, plan } = buildTask(testDb.db, { agent });
+            updateAgentTask(testDb.db, agent.id, plan.id, task.id);
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.current_plan_id).toBe(plan.id);
+            expect(retrieved.current_task_id).toBe(task.id);
+        });
+        it('clears plan and task with null', () => {
+            const { agent } = buildAgent(testDb.db);
+            updateAgentTask(testDb.db, agent.id, null, null);
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.current_plan_id).toBeNull();
+            expect(retrieved.current_task_id).toBeNull();
+        });
+    });
+    describe('unregisterAgent', () => {
+        it('removes agent from database', () => {
+            const { agent } = buildAgent(testDb.db);
+            unregisterAgent(testDb.db, agent.id);
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved).toBeNull();
+        });
+    });
+});

package/dist/agents/getActiveAgents.d.ts

@@ -0,0 +1,6 @@
+import type { Database } from 'bun:sqlite';
+import type { Agent } from './types';
+/**
+ * Get all active agents
+ */
+export declare function getActiveAgents(db: Database): Agent[];

package/dist/agents/getActiveAgents.js

@@ -0,0 +1,11 @@
+/**
+ * Get all active agents
+ */
+export function getActiveAgents(db) {
+    const stmt = db.prepare(`
+    SELECT * FROM agents
+    WHERE status = 'active'
+    ORDER BY created_at DESC
+  `);
+    return stmt.all();
+}

package/dist/agents/getAgent.d.ts

@@ -0,0 +1,6 @@
+import type { Database } from 'bun:sqlite';
+import type { Agent } from './types';
+/**
+ * Get an agent by ID
+ */
+export declare function getAgent(db: Database, agentId: string): Agent | null;

package/dist/agents/getAgent.js

@@ -0,0 +1,7 @@
+/**
+ * Get an agent by ID
+ */
+export function getAgent(db, agentId) {
+    const stmt = db.prepare('SELECT * FROM agents WHERE id = ?');
+    return stmt.get(agentId) ?? null;
+}

package/dist/agents/getAgentBySessionId.d.ts

@@ -0,0 +1,10 @@
+import type { Database } from 'bun:sqlite';
+import type { Agent } from './types';
+/**
+ * Get an active agent by session ID
+ *
+ * Used for MCP tools to find "their" agent without needing the agent_id.
+ * The session_id is passed by Claude Code to hooks and can be used to
+ * correlate the hook-registered agent with subsequent MCP calls.
+ */
+export declare function getAgentBySessionId(db: Database, sessionId: string): Agent | null;

package/dist/agents/getAgentBySessionId.js

@@ -0,0 +1,17 @@
+/**
+ * Get an active agent by session ID
+ *
+ * Used for MCP tools to find "their" agent without needing the agent_id.
+ * The session_id is passed by Claude Code to hooks and can be used to
+ * correlate the hook-registered agent with subsequent MCP calls.
+ */
+export function getAgentBySessionId(db, sessionId) {
+    const stmt = db.prepare(`
+    SELECT * FROM agents
+    WHERE session_id = ?
+    AND status = 'active'
+    ORDER BY created_at DESC
+    LIMIT 1
+  `);
+    return stmt.get(sessionId) ?? null;
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,10 @@
+export type { AgentStatus, Agent, RegisterAgentInput } from './types';
+export { registerAgent } from './registerAgent';
+export { unregisterAgent } from './unregisterAgent';
+export { getAgent } from './getAgent';
+export { getActiveAgents } from './getActiveAgents';
+export { updateAgentContext } from './updateAgentContext';
+export { updateAgentTask } from './updateAgentTask';
+export { updateAgentWorktree } from './updateAgentWorktree';
+export { markAgentDead } from './markAgentDead';
+export { markAgentIdle } from './markAgentIdle';

package/dist/agents/index.js

@@ -0,0 +1,12 @@
+// Registration
+export { registerAgent } from './registerAgent';
+export { unregisterAgent } from './unregisterAgent';
+// Query
+export { getAgent } from './getAgent';
+export { getActiveAgents } from './getActiveAgents';
+// Updates
+export { updateAgentContext } from './updateAgentContext';
+export { updateAgentTask } from './updateAgentTask';
+export { updateAgentWorktree } from './updateAgentWorktree';
+export { markAgentDead } from './markAgentDead';
+export { markAgentIdle } from './markAgentIdle';

package/dist/agents/markAgentDead.d.ts

@@ -0,0 +1,6 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Mark an agent as dead (no longer responding)
+ * Also releases any tasks the agent had claimed back to pending
+ */
+export declare function markAgentDead(db: Database, agentId: string): boolean;

package/dist/agents/markAgentDead.js

@@ -0,0 +1,26 @@
+/**
+ * Mark an agent as dead (no longer responding)
+ * Also releases any tasks the agent had claimed back to pending
+ */
+export function markAgentDead(db, agentId) {
+    // Release any tasks this agent had claimed or was working on
+    const releaseTasksStmt = db.prepare(`
+    UPDATE tasks
+    SET status = 'pending',
+        claimed_by = NULL,
+        claimed_at = NULL
+    WHERE claimed_by = ?
+      AND status IN ('claimed', 'in_progress')
+  `);
+    releaseTasksStmt.run(agentId);
+    // Mark the agent as dead and clear its current task/plan references
+    const stmt = db.prepare(`
+    UPDATE agents
+    SET status = 'dead',
+        current_task_id = NULL,
+        current_plan_id = NULL
+    WHERE id = ?
+  `);
+    const result = stmt.run(agentId);
+    return result.changes > 0;
+}

package/dist/agents/markAgentIdle.d.ts

@@ -0,0 +1,5 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Mark an agent as idle (alive but not actively working)
+ */
+export declare function markAgentIdle(db: Database, agentId: string): boolean;

package/dist/agents/markAgentIdle.js

@@ -0,0 +1,12 @@
+/**
+ * Mark an agent as idle (alive but not actively working)
+ */
+export function markAgentIdle(db, agentId) {
+    const stmt = db.prepare(`
+    UPDATE agents
+    SET status = 'idle'
+    WHERE id = ?
+  `);
+    const result = stmt.run(agentId);
+    return result.changes > 0;
+}

package/dist/agents/registerAgent.d.ts

@@ -0,0 +1,6 @@
+import type { Database } from 'bun:sqlite';
+import type { Agent, RegisterAgentInput } from './types';
+/**
+ * Register a new agent in the hivemind
+ */
+export declare function registerAgent(db: Database, input?: RegisterAgentInput): Agent;

package/dist/agents/registerAgent.js

@@ -0,0 +1,29 @@
+import { makeAgentId } from '../ids/makeAgentId';
+import { parseId } from '../ids/parseId';
+import { now } from '../datetime/now';
+/**
+ * Register a new agent in the hivemind
+ */
+export function registerAgent(db, input = {}) {
+    const id = makeAgentId(input.label);
+    const parsed = parseId(id);
+    const timestamp = now();
+    const stmt = db.prepare(`
+    INSERT INTO agents (id, hex, label, status, pid, session_id, worktree_id, context_summary, created_at)
+    VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?)
+  `);
+    stmt.run(id, parsed.hex, parsed.label ?? null, input.pid ?? null, input.session_id ?? null, input.worktree_id ?? null, input.context_summary ?? null, timestamp);
+    return {
+        id,
+        hex: parsed.hex,
+        label: parsed.label ?? null,
+        status: 'active',
+        pid: input.pid ?? null,
+        session_id: input.session_id ?? null,
+        current_plan_id: null,
+        current_task_id: null,
+        worktree_id: input.worktree_id ?? null,
+        context_summary: input.context_summary ?? null,
+        created_at: timestamp,
+    };
+}

package/dist/agents/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent status values
+ */
+export type AgentStatus = 'active' | 'idle' | 'dead';
+/**
+ * Agent record as stored in DB
+ */
+export type Agent = {
+    id: string;
+    hex: string;
+    label: string | null;
+    status: AgentStatus;
+    pid: number | null;
+    session_id: string | null;
+    current_plan_id: string | null;
+    current_task_id: string | null;
+    worktree_id: string | null;
+    context_summary: string | null;
+    created_at: string;
+};
+/**
+ * Input for registering an agent
+ */
+export type RegisterAgentInput = {
+    label?: string;
+    pid?: number;
+    session_id?: string;
+    worktree_id?: string;
+    context_summary?: string;
+};

package/dist/agents/types.js

@@ -0,0 +1 @@
+export {};

package/dist/agents/unregisterAgent.d.ts

@@ -0,0 +1,5 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Remove an agent from the hivemind
+ */
+export declare function unregisterAgent(db: Database, agentId: string): boolean;

package/dist/agents/unregisterAgent.js

@@ -0,0 +1,8 @@
+/**
+ * Remove an agent from the hivemind
+ */
+export function unregisterAgent(db, agentId) {
+    const stmt = db.prepare('DELETE FROM agents WHERE id = ?');
+    const result = stmt.run(agentId);
+    return result.changes > 0;
+}

package/dist/agents/updateAgentContext.d.ts

@@ -0,0 +1,5 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Update an agent's context summary (what it knows/is working on)
+ */
+export declare function updateAgentContext(db: Database, agentId: string, contextSummary: string): boolean;

package/dist/agents/updateAgentContext.js

@@ -0,0 +1,12 @@
+/**
+ * Update an agent's context summary (what it knows/is working on)
+ */
+export function updateAgentContext(db, agentId, contextSummary) {
+    const stmt = db.prepare(`
+    UPDATE agents
+    SET context_summary = ?
+    WHERE id = ?
+  `);
+    const result = stmt.run(contextSummary, agentId);
+    return result.changes > 0;
+}

package/dist/agents/updateAgentTask.d.ts

@@ -0,0 +1,5 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Update an agent's current plan and task
+ */
+export declare function updateAgentTask(db: Database, agentId: string, planId: string | null, taskId: string | null): boolean;

package/dist/agents/updateAgentTask.js

@@ -0,0 +1,12 @@
+/**
+ * Update an agent's current plan and task
+ */
+export function updateAgentTask(db, agentId, planId, taskId) {
+    const stmt = db.prepare(`
+    UPDATE agents
+    SET current_plan_id = ?, current_task_id = ?
+    WHERE id = ?
+  `);
+    const result = stmt.run(planId, taskId, agentId);
+    return result.changes > 0;
+}

package/dist/agents/updateAgentWorktree.d.ts

@@ -0,0 +1,5 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Update an agent's worktree assignment
+ */
+export declare function updateAgentWorktree(db: Database, agentId: string, worktreeId: string | null): boolean;

package/dist/agents/updateAgentWorktree.js

@@ -0,0 +1,12 @@
+/**
+ * Update an agent's worktree assignment
+ */
+export function updateAgentWorktree(db, agentId, worktreeId) {
+    const stmt = db.prepare(`
+    UPDATE agents
+    SET worktree_id = ?
+    WHERE id = ?
+  `);
+    const result = stmt.run(worktreeId, agentId);
+    return result.changes > 0;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI commands
+ */
+export { installCommand } from './install';
+export { initCommand } from './init';
+export { statusCommand } from './status';
+export { joinCommand } from './join';
+export { registerMcpServer, isMcpRegistered } from './registerMcp';

package/dist/cli/index.js

@@ -0,0 +1,8 @@
+/**
+ * CLI commands
+ */
+export { installCommand } from './install';
+export { initCommand } from './init';
+export { statusCommand } from './status';
+export { joinCommand } from './join';
+export { registerMcpServer, isMcpRegistered } from './registerMcp';

package/dist/cli/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * hivemind init - Register a project with hivemind
+ *
+ * Run from a project directory to:
+ * 1. Create database in ~/.hivemind/<project>/
+ * 2. Set up .claude/settings.json hooks
+ * 3. Add CLAUDE.md instructions
+ */
+type InitOptions = {
+    project?: string;
+    hooks?: boolean;
+};
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};