@inixiative/hivemind 0.1.0

package/dist/ids/sanitizeLabel.js

@@ -0,0 +1,12 @@
+/**
+ * Sanitize a label for use in IDs
+ * - lowercase
+ * - remove special chars (keep alphanumeric only)
+ * - max 20 chars
+ */
+export function sanitizeLabel(label) {
+    return label
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, '')
+        .slice(0, 20);
+}

package/dist/ids/typedIds.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Typed ID utility for compile-time type safety
+ *
+ * Creates a "typed" string by adding a phantom type property.
+ * The __model property only exists at compile-time and has zero runtime cost.
+ */
+export type Id<Model> = string & {
+    readonly __model: Model;
+};
+export declare const HivemindIdType: {
+    readonly Agent: "AgentId";
+    readonly Plan: "PlanId";
+    readonly Task: "TaskId";
+    readonly Event: "EventId";
+    readonly Worktree: "WorktreeId";
+};
+export type HivemindIdType = (typeof HivemindIdType)[keyof typeof HivemindIdType];
+export type AgentId = Id<typeof HivemindIdType.Agent>;
+export type PlanId = Id<typeof HivemindIdType.Plan>;
+export type TaskId = Id<typeof HivemindIdType.Task>;
+export type EventId = Id<typeof HivemindIdType.Event>;
+export type WorktreeId = Id<typeof HivemindIdType.Worktree>;
+export declare const createId: <M extends HivemindIdType>(raw: string) => Id<M>;
+export declare const agentId: (id: string) => AgentId;
+export declare const planId: (id: string) => PlanId;
+export declare const taskId: (id: string) => TaskId;
+export declare const eventId: (id: string) => EventId;
+export declare const worktreeId: (id: string) => WorktreeId;
+export declare const isAgentId: (id: string) => id is AgentId;
+export declare const isPlanId: (id: string) => id is PlanId;
+export declare const isTaskId: (id: string) => id is TaskId;
+export declare const isEventId: (id: string) => id is EventId;
+export declare const isWorktreeId: (id: string) => id is WorktreeId;
+export type ExtractIdType<T> = T extends AgentId ? typeof HivemindIdType.Agent : T extends PlanId ? typeof HivemindIdType.Plan : T extends TaskId ? typeof HivemindIdType.Task : T extends EventId ? typeof HivemindIdType.Event : T extends WorktreeId ? typeof HivemindIdType.Worktree : never;

package/dist/ids/typedIds.js

@@ -0,0 +1,22 @@
+// Define all hivemind entity ID types
+export const HivemindIdType = {
+    Agent: 'AgentId',
+    Plan: 'PlanId',
+    Task: 'TaskId',
+    Event: 'EventId',
+    Worktree: 'WorktreeId',
+};
+// Core helper functions
+export const createId = (raw) => raw;
+// Convenience creator functions (for casting existing strings)
+export const agentId = (id) => id;
+export const planId = (id) => id;
+export const taskId = (id) => id;
+export const eventId = (id) => id;
+export const worktreeId = (id) => id;
+// Type guards for runtime validation
+export const isAgentId = (id) => id.startsWith('agt_');
+export const isPlanId = (id) => id.startsWith('pln_');
+export const isTaskId = (id) => id.startsWith('tsk_');
+export const isEventId = (id) => id.startsWith('evt_');
+export const isWorktreeId = (id) => id.startsWith('wkt_');

package/dist/ids/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Valid ID type prefixes
+ */
+export type IdType = 'agt' | 'pln' | 'tsk' | 'evt';
+/**
+ * Parsed ID components
+ */
+export type ParsedId = {
+    type: IdType;
+    hex: string;
+    seq?: string;
+    label?: string;
+    raw: string;
+};

package/dist/ids/types.js

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

package/dist/init/claudeConfig.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Claude Code configuration for hivemind
+ *
+ * When `hivemind init` runs, it sets up:
+ * 1. .claude/settings.json - SessionStart hook for auto-registration
+ * 2. .claude/CLAUDE.md - Behavioral instructions for agents
+ *
+ * Projects can customize agent behavior by adding a `## Hivemind Events`
+ * section to their root CLAUDE.md - it gets extracted and injected.
+ */
+/**
+ * Extract a markdown section by heading from content
+ * Returns the section content (including heading) or null if not found
+ */
+export declare function extractMarkdownSection(content: string, heading: string): string | null;
+/**
+ * Build the CLAUDE.md content, optionally with custom events section
+ */
+export declare function buildHivemindClaudeMd(customEventsSection?: string): string;
+/**
+ * Settings.json hooks for auto-registration
+ */
+export declare function getHivemindHooks(hivemindRoot: string): {
+    hooks: {
+        SessionStart: {
+            hooks: {
+                type: string;
+                command: string;
+            }[];
+        }[];
+    };
+};
+/**
+ * Initialize Claude Code configuration for hivemind
+ */
+export declare function initClaudeConfig(projectRoot: string, _project: string, hivemindRoot: string): {
+    created: string[];
+    updated: string[];
+};

package/dist/init/claudeConfig.js

@@ -0,0 +1,161 @@
+/**
+ * Claude Code configuration for hivemind
+ *
+ * When `hivemind init` runs, it sets up:
+ * 1. .claude/settings.json - SessionStart hook for auto-registration
+ * 2. .claude/CLAUDE.md - Behavioral instructions for agents
+ *
+ * Projects can customize agent behavior by adding a `## Hivemind Events`
+ * section to their root CLAUDE.md - it gets extracted and injected.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Default events instructions (used if project doesn't define custom ones)
+ */
+const DEFAULT_EVENTS_SECTION = `## Hivemind Events
+
+Emit concise events to coordinate. **Under 80 chars.** Map, not territory.
+
+\`\`\`
+hivemind_emit type=decision content="Redis for cache, Postgres for persistence"
+hivemind_emit type=context content="API rate limit: 100/min per key"
+hivemind_emit type=note content="003 done, starting 004"
+\`\`\`
+
+**Emit for:** architectural decisions, discoveries others need, blockers, questions.
+
+**Skip:** routine progress, obvious steps, anything verbose.`;
+/**
+ * Extract a markdown section by heading from content
+ * Returns the section content (including heading) or null if not found
+ */
+export function extractMarkdownSection(content, heading) {
+    // Match ## Heading through end of section (next ## or EOF)
+    // Split into lines and find section boundaries
+    const lines = content.split('\n');
+    const startPattern = new RegExp(`^## ${heading}\\s*$`, 'i');
+    let startIdx = -1;
+    let endIdx = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        if (startIdx === -1 && startPattern.test(lines[i])) {
+            startIdx = i;
+        }
+        else if (startIdx !== -1 && /^## /.test(lines[i])) {
+            endIdx = i;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    return lines.slice(startIdx, endIdx).join('\n').trim();
+}
+/**
+ * Build the CLAUDE.md content, optionally with custom events section
+ */
+export function buildHivemindClaudeMd(customEventsSection) {
+    const eventsSection = customEventsSection || DEFAULT_EVENTS_SECTION;
+    return `# Hivemind Agent Instructions
+
+You are part of a **hivemind** - a coordinated group of Claude agents working together.
+
+## Automatic Behaviors
+
+**Your todos are automatically synced to hivemind.** When you use TodoWrite, the hivemind watcher detects changes and syncs them to a shared plan. Other agents can see your progress in real-time.
+
+Your lifecycle is tracked by PID - no heartbeats needed. When you exit, hivemind automatically marks you as inactive.
+
+## MCP Tools
+
+- \`hivemind_status\` - View active agents, plans, and recent activity
+- \`hivemind_query\` - See what other agents are doing
+- \`hivemind_emit\` - Share notes, decisions, questions with other agents
+
+${eventsSection}
+
+## Coordination Protocol
+
+1. **Before starting work**: Check \`hivemind_status\` to see what others are doing
+2. **When making decisions**: Use \`hivemind_emit\` with type "decision" to share
+3. **When blocked**: Use \`hivemind_emit\` with type "question" to ask for help
+4. **Just work**: Your todos sync automatically - focus on the task!
+`;
+}
+/**
+ * Settings.json hooks for auto-registration
+ */
+export function getHivemindHooks(hivemindRoot) {
+    return {
+        hooks: {
+            SessionStart: [
+                {
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: `bun run ${hivemindRoot}/src/hooks/sessionStart.ts`,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
+/**
+ * Initialize Claude Code configuration for hivemind
+ */
+export function initClaudeConfig(projectRoot, _project, hivemindRoot) {
+    const claudeDir = join(projectRoot, '.claude');
+    const settingsPath = join(claudeDir, 'settings.json');
+    const claudeMdPath = join(claudeDir, 'CLAUDE.md');
+    const projectClaudeMdPath = join(projectRoot, 'CLAUDE.md');
+    const created = [];
+    const updated = [];
+    // Ensure .claude directory exists
+    if (!existsSync(claudeDir)) {
+        mkdirSync(claudeDir, { recursive: true });
+        created.push('.claude/');
+    }
+    // Create or update settings.json
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Invalid JSON, start fresh
+        }
+    }
+    const hooks = getHivemindHooks(hivemindRoot);
+    const existingHooks = settings.hooks;
+    if (!existingHooks?.SessionStart) {
+        settings.hooks = { ...existingHooks, ...hooks.hooks };
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        updated.push('.claude/settings.json');
+    }
+    // Extract custom events section from project's root CLAUDE.md (if exists)
+    let customEventsSection;
+    if (existsSync(projectClaudeMdPath)) {
+        const projectClaudeMd = readFileSync(projectClaudeMdPath, 'utf-8');
+        const extracted = extractMarkdownSection(projectClaudeMd, 'Hivemind Events');
+        if (extracted) {
+            customEventsSection = extracted;
+        }
+    }
+    // Build the hivemind instructions (with custom or default events section)
+    const hivemindClaudeMd = buildHivemindClaudeMd(customEventsSection);
+    // Create or update .claude/CLAUDE.md
+    if (!existsSync(claudeMdPath)) {
+        writeFileSync(claudeMdPath, hivemindClaudeMd);
+        created.push('.claude/CLAUDE.md');
+    }
+    else {
+        // Check if hivemind instructions are already there
+        const existing = readFileSync(claudeMdPath, 'utf-8');
+        if (!existing.includes('Hivemind Agent Instructions')) {
+            // Append hivemind instructions
+            writeFileSync(claudeMdPath, existing + '\n\n' + hivemindClaudeMd);
+            updated.push('.claude/CLAUDE.md');
+        }
+    }
+    return { created, updated };
+}

package/dist/llm/extractTasks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Task extraction from plan markdown
+ *
+ * Two modes:
+ * 1. Fast regex parsing (default) - handles common formats instantly
+ * 2. LLM extraction (optional) - for complex plans, user-triggered
+ */
+export type ExtractedTask = {
+    title: string;
+    description?: string;
+    status: 'pending' | 'in_progress' | 'done';
+};
+/**
+ * Fast regex-based task extraction
+ * Handles common markdown patterns:
+ * - [ ] pending task
+ * - [x] completed task
+ * - [ ] ~in progress~ (strikethrough = in progress)
+ * ### 1. Numbered section headers
+ * 1. Numbered list items
+ */
+export declare function extractTasksWithRegex(markdown: string): ExtractedTask[];
+/**
+ * LLM-based task extraction (slower, more accurate for complex plans)
+ * Use extractTasksWithRegex() for real-time sync
+ */
+export declare function extractTasksWithLLM(markdown: string): Promise<ExtractedTask[]>;
+export declare const extractTasksFromPlan: typeof extractTasksWithRegex;

package/dist/llm/extractTasks.js

@@ -0,0 +1,108 @@
+/**
+ * Task extraction from plan markdown
+ *
+ * Two modes:
+ * 1. Fast regex parsing (default) - handles common formats instantly
+ * 2. LLM extraction (optional) - for complex plans, user-triggered
+ */
+import { spawn } from 'child_process';
+/**
+ * Fast regex-based task extraction
+ * Handles common markdown patterns:
+ * - [ ] pending task
+ * - [x] completed task
+ * - [ ] ~in progress~ (strikethrough = in progress)
+ * ### 1. Numbered section headers
+ * 1. Numbered list items
+ */
+export function extractTasksWithRegex(markdown) {
+    const tasks = [];
+    const lines = markdown.split('\n');
+    for (const line of lines) {
+        // Checkbox tasks: - [ ] task or - [x] task
+        const checkboxMatch = line.match(/^[\s]*[-*]\s*\[([ xX])\]\s*(.+)$/);
+        if (checkboxMatch) {
+            const isDone = checkboxMatch[1].toLowerCase() === 'x';
+            const title = checkboxMatch[2].trim();
+            tasks.push({
+                title: title.slice(0, 100),
+                status: isDone ? 'done' : 'pending',
+            });
+            continue;
+        }
+        // Numbered section headers: ### 1. Task name or ## 1. Task name
+        const sectionMatch = line.match(/^#{2,4}\s*\d+\.\s*(.+)$/);
+        if (sectionMatch) {
+            const title = sectionMatch[1].trim();
+            // Skip if it looks like a file path or code
+            if (!title.includes('/') && !title.includes('`')) {
+                tasks.push({
+                    title: title.slice(0, 100),
+                    status: 'pending',
+                });
+            }
+            continue;
+        }
+        // Top-level numbered list: 1. Task item (only at start of line)
+        const numberedMatch = line.match(/^\d+\.\s+([A-Z][^.]+)$/);
+        if (numberedMatch) {
+            const title = numberedMatch[1].trim();
+            tasks.push({
+                title: title.slice(0, 100),
+                status: 'pending',
+            });
+            continue;
+        }
+    }
+    return tasks;
+}
+/**
+ * LLM-based task extraction (slower, more accurate for complex plans)
+ * Use extractTasksWithRegex() for real-time sync
+ */
+export async function extractTasksWithLLM(markdown) {
+    const MAX_LENGTH = 4000;
+    const truncated = markdown.length > MAX_LENGTH
+        ? markdown.slice(0, MAX_LENGTH) + '\n\n[... truncated]'
+        : markdown;
+    const prompt = `I'm building a multi-agent coordination system. Extract implementation tasks from this plan as JSON array:
+[{"title": "Task name", "status": "pending"}]
+
+Plan:
+${truncated}`;
+    return new Promise((resolve, reject) => {
+        const proc = spawn('claude', ['--print', '--output-format', 'text', prompt], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (d) => { stdout += d.toString(); });
+        proc.stderr.on('data', (d) => { stderr += d.toString(); });
+        proc.on('error', (err) => reject(new Error(`spawn failed: ${err.message}`)));
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`claude exited ${code}: ${stderr || stdout}`));
+                return;
+            }
+            try {
+                const match = stdout.match(/```(?:json)?\s*([\s\S]*?)```/) || stdout.match(/\[[\s\S]*\]/);
+                const jsonStr = match ? (match[1] || match[0]).trim() : null;
+                if (!jsonStr) {
+                    resolve([]);
+                    return;
+                }
+                const tasks = JSON.parse(jsonStr);
+                resolve(tasks.map((t) => ({
+                    title: String(t.title || '').slice(0, 100),
+                    description: t.description,
+                    status: ['pending', 'in_progress', 'done'].includes(t.status) ? t.status : 'pending',
+                })).filter((t) => t.title));
+            }
+            catch (err) {
+                reject(new Error(`JSON parse failed: ${err}`));
+            }
+        });
+    });
+}
+// Default export uses fast regex
+export const extractTasksFromPlan = extractTasksWithRegex;

package/dist/llm/index.d.ts

@@ -0,0 +1,2 @@
+export { extractTasksFromPlan, type ExtractedTask } from './extractTasks';
+export { reconcileTasks, type ReconcileResult } from './reconcileTasks';

package/dist/llm/index.js

@@ -0,0 +1,2 @@
+export { extractTasksFromPlan } from './extractTasks';
+export { reconcileTasks } from './reconcileTasks';

package/dist/llm/reconcileTasks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Reconcile extracted tasks with database
+ * Plan file is source of truth - DB reflects what's in the file
+ */
+import type { Database } from 'bun:sqlite';
+import type { Task } from '../tasks/types';
+import type { ExtractedTask } from './extractTasks';
+export type ReconcileResult = {
+    created: Task[];
+    updated: Task[];
+    removed: Task[];
+    unchanged: number;
+};
+/**
+ * Reconcile extracted tasks with existing tasks in a plan
+ *
+ * - Tasks in file but not DB → create
+ * - Tasks in DB but not file → mark done (removed)
+ * - Tasks in both → update status if changed
+ */
+export declare function reconcileTasks(db: Database, planId: string, extracted: ExtractedTask[]): ReconcileResult;

package/dist/llm/reconcileTasks.js

@@ -0,0 +1,82 @@
+/**
+ * Reconcile extracted tasks with database
+ * Plan file is source of truth - DB reflects what's in the file
+ */
+import { createTask } from '../tasks/createTask';
+import { getTasksByPlan } from '../tasks/getTasksByPlan';
+import { completeTask } from '../tasks/completeTask';
+import { startTask } from '../tasks/startTask';
+import { emit } from '../events/emit';
+/**
+ * Reconcile extracted tasks with existing tasks in a plan
+ *
+ * - Tasks in file but not DB → create
+ * - Tasks in DB but not file → mark done (removed)
+ * - Tasks in both → update status if changed
+ */
+export function reconcileTasks(db, planId, extracted) {
+    const existing = getTasksByPlan(db, planId);
+    const existingByTitle = new Map(existing.map((t) => [t.title.toLowerCase(), t]));
+    const extractedTitles = new Set(extracted.map((t) => t.title.toLowerCase()));
+    const created = [];
+    const updated = [];
+    const removed = [];
+    let unchanged = 0;
+    // Process extracted tasks
+    for (const ext of extracted) {
+        const titleKey = ext.title.toLowerCase();
+        const existingTask = existingByTitle.get(titleKey);
+        if (existingTask) {
+            // Task exists - check if status changed
+            const dbStatus = existingTask.status;
+            const extStatus = ext.status;
+            // Map extracted status to DB status
+            let needsUpdate = false;
+            if (extStatus === 'done' && dbStatus !== 'done') {
+                completeTask(db, existingTask.id);
+                updated.push({ ...existingTask, status: 'done' });
+                needsUpdate = true;
+            }
+            else if (extStatus === 'in_progress' && dbStatus !== 'in_progress') {
+                startTask(db, existingTask.id);
+                updated.push({ ...existingTask, status: 'in_progress' });
+                needsUpdate = true;
+            }
+            if (!needsUpdate) {
+                unchanged++;
+            }
+        }
+        else {
+            // New task - create it
+            const task = createTask(db, {
+                plan_id: planId,
+                title: ext.title,
+                description: ext.description,
+            });
+            // Emit task:create system event
+            emit(db, {
+                type: 'task:create',
+                task_id: task.id,
+                plan_id: planId,
+                content: `Task created: ${task.title}`,
+            });
+            // Set initial status if not pending
+            if (ext.status === 'in_progress') {
+                startTask(db, task.id);
+            }
+            else if (ext.status === 'done') {
+                completeTask(db, task.id);
+            }
+            created.push(task);
+        }
+    }
+    // Tasks in DB but not in file → mark as done (removed from plan)
+    for (const task of existing) {
+        const titleKey = task.title.toLowerCase();
+        if (!extractedTitles.has(titleKey) && task.status !== 'done') {
+            completeTask(db, task.id);
+            removed.push({ ...task, status: 'done' });
+        }
+    }
+    return { created, updated, removed, unchanged };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { setupTool, executeSetup, registerTool, executeRegister, emitEventTool, executeEmitEvent, queryTool, executeQuery, statusTool, executeStatus, resetTool, executeReset, claimTaskTool, executeClaimTask, startTaskTool, executeStartTask, completeTaskTool, executeCompleteTask, eventsTool, executeEvents, worktreeCleanupTool, executeWorktreeCleanup, } from './tools/index';
+const server = new Server({
+    name: 'hivemind',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            setupTool,
+            registerTool,
+            statusTool,
+            eventsTool,
+            emitEventTool,
+            queryTool,
+            claimTaskTool,
+            startTaskTool,
+            completeTaskTool,
+            worktreeCleanupTool,
+            resetTool,
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case 'hivemind_setup':
+                result = executeSetup(args);
+                break;
+            case 'hivemind_register':
+                result = executeRegister(args);
+                break;
+            case 'hivemind_emit':
+                result = executeEmitEvent(args);
+                break;
+            case 'hivemind_query':
+                result = executeQuery(args);
+                break;
+            case 'hivemind_status':
+                result = executeStatus(args);
+                break;
+            case 'hivemind_reset':
+                result = executeReset(args);
+                break;
+            case 'hivemind_claim_task':
+                result = executeClaimTask(args);
+                break;
+            case 'hivemind_start_task':
+                result = executeStartTask(args);
+                break;
+            case 'hivemind_complete_task':
+                result = executeCompleteTask(args);
+                break;
+            case 'hivemind_events':
+                result = executeEvents(args);
+                break;
+            case 'hivemind_worktree_cleanup':
+                result = executeWorktreeCleanup(args);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: message }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);