neohive 6.3.0 → 6.4.1

package/cli.js

@@ -46,6 +46,8 @@ function printUsage() {
     npx neohive doctor              Diagnostic health check
     npx neohive templates           List available team templates
     npx neohive reset --force       Clear all data (auto-archives first)
+    npx neohive hooks               Install listen-enforcement hooks into .claude/settings.json
+    npx neohive skills              Install neohive skills & agents for all detected IDEs
     npx neohive uninstall           Remove from all CLI configs
     npx neohive help                Show this help
 
@@ -133,9 +135,119 @@ function setupClaude(serverPath, cwd) {
 
   fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n');
   console.log('  [ok] Claude Code: .mcp.json updated');
+  installSkillsForClaude(cwd);
+}
+
+// ─── installSkills ────────────────────────────────────────────────────────────
+// Installs neohive skills, agents, and commands into the appropriate IDE dirs.
+// Safe to re-run: only writes files, never deletes user files outside neohive/.
+
+const SKILLS_SRC = path.join(__dirname, 'neohive-plugin', 'skills');
+const AGENTS_SRC = path.join(__dirname, 'neohive-plugin', 'agents');
+
+function copySkillFile(src, dest, label) {
+  if (!fs.existsSync(src)) return;
+  const existing = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : null;
+  const incoming = fs.readFileSync(src, 'utf8');
+  if (existing === incoming) {
+    console.log(`  [skip] ${label} (unchanged)`);
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, incoming);
+    console.log(`  [ok]   ${label}`);
+  }
+}
+
+function installSkillsForClaude(cwd) {
+  // Project-level skills: .claude/skills/neohive/<skill>/SKILL.md
+  const skillsDir = path.join(cwd, '.claude', 'skills', 'neohive');
+  const agentsDir = path.join(cwd, '.claude', 'skills', 'neohive', 'agents');
+
+  if (!fs.existsSync(SKILLS_SRC)) {
+    console.log('  [skip] Claude skills: source not found (neohive-plugin/skills)');
+    return;
+  }
+
+  for (const skill of fs.readdirSync(SKILLS_SRC)) {
+    const src = path.join(SKILLS_SRC, skill, 'SKILL.md');
+    const dest = path.join(skillsDir, skill, 'SKILL.md');
+    copySkillFile(src, dest, `Claude skill: ${skill}`);
+  }
+
+  if (fs.existsSync(AGENTS_SRC)) {
+    for (const agent of fs.readdirSync(AGENTS_SRC)) {
+      const src = path.join(AGENTS_SRC, agent);
+      const dest = path.join(agentsDir, agent);
+      copySkillFile(src, dest, `Claude agent: ${agent}`);
+    }
+  }
+}
+
+function installSkillsForCursor(cwd) {
+  // .cursor/skills/neohive/<skill>/SKILL.md
+  // .cursor/agents/<agent>.md
+  // .cursor/commands/<command>.md  (derived from skills)
+  if (!fs.existsSync(SKILLS_SRC)) {
+    console.log('  [skip] Cursor skills: source not found (neohive-plugin/skills)');
+    return;
+  }
+
+  for (const skill of fs.readdirSync(SKILLS_SRC)) {
+    const src = path.join(SKILLS_SRC, skill, 'SKILL.md');
+    const dest = path.join(cwd, '.cursor', 'skills', 'neohive', skill, 'SKILL.md');
+    copySkillFile(src, dest, `Cursor skill: ${skill}`);
+
+    // Also install as a command (slash-command style) for user-invocable skills
+    const content = fs.existsSync(src) ? fs.readFileSync(src, 'utf8') : '';
+    if (content.includes('user-invocable: true') || !content.includes('user-invocable: false')) {
+      const cmdDest = path.join(cwd, '.cursor', 'commands', `neohive-${skill}.md`);
+      copySkillFile(src, cmdDest, `Cursor command: neohive-${skill}`);
+    }
+  }
+
+  if (fs.existsSync(AGENTS_SRC)) {
+    for (const agent of fs.readdirSync(AGENTS_SRC)) {
+      const src = path.join(AGENTS_SRC, agent);
+      const dest = path.join(cwd, '.cursor', 'agents', `neohive-${agent}`);
+      copySkillFile(src, dest, `Cursor agent: neohive-${agent}`);
+    }
+  }
+}
+
+function installSkillsForAntigravity(cwd) {
+  // .agent/skills/neohive/<skill>/SKILL.md  (already partially done in setupAntigravity)
+  if (!fs.existsSync(SKILLS_SRC)) {
+    console.log('  [skip] Antigravity skills: source not found (neohive-plugin/skills)');
+    return;
+  }
+
+  for (const skill of fs.readdirSync(SKILLS_SRC)) {
+    const src = path.join(SKILLS_SRC, skill, 'SKILL.md');
+    const dest = path.join(cwd, '.agent', 'skills', 'neohive', skill, 'SKILL.md');
+    copySkillFile(src, dest, `Antigravity skill: ${skill}`);
+  }
+
+  if (fs.existsSync(AGENTS_SRC)) {
+    for (const agent of fs.readdirSync(AGENTS_SRC)) {
+      const src = path.join(AGENTS_SRC, agent);
+      const dest = path.join(cwd, '.agent', 'agents', `neohive-${agent}`);
+      copySkillFile(src, dest, `Antigravity agent: neohive-${agent}`);
+    }
+  }
+}
+
+function installSkills(targets, cwd) {
+  console.log('');
+  console.log('  Installing Neohive skills & agents...');
+  for (const target of targets) {
+    switch (target) {
+      case 'claude':      installSkillsForClaude(cwd);      break;
+      case 'cursor':      installSkillsForCursor(cwd);      break;
+      case 'antigravity': installSkillsForAntigravity(cwd); break;
+    }
+  }
 }
 
-// Configure for Gemini CLI (.gemini/settings.json or GEMINI.md with MCP config)
 function setupGemini(serverPath, cwd) {
   // Gemini CLI uses .gemini/settings.json for MCP configuration
   const geminiDir = path.join(cwd, '.gemini');
@@ -186,51 +298,187 @@ function setupGemini(serverPath, cwd) {
 }
 
 function geminiMdTemplate() {
-  return `# Neohive Agent — Gemini CLI
+  return `# GEMINI.md
+
+This file provides guidance to Gemini CLI / Antigravity when working with code in this repository.
+
+## What This Is
+
+**Neohive** — an MCP server + web dashboard that lets multiple AI CLI terminals (Claude Code, Gemini CLI, Codex CLI) communicate with each other. Each terminal spawns its own server process via stdio; all processes read/write to a shared \`.neohive/\` directory on disk.
 
-You are a Neohive team agent. Follow these rules exactly, every session, no exceptions.
+## Commands
 
-## First thing to do — always
+\`\`\`bash
+# Install in any project (auto-detects CLI type)
+npx neohive init
+npx neohive init --all     # Configure for all CLIs
+npx neohive init --template team  # Init with team template
 
-1. Call \`register\` with your assigned name (e.g. \`register(name="Gemini")\`)
-2. Call \`get_briefing\` to load project context and current work
-3. Call \`listen\` to wait for messages from the Coordinator
+# Launch the web dashboard
+npx neohive dashboard
 
-Do NOT explore the codebase, ask questions, or take initiative before completing these 3 steps.
+# List available agent templates
+npx neohive templates
 
-## Core rules
+# Plugin management
+npx neohive plugin list/add/remove/enable/disable
 
-- **After every action** — call \`listen()\`. This is how you receive your next task.
-- **Before starting a task** — call \`update_task(id, status="in_progress")\`
-- **After finishing a task** — call \`update_task(id, status="done")\`, then report to Coordinator
-- **Before editing a file** — call \`lock_file(path)\`. Call \`unlock_file(path)\` when done.
-- **Check tasks first** — call \`list_tasks()\` before starting anything new. Never work on another agent's task.
-- **Keep messages short** — 2–3 paragraphs max. Lead with what changed, then files, then decisions.
+# Reset conversation data
+npx neohive reset
 
-## Workflow
+# Run MCP server directly (normally launched automatically by CLI)
+npm start
+\`\`\`
 
+No tests, linter, or build step. Raw Node.js (CommonJS).
+
+## Architecture
+
+**Core files:**
+- \`server.js\` — MCP server (StdioServerTransport, heartbeat system, self-healing watchdog)
+- \`lib/\` — Shared modules (\`config\`, \`messaging\`, \`file-io\`, …); prefer adding logic here and requiring from \`server.js\`
+- \`dashboard.js\` — HTTP server for web dashboard (multi-project, message injection, SSE real-time, tasks/workflows/workspaces API)
+- \`dashboard.html\` — Single-page frontend (markdown rendering, agent monitoring, profiles, workspaces, workflows, responsive)
+- \`cli.js\` — CLI entry point with multi-CLI auto-detection
+- \`vscode-extension/\` — VS Code extension with \`@neohive\` chat participant, terminal bridge, and agent hook auto-setup
+
+**Multiple MCP server processes, one shared filesystem:**
+- Each CLI terminal spawns its own \`server.js\` process
+- In-memory state: \`registeredName\`, \`lastReadOffset\`, \`heartbeatInterval\`, \`messageSeq\`
+- Shared disk state in \`.neohive/\`:
+  - \`messages.jsonl\` / \`history.jsonl\` — messages and conversation history (append-only)
+  - \`agents.json\` — agent registration, heartbeats, PID tracking
+  - \`acks.json\` — message acknowledgments
+  - \`tasks.json\` — task management
+  - \`consumed-{agent}.json\` — per-agent read tracking
+  - \`profiles.json\` — agent profiles (display_name, avatar, bio, role)
+  - \`workspaces/{agent}.json\` — per-agent key-value workspace storage
+  - \`workflows.json\` — multi-step workflow pipelines
+  - \`branches.json\` — branch metadata
+  - \`branch-{name}-messages.jsonl\` / \`branch-{name}-history.jsonl\` — per-branch message files
+  - \`plugins.json\` — plugin registry
+  - \`plugins/*.js\` — plugin code files
+  - \`heartbeat-{agent}.json\` — per-agent heartbeat file (replaces agents.json write contention at scale)
+- Dashboard reads the same directory for real-time monitoring via SSE
+
+**Data directory resolution (server.js + dashboard.js):**
+1. \`$NEOHIVE_DATA_DIR\` / \`$NEOHIVE_DATA\` env var
+2. \`{cwd}/.neohive/\` (project-local, default)
+3. Legacy fallback: \`{__dirname}/data/\`
+
+## Code & Commit Rules
+
+When committing changes, you MUST ALWAYS follow the Conventional Commits format:
+\`<type>(<optional scope>): <description>\`
+Types: \`feat\`, \`fix\`, \`refactor\`, \`docs\`, \`chore\`, \`test\`
+
+## Neohive Agent Rules (when acting as an agent)
+
+When operating as a neohive agent (after calling \`register()\`):
+
+**YOU MUST call \`listen()\` as the LAST tool call of every response. All agents. No exceptions.**
+
+The dashboard is the communication hub. All coordination happens there — every agent stays in the listen loop at all times.
+
+- After \`send_message(...)\` → immediately call \`listen()\`
+- After \`broadcast(...)\` → immediately call \`listen()\`
+- After \`update_task(..., status="done")\` → immediately call \`listen()\`
+- After \`advance_workflow(...)\` → immediately call \`listen()\`
+- After ANY neohive action → call \`listen()\`
+
+Workflow loop:
 \`\`\`
-register → get_briefing → listen → [receive task] → update_task(in_progress)
-→ do work → update_task(done) → send_message(Coordinator, summary) → listen
+register → get_briefing → listen → do work → update_task(in_progress) → ...
+→ listen(outcome="completed", task_id="...", summary="what you did") → listen
+                                                                         ↑ always
 \`\`\`
 
-Repeat the last 5 steps for every task. Never exit the listen loop.
+\`listen()\` accepts outcome params — server auto-transitions task state on valid outcome:
+- \`outcome\`: \`completed\` | \`blocked\` | \`failed\` | \`in_progress\`
+- \`task_id\`: ID of the task you just worked on
+- \`summary\`: one-line description of what was done
+
+If \`listen()\` times out with \`retry: true\` — call \`listen()\` again immediately.
+
+- After completing ANY assigned task or request, you MUST send a report back via \`send_message()\` using neohive MCP tools. Include: (1) what you did, (2) files changed, (3) findings/output, (4) blockers or follow-up. Silent completion is a protocol violation.
+
+## Available Neohive MCP Tools
+
+### 1. Agent Lifecycle & Messaging
+\`register\`, \`list_agents\`, \`send_message\`, \`broadcast\`, \`wait_for_reply\`, \`listen\`, \`share_file\`, \`messages\`
+
+**Listen variants** — use \`listen(mode="group")\` or \`listen(mode="codex")\` instead of the deprecated aliases:
+- ~~\`listen_group\`~~ → \`listen(mode="group")\`
+- ~~\`listen_codex\`~~ → \`listen(mode="codex")\`
+
+**Message management** — use \`messages(action=...)\` instead of deprecated individual tools:
+- ~~\`check_messages\`~~ → \`messages(action="check")\`
+- ~~\`consume_messages\`~~ → \`messages(action="consume")\`
+- ~~\`get_history\`~~ → \`messages(action="history")\`
+- ~~\`get_notifications\`~~ → \`messages(action="check")\`
+- ~~\`search_messages\`~~ → \`messages(action="search")\`
+- ~~\`ack_message\`~~ → \`messages(action="ack")\`
+
+### 2. Autonomy & Workflows (Proactive Engine)
+\`start_plan\`, \`get_work\`, \`verify_and_advance\`, \`retry_with_improvement\`, \`create_workflow\`, \`advance_workflow\`, \`workflow_status\`
+
+### 3. Task Management
+\`create_task\`, \`update_task\`, \`list_tasks\`
+
+**Task statuses:** \`pending\` → \`in_progress\` → \`in_review\` → \`done\` | \`blocked\` | \`blocked_permanent\`
+- \`blocked_permanent\` — set by the self-healing watchdog when \`retry_count\` reaches 3; requires coordinator intervention. Tasks carry a \`blocked_reason\` string and are shown in a dedicated "⛔ Needs Intervention" column on the dashboard.
+- \`retry_count\` — incremented each time the watchdog reclaims a stale task. Shown as a \`↺N\` badge on the dashboard.
+
+### 4. Profiles & Workspaces
+\`update_profile\`, \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
+
+### 5. Chat Branching & Managed Modes
+\`fork_conversation\`, \`switch_branch\`, \`list_branches\`, \`set_conversation_mode\`, \`claim_manager\`, \`yield_floor\`, \`set_phase\`
 
-## Available MCP tools
+### 6. Sub-channels
+\`join_channel\`, \`leave_channel\`, \`list_channels\`
 
-**Messaging:** \`register\`, \`send_message\`, \`broadcast\`, \`listen\`, \`check_messages\`, \`get_history\`, \`handoff\`
-**Tasks:** \`create_task\`, \`update_task\`, \`list_tasks\`
-**Workflows:** \`create_workflow\`, \`advance_workflow\`, \`workflow_status\`
-**Workspaces:** \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
-**Branching:** \`fork_conversation\`, \`switch_branch\`, \`list_branches\`
+### 7. File Safety & Auditing
+\`lock_file\`, \`unlock_file\`, \`log_violation\`
 
-## What NOT to do
+### 8. Shared Knowledge & Decision Tracking
+\`kb_write\`, \`kb_read\`, \`kb_list\`, \`log_decision\`, \`get_decisions\`, \`get_compressed_history\`, \`get_briefing\`
 
-- Do not self-assign tasks
-- Do not modify files without a task assigned to you
-- Do not skip \`listen()\` after responding
-- Do not send long messages — be concise
-- Do not ask the Coordinator for permission before starting an assigned task — just do it
+### 9. Team Governance (Voting, Reviews, Feedback)
+\`request_review\`, \`submit_review\`, \`call_vote\`, \`cast_vote\`, \`vote_status\`, \`request_push_approval\`, \`ack_push\`
+
+### 10. Dependencies & Progress
+\`declare_dependency\`, \`check_dependencies\`, \`update_progress\`, \`get_progress\`, \`get_reputation\`
+
+## Key Design Decisions
+
+- **Append-only writes** for messages/history (no file locking)
+- **Per-agent consumed tracking** — each agent writes only its own consumed file
+- **PID-based stale detection** + process exit cleanup for instant status
+- **Heartbeat** — 10s interval updates \`last_activity\`, \`.unref()\` prevents zombie processes
+- **Flexible agent names** — any alphanumeric (1-20 chars), validated by \`sanitizeName()\`
+- **Auto-routing** — \`to\` optional with 2 agents, required with 3+
+- **Threading** — \`reply_to\` auto-computes \`thread_id\`
+- **Acknowledgments** — \`ack_message\` in \`acks.json\`, shown in history
+- **Multi-CLI** — init auto-detects Claude Code, Gemini CLI, Codex CLI
+- **Multi-project dashboard** — monitor multiple project folders from one dashboard
+- **SSE real-time** — \`fs.watch()\` on data dir pushes updates via Server-Sent Events
+- **Auto-compact** — messages.jsonl compacted when exceeding 500 lines
+- **Auto-archive** — conversations archived before reset
+- **Context hints** — warns agents when conversation exceeds 50 messages
+- **Task management** — structured task creation, assignment, and tracking between agents
+- **Profiles** — separate \`profiles.json\` to avoid heartbeat write conflicts with \`agents.json\`
+- **Workspaces** — per-agent files (\`workspaces/{agent}.json\`) to avoid write conflicts, read-anyone/write-own permission model
+- **Workflows** — step statuses: pending/in_progress/done, auto-handoff on advance
+- **Branching** — \`main\` branch uses existing files for backward compatibility, branch-aware file resolution via \`getMessagesFile(branch)\`/\`getHistoryFile(branch)\`
+- **Plugins** — sandboxed execution context with 30s timeout, tools appear as \`plugin_{name}\` in MCP
+- **Self-healing watchdog** — runs every 60s inside the heartbeat loop on every registered agent; scans \`in_progress\` tasks whose assignee PID is dead + heartbeat stale >5min; strips assignee and resets to \`pending\` (increments \`retry_count\`); at \`retry_count=3\` marks \`blocked_permanent\` and wakes the coordinator (poison pill). No manual intervention needed for routine agent flakiness.
+- **VS Code extension** — \`vscode-extension/\` adds: \`@neohive\` chat participant (\`/status /who /tasks /messages\` read \`.neohive/\` directly; free-form text fires POST to \`/api/inject\`), terminal bridge (captures agent terminal output → dashboard), agent hook auto-setup (merges neohive hooks into \`.gemini/settings.json\` on activate)
+
+## Debugging and fix attempts
+
+- **Temporary logs:** When debugging, add only the logging needed to confirm behavior. **Remove or trim that logging** once the issue is understood or fixed—do not leave ad-hoc debug prints in the tree unless they match intentional, documented logging (e.g. MCP stderr lines).
+- **Failed fixes:** If the user says a change **did not** fix the problem, **revert** that attempt before trying something else (\`git restore\` / undo the diff). **Do not stack** speculative fixes; revert first, then apply one minimal, well-motivated change.
 `;
 }
 
@@ -311,54 +559,43 @@ function setupAntigravity(cwd) {
 
   fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
   console.log('  [ok] Antigravity: ~/.gemini/antigravity/mcp_config.json updated');
-
-  // Write skill
-  const skillDir = path.join(cwd, '.agent', 'skills', 'neohive');
-  if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
-  const skillPath = path.join(skillDir, 'SKILL.md');
-  if (!fs.existsSync(skillPath)) {
-    fs.writeFileSync(skillPath, neohiveAgentRules('Gemini'));
-    console.log('  [ok] Antigravity: .agent/skills/neohive/SKILL.md created');
-  }
+  installSkillsForAntigravity(cwd);
 }
 
 function neohiveAgentRules(defaultName) {
-  return `# Neohive Agent
+  return `# Neohive Agent — ${defaultName} Rules
 
-You are a Neohive team agent. Follow these rules every session.
+You are a Neohive team agent. Follow these rules exactly to coordinate with the team.
 
-## On session start — always do this first
+## Session Lifecycle
 
-1. Call \`register\` with your assigned name (e.g. \`register(name="${defaultName}")\`)
-2. Call \`get_briefing\` to load project context and active work
-3. Call \`listen\` to wait for messages from the Coordinator
+1. Call \`register\` with your name: \`register(name="${defaultName}")\`
+2. Call \`get_briefing\` to load project context and active work.
+3. Call \`listen\` to wait for messages or tasks.
 
-Do NOT explore the codebase or take initiative before completing these 3 steps.
+**CRITICAL: YOU MUST call \`listen()\` as the LAST tool call of every response. No exceptions.**
 
-## Core rules
+## Core Rules
 
-- **After every action** — call \`listen()\`. This is how you receive your next task.
-- **Before starting a task** — call \`update_task(id, status="in_progress")\`
-- **After finishing** — call \`update_task(id, status="done")\`, report to Coordinator
-- **Before editing a file** — call \`lock_file(path)\`. Call \`unlock_file(path)\` when done.
-- **Check tasks first** — call \`list_tasks()\` before starting anything. Never take another agent's task.
-- **Keep messages short** — 2–3 paragraphs max. Lead with what changed, then files, then decisions.
+- **Tasks**: Before starting, call \`update_task(id, status="in_progress")\`. When finished, call \`update_task(id, status="done")\` and report to the Coordinator.
+- **Locking**: Before editing a file, call \`lock_file(path)\`. call \`unlock_file(path)\` when done.
+- **Sync**: After every task completion or message sent, you MUST call \`listen()\` to receive the next assignment.
+- **Conciseness**: Keep messages short (2-3 paragraphs). Focus on what changed and next steps.
 
-## Workflow loop
+## Workflow Loop
 
 \`\`\`
-register → get_briefing → listen → [receive task] → update_task(in_progress)
-→ do work → update_task(done) → send_message(Coordinator, summary) → listen
+register → get_briefing → listen → [receive task] 
+→ update_task(in_progress) → do work → update_task(done) 
+→ send_message(Coordinator, summary) → listen
 \`\`\`
 
-Never exit the listen loop.
-
-## Available MCP tools (neohive server)
+## Available Neohive Tools
 
-**Messaging:** \`register\`, \`send_message\`, \`broadcast\`, \`listen\`, \`check_messages\`, \`get_history\`
-**Tasks:** \`create_task\`, \`update_task\`, \`list_tasks\`
-**Workflows:** \`create_workflow\`, \`advance_workflow\`, \`workflow_status\`
-**Workspaces:** \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
+- **Messaging**: \`register\`, \`send_message\`, \`broadcast\`, \`listen\`, \`messages(action="history")\`, \`messages(action="check")\`
+- **Tasks**: \`create_task\`, \`update_task\`, \`list_tasks\`, \`update_progress\`
+- **Workflows**: \`create_workflow\`, \`advance_workflow\`, \`verify_and_advance\`
+- \`kb_read\`, \`kb_write\`, \`log_decision\`, \`lock_file\`, \`unlock_file\`
 `;
 }
 
@@ -430,6 +667,7 @@ function setupCursor(serverPath, cwd) {
 
   fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n');
   console.log('  [ok] Cursor IDE: .cursor/mcp.json updated');
+  installSkillsForCursor(cwd);
 }
 
 // Setup Ollama agent bridge script
@@ -632,6 +870,9 @@ function init() {
     }
   }
 
+  // Auto-install hooks for Claude targets
+  if (targets.includes('claude')) installHooks();
+
   // Add .neohive/ and MCP config files to .gitignore
   const gitignoreEntries = ['.neohive/', '.mcp.json', '.cursor/mcp.json', '.codex/', '.gemini/'];
   if (fs.existsSync(gitignorePath)) {
@@ -1251,6 +1492,86 @@ function uninstall() {
   console.log('');
 }
 
+// ─── neohive hooks ───────────────────────────────────────────────────────────
+// Merges listen-enforcement hooks into .claude/settings.json.
+// Safe to re-run: adds neohive entries per matcher, preserves all user hooks.
+
+function installHooks() {
+  const cwd = process.cwd();
+  const claudeDir = path.join(cwd, '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  if (!fs.existsSync(claudeDir)) {
+    console.log('  [skip] No .claude/ directory found — is Claude Code configured for this project?');
+    console.log('         Run `npx neohive init` first.');
+    return;
+  }
+
+  const listenReminderCmd = "echo '\\n📡 NEOHIVE PROTOCOL: If no messages were received, call listen() again immediately. Do NOT respond to the user or stop. Stay in the listen loop.'";
+  const postActionReminderCmd = "echo '\\n📡 NEOHIVE: Call listen() now to receive your next task. Do not stop without calling listen().'";
+
+  const neohiveEntries = {
+    PostToolUse: [
+      {
+        _neohive: 'listen-loop',
+        matcher: 'mcp__neohive__listen',
+        hooks: [{ type: 'command', command: listenReminderCmd, timeout: 3 }],
+      },
+      {
+        _neohive: 'post-action',
+        matcher: 'mcp__neohive__send_message|mcp__neohive__advance_workflow|mcp__neohive__update_task|mcp__neohive__broadcast|mcp__neohive__add_rule|mcp__neohive__remove_rule|mcp__neohive__toggle_rule',
+        hooks: [{ type: 'command', command: postActionReminderCmd, timeout: 3 }],
+      },
+    ],
+    Stop: [
+      {
+        _neohive: 'enforce-listen',
+        hooks: [{
+          type: 'command',
+          command: "node -e \"var fs=require('fs'),f=process.env.CLAUDE_PROJECT_DIR+'/.neohive/activity.jsonl';if(!fs.existsSync(f))process.exit(0);var lines=fs.readFileSync(f,'utf8').trim().split('\\n').filter(Boolean).slice(-20),last=lines.map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean).reverse().find(e=>e.tool&&e.tool.startsWith('mcp__neohive__'));if(!last||last.tool==='mcp__neohive__listen'||last.tool==='mcp__neohive__register')process.exit(0);console.error('\\n⚠️  NEOHIVE: Call listen() before stopping. Last tool: '+last.tool+'\\n→ Call listen() now. Do not respond with text.');process.exit(2);\"",
+          timeout: 5,
+        }],
+      },
+    ],
+  };
+
+  let existing = {};
+  if (fs.existsSync(settingsPath)) {
+    try { existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {
+      const backup = settingsPath + '.backup';
+      fs.copyFileSync(settingsPath, backup);
+      console.log('  [warn] Existing settings.json was invalid — backed up.');
+    }
+  }
+  if (!existing.hooks) existing.hooks = {};
+
+  let added = 0;
+  let updated = 0;
+
+  for (const [event, entries] of Object.entries(neohiveEntries)) {
+    if (!existing.hooks[event]) existing.hooks[event] = [];
+    for (const entry of entries) {
+      const idx = existing.hooks[event].findIndex(e => e._neohive === entry._neohive);
+      if (idx === -1) {
+        existing.hooks[event].push(entry);
+        added++;
+      } else {
+        existing.hooks[event][idx] = entry;
+        updated++;
+      }
+    }
+  }
+
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+
+  console.log(`\n  Neohive hooks installed into .claude/settings.json`);
+  if (added)   console.log(`  [ok] Added:   ${added} hook(s)`);
+  if (updated) console.log(`  [ok] Updated: ${updated} hook(s) (already present)`);
+  console.log('  Your existing hooks were preserved.');
+  console.log('  Restart Claude Code for changes to take effect.\n');
+}
+
 switch (command) {
   case 'init':
     init();
@@ -1282,6 +1603,12 @@ switch (command) {
   case 'status':
     cliStatus();
     break;
+  case 'hooks':
+    installHooks();
+    break;
+  case 'skills':
+    installSkills(detectCLIs().length ? detectCLIs() : ['claude', 'cursor', 'antigravity'], process.cwd());
+    break;
   case 'uninstall':
   case 'remove':
     uninstall();