85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# @hive-mind/claude-code-hooks
|
|
|
|
> Silent memory capture for [Anthropic Claude Code](https://claude.com/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](../shim-core):
|
|
|
|
| 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://github.com/marolinik/hive-mind-clients/blob/main/LICENSE).
|