neohive 6.2.2 → 6.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [6.3.0] - 2026-04-05
+
+### Added
+
+- **Unified `next_action` response chain** — every MCP tool response now includes a single `next_action` field that tells the AI agent exactly what to do next, replacing 10+ scattered hint fields (`_listen`, `_nudge`, `hint`, `action_required`, `unread_action`, `you_have_messages`, `urgent`, `mode_hint`, `_protocol`, etc.)
+- **Tool-specific directives** — each tool sets a context-aware `next_action` (e.g. `update_task(done)` → "Send a summary via send_message(), then call listen()"; `lock_file` → "Edit the file, then call unlock_file() when done")
+- **Coordinator-aware middleware** — post-processing middleware detects responsive coordinators and replaces any `listen()` directive with `consume_messages()` or removes it entirely, preventing coordinators from blocking in listen mode
+- **Persistent listen loop** — `listen()` and `listen_group()` no longer return `retry: true` on timeout; they loop internally with fresh watchers and heartbeats, so agents cannot break out of listen mode
+- **Managed mode next_action** — `buildListenGroupResponse` respects `should_respond` and floor state; agents without the floor get "do NOT respond" instead of "reply via send_message()"
+- **Autonomous get_work() directives** — all 10 return types from `get_work()` carry specific `next_action` values guiding agents through the workflow/verify/advance cycle
+- **Documentation** — `docs/reference/next-action-chain.md` with flow diagrams for standard agents, agent-to-agent communication, responsive/autonomous coordinators, managed mode, and persistent listen
+
+### Changed
+
+- **Post-processing middleware rewrite** — removed the scattered nudge/unread/listen injection block (~80 lines) and replaced with a unified `next_action` block using priority logic: tool-specific > coordinator override > call-count warning > urgent messages > pending messages > default
+- **`buildMessageResponse`** — `_protocol` field inside message objects replaced with top-level `next_action`; `coordinator_mode` field removed from listen responses
+- **`buildListenGroupResponse`** — simplified `next_action` with mode-aware branching (autonomous/managed/standard)
+- **`send_message` / `broadcast`** — removed `you_have_messages`, `urgent`, `mode_hint` fields; added `next_action: "Call listen() to receive replies."`
+- **`verify_and_advance`** — replaced verbose `message` strings with concise `next_action` directives
+
+### Fixed
+
+- **Responsive coordinator contradiction** — `send_message`, `broadcast`, and `create_task` no longer unconditionally tell responsive coordinators to call `listen()`; middleware overrides any `listen()` directive for responsive coordinators
+- **Managed mode contradiction** — `buildListenGroupResponse` no longer sets "Reply via send_message()" when `should_respond: false` and `instructions: "DO NOT RESPOND"` are also present
+- **Autonomous listen_group retry** — removed contradictory `retry: true` from autonomous mode timeout path where `next_action` directs to `get_work()` instead
+
 ## [6.1.0] - 2026-04-04
 
 ### Added

package/README.md

@@ -256,10 +256,13 @@ neohive status              # active agents, tasks, workflows
 neohive msg <agent> <text>  # send message from CLI
 neohive doctor              # diagnostic health check
 neohive templates           # list available templates
+neohive hooks               # install listen-enforcement hooks into .claude/settings.json
 neohive reset --force       # clear data (auto-archives first)
 neohive uninstall           # remove from all CLI configs
 ```
 
+> **Claude Code users:** Run `npx neohive hooks` after `init` to install listen-enforcement hooks into `.claude/settings.json`. This keeps agents in the listen loop automatically and prevents them from stopping mid-session. Safe to re-run — your existing hooks are preserved.
+
 <br />
 
 ## ⚙️ Configuration

package/cli.js

@@ -46,6 +46,7 @@ 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 uninstall           Remove from all CLI configs
     npx neohive help                Show this help
 
@@ -135,7 +136,6 @@ function setupClaude(serverPath, cwd) {
   console.log('  [ok] Claude Code: .mcp.json updated');
 }
 
-// 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 +186,187 @@ function setupGemini(serverPath, cwd) {
 }
 
 function geminiMdTemplate() {
-  return `# Neohive Agent — Gemini CLI
+  return `# GEMINI.md
 
-You are a Neohive team agent. Follow these rules exactly, every session, no exceptions.
+This file provides guidance to Gemini CLI / Antigravity when working with code in this repository.
 
-## First thing to do — always
+## What This Is
 
-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
+**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.
 
-Do NOT explore the codebase, ask questions, or take initiative before completing these 3 steps.
+## Commands
 
-## Core rules
+\`\`\`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
 
-- **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.
+# Launch the web dashboard
+npx neohive dashboard
 
-## Workflow
+# List available agent templates
+npx neohive templates
 
+# Plugin management
+npx neohive plugin list/add/remove/enable/disable
+
+# Reset conversation data
+npx neohive reset
+
+# 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\`
 
-## Available MCP tools
+**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.
 
-**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\`
+### 4. Profiles & Workspaces
+\`update_profile\`, \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
 
-## What NOT to do
+### 5. Chat Branching & Managed Modes
+\`fork_conversation\`, \`switch_branch\`, \`list_branches\`, \`set_conversation_mode\`, \`claim_manager\`, \`yield_floor\`, \`set_phase\`
 
-- 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
+### 6. Sub-channels
+\`join_channel\`, \`leave_channel\`, \`list_channels\`
+
+### 7. File Safety & Auditing
+\`lock_file\`, \`unlock_file\`, \`log_violation\`
+
+### 8. Shared Knowledge & Decision Tracking
+\`kb_write\`, \`kb_read\`, \`kb_list\`, \`log_decision\`, \`get_decisions\`, \`get_compressed_history\`, \`get_briefing\`
+
+### 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.
 `;
 }
 
@@ -323,42 +459,39 @@ function setupAntigravity(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\`
 `;
 }
 
@@ -685,6 +818,12 @@ function init() {
     console.log('    npx neohive status');
     console.log('    npx neohive doctor');
     console.log('');
+    if (targets.includes('claude')) {
+      console.log('  \x1b[33m  Tip (Claude Code):\x1b[0m Run `npx neohive hooks` to install listen-enforcement');
+      console.log('  hooks into .claude/settings.json. Keeps agents in the listen loop automatically.');
+      console.log('  Your existing hooks will not be removed.');
+      console.log('');
+    }
   }
 }
 
@@ -1251,6 +1390,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 +1501,9 @@ switch (command) {
   case 'status':
     cliStatus();
     break;
+  case 'hooks':
+    installHooks();
+    break;
   case 'uninstall':
   case 'remove':
     uninstall();