waggle-os/packages/hive-mind-hooks-claude-code

@hive-mind/claude-code-hooks

Silent memory capture for Anthropic Claude Code — every session writes to your local ~/.hive-mind/global.mind, no cloud, no opt-in per session.

Status: Wave 1 MVP, pre-1.0. License: Apache-2.0. Peer dependency: @hive-mind/cli >= 0.1.0 (must be on PATH).

What it does

Patches ~/.claude/settings.json with four hook entries that route Claude Code lifecycle events into hive-mind via the shim-core CLI bridge:

Hook	What we do
SessionStart	Resolve workspace, switch to it, recall the top-N frames, inject as additional context.
UserPromptSubmit	Save the user prompt as a temporary frame scoped to the current session.
Stop	Deterministically summarize the just-completed turn and save it as an important frame, parented to the prompt frame.
PreCompact	Run compact_memory so superseded P/B frames merge before Claude's own context truncation.

All hooks fail open: if hive-mind-cli is unreachable or any step throws, the hook logs a warning to stderr and exits 0. Claude Code never sees a hook failure.

Quickstart

# One-time: install hive-mind-cli globally and init the .mind file
npm install -g @hive-mind/cli
hive-mind-cli init

# Per-machine: install the Claude Code shim
npx @hive-mind/claude-code-hooks install

Windows / pinned CLI path

On Windows, hive-mind-cli is published as an npm .cmd shim that cannot be exec'd directly from a hook. Pin the path at install time:

# Find the upstream CLI's compiled JS entry point
npx @hive-mind/claude-code-hooks install \
  --cli-path "C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@hive-mind\\cli\\dist\\index.js"

The path is recorded in ~/.claude/hive-mind-install.json and threaded into every generated hook command as --cli-path "...". Production users on POSIX may omit the flag if hive-mind-cli is reliably on $PATH at hook invocation time.

Output:

hive-mind/claude-code-hooks: install
  - settings:    /Users/you/.claude/settings.json
  - backup:      /Users/you/.claude/settings.json.hive-mind-backup.2026-04-28T...
  - pointer:     /Users/you/.claude/hive-mind-install.json
  - added hooks: session-start, user-prompt-submit, stop, pre-compact
  - cli path:    (default — hive-mind-cli on PATH)

Done. New Claude Code sessions will silently capture to hive-mind.
Run "claude-code-hooks verify" to inspect, "claude-code-hooks uninstall" to revert.

Reversibility

Install writes a timestamped, byte-identical backup of ~/.claude/settings.json before any modification, plus a small pointer file ~/.claude/hive-mind-install.json. Uninstall reads the pointer, copies the backup back over settings.json, and refuses to remove the backup until the round-trip content matches. The result is a SHA-256-identical pre-install state.

npx @hive-mind/claude-code-hooks uninstall

Coexistence with MEMORY.md

This shim handles the episodic layer (actual conversation turns, captured automatically as frames). It does not touch your existing MEMORY.md — that file is the semantic layer (distilled rules and preferences) and stays under your manual control. The two layers complement each other; nothing is moved or rewritten.

Verify

npx @hive-mind/claude-code-hooks verify

Checks:

• ~/.claude/settings.json exists and is valid JSON.
• All four hive-mind hook entries are present and reference compiled dist/hooks/*.js files that actually exist.
• hive-mind-cli is on PATH and answers --version.

License

Apache-2.0 — see the repo root.