hippo-memory 1.70.0 → 1.71.0

package/dist/hooks/hook-blocks.js

@@ -5,71 +5,22 @@ export const HOOK_MARKERS = {
     start: '<!-- hippo:start -->',
     end: '<!-- hippo:end -->',
 };
-export const HOOKS = {
-    'claude-code': {
-        file: 'CLAUDE.md',
-        description: 'Claude Code',
-        content: `
-## Project Memory (Hippo)
-
-Pinned rules and recent writes auto-inject at every prompt via the installed
-UserPromptSubmit hook; never re-run that part manually. At the START of a
-task (not per prompt), additionally load task-specific context: git-aware
-recall over the full store that per-prompt injection does not cover. Also
-run it if the hook is not installed:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-
-When you find out why something failed, record it right then, while you
-work, never as a closing step:
-\`\`\`bash
-hippo remember "<what went wrong and why>" --error
-\`\`\`
-
-The installed hooks store failed tool calls and capture the session when it
-ends, so there is nothing to run before you finish.
-`.trim(),
-    },
-    'codex': {
-        file: 'AGENTS.md',
-        description: 'OpenAI Codex',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every task, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour, record it right then, while you work,
-never as a closing step:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-When you learn something that should outlive this session (a decision and
-its reason, a user preference, a lesson), record it right then, while you
-work, never as a closing step. Leave out secrets and personal details:
-\`\`\`bash
-hippo remember "<what you learned and why>"
-\`\`\`
-
-When Hippo's Codex wrapper is installed, session-end capture runs automatically.
-If the wrapper is not installed, capture a brief summary manually:
+// Shared by the agents that differ only in the noun, an optional recall paragraph and an optional footer.
+const PI_FOOTER = 'For full integration, copy the hippo-memory Pi extension to `~/.pi/agent/extensions/hippo-memory/`.';
+function agentsBlock(noun, opts = {}) {
+    const recall = opts.recall
+        ? `
+When stuck or repeating yourself, check if this happened before:
 \`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+hippo recall "<what's going wrong>" --budget 2000
 \`\`\`
-`.trim(),
-    },
-    'cursor': {
-        file: 'AGENTS.md',
-        description: 'Cursor',
-        content: `
+`
+        : '';
+    const footer = opts.footer ? `\n${opts.footer}\n` : '';
+    return `
 ## Project Memory (Hippo)
 
-At the start of every task, run:
+At the start of every ${noun}, run:
 \`\`\`bash
 hippo context --auto --budget 1500
 \`\`\`
@@ -87,47 +38,42 @@ work, never as a closing step. Leave out secrets and personal details:
 \`\`\`bash
 hippo remember "<what you learned and why>"
 \`\`\`
-
+${recall}
 When ending a session, capture a brief summary:
 \`\`\`bash
 hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
 \`\`\`
-`.trim(),
-    },
-    'openclaw': {
-        file: 'AGENTS.md',
-        description: 'OpenClaw',
+${footer}`.trim();
+}
+export const HOOKS = {
+    'claude-code': {
+        file: 'CLAUDE.md',
+        description: 'Claude Code',
         content: `
 ## Project Memory (Hippo)
 
-At the start of every session, run:
+Pinned rules and recent writes auto-inject at every prompt via the installed
+UserPromptSubmit hook; never re-run that part manually. At the START of a
+task (not per prompt), additionally load task-specific context: git-aware
+recall over the full store that per-prompt injection does not cover. Also
+run it if the hook is not installed:
 \`\`\`bash
 hippo context --auto --budget 1500
 \`\`\`
-Read the output before writing any code.
 
-On errors or unexpected behaviour, record it right then, while you work,
-never as a closing step:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-When you learn something that should outlive this session (a decision and
-its reason, a user preference, a lesson), record it right then, while you
-work, never as a closing step. Leave out secrets and personal details:
+When you find out why something failed, record it right then, while you
+work, never as a closing step:
 \`\`\`bash
-hippo remember "<what you learned and why>"
+hippo remember "<what went wrong and why>" --error
 \`\`\`
 
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
-\`\`\`
+The installed hooks store failed tool calls and capture the session when it
+ends, so there is nothing to run before you finish.
 `.trim(),
     },
-    'opencode': {
+    'codex': {
         file: 'AGENTS.md',
-        description: 'OpenCode',
+        description: 'OpenAI Codex',
         content: `
 ## Project Memory (Hippo)
 
@@ -150,50 +96,17 @@ work, never as a closing step. Leave out secrets and personal details:
 hippo remember "<what you learned and why>"
 \`\`\`
 
-When stuck or repeating yourself, check if this happened before:
-\`\`\`bash
-hippo recall "<what's going wrong>" --budget 2000
-\`\`\`
-
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
-\`\`\`
-`.trim(),
-    },
-    'pi': {
-        file: 'AGENTS.md',
-        description: 'Pi',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every session, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour, record it right then, while you work,
-never as a closing step:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-When you learn something that should outlive this session (a decision and
-its reason, a user preference, a lesson), record it right then, while you
-work, never as a closing step. Leave out secrets and personal details:
-\`\`\`bash
-hippo remember "<what you learned and why>"
-\`\`\`
-
-When ending a session, capture a brief summary:
+When Hippo's Codex wrapper is installed, session-end capture runs automatically.
+If the wrapper is not installed, capture a brief summary manually:
 \`\`\`bash
 hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
 \`\`\`
-
-For full integration, copy the hippo-memory Pi extension to \`~/.pi/agent/extensions/hippo-memory/\`.
 `.trim(),
     },
+    'cursor': { file: 'AGENTS.md', description: 'Cursor', content: agentsBlock('task') },
+    'openclaw': { file: 'AGENTS.md', description: 'OpenClaw', content: agentsBlock('session') },
+    'opencode': { file: 'AGENTS.md', description: 'OpenCode', content: agentsBlock('task', { recall: true }) },
+    'pi': { file: 'AGENTS.md', description: 'Pi', content: agentsBlock('session', { footer: PI_FOOTER }) },
 };
 // sha256 of each trimmed block an earlier hippo wrote, so init refreshes only blocks nobody edited. Add the old hash when a block changes.
 const SHIPPED_HOOK_HASHES = new Map([

package/dist/hooks/json-hooks.d.ts

@@ -1,38 +1,5 @@
-/**
- * Hook install/uninstall for AI coding tools.
- *
- * Two integration models live in this file:
- *
- * 1. JSON-hook install (Claude Code only). Writes a `hooks` block into the
- *    tool's settings.json with two entries:
- *      - SessionEnd: `hippo session-end --log-file <path>` - spawns a detached
- *        child that runs `hippo sleep` then `hippo capture --last-session` in
- *        sequence, writing both outputs to the log file. The parent returns in
- *        <100ms so the TUI teardown can't kill the child before it finishes.
- *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
- *        written by the previous session's detached worker on stderr and
- *        clears it. Stdout carries only a `systemMessage` problems line,
- *        because Claude Code shows that to the user, not the model.
- *    Earlier Claude Code forms are detected and migrated automatically:
- *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
- *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
- *      - 0.22.x: separate sleep + capture SessionEnd entries.
- *    PreCompact and PostCompact entries go in too: the first records the compaction and
- *    asks the summariser for a "Memories for hippo" list, the second saves that list.
- *    Codex's hooks.json gets only two groups (per-prompt memory and
- *    compact-resume); see installCodexHooks. Copilot gets a file of its own; see installCopilotHooks.
- *
- * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
- *    JSON-hook schema — its config has `additionalProperties: false` and no
- *    `hooks` key, so a JSON-hook install breaks opencode launch. Hippo
- *    installs a TypeScript plugin at
- *    `~/.config/opencode/plugins/hippo.ts` subscribing to opencode's
- *    `session.idle` (→ `hippo session-end`) and `session.created` (→
- *    `hippo last-sleep`) events. See OPENCODE_PLUGIN_SOURCE below for the
- *    plugin file content + design rationale; see installOpencodePlugin for
- *    the installer + the migration that removes any pre-existing broken
- *    `hooks` block from opencode.json.
- */
+/** Hook install/uninstall for AI coding tools. Claude Code gets a JSON `hooks` block in settings.json; older forms are migrated automatically.
+ * OpenCode rejects the JSON-hook schema (no `hooks` key), so it gets a TS plugin (OPENCODE_PLUGIN_SOURCE); see installCodexHooks, installCopilotHooks. */
 import { type JsonHookTarget } from './shared.js';
 import { type JsonValue } from '../util/json.js';
 /** A target's hook settings file, the log its SessionEnd hook writes, and the tool's display name. */
@@ -71,6 +38,7 @@ export declare function installJsonHooks(target: JsonHookTarget): InstallResult;
 export declare function writeSettingsFile(file: string, settings: JsonValue): void;
 /** Removes hippo's own hook handlers from `target`'s settings file and keeps every other handler; true when the file changed. */
 export declare function uninstallJsonHooks(target: JsonHookTarget): boolean;
-/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
+/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists
+ * but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
 export declare function checkUninstallable(target: JsonHookTarget): Pick<InstallResult, 'settingsPath' | 'invalidJson'>;
 //# sourceMappingURL=json-hooks.d.ts.map

package/dist/hooks/json-hooks.js

@@ -1,38 +1,5 @@
-/**
- * Hook install/uninstall for AI coding tools.
- *
- * Two integration models live in this file:
- *
- * 1. JSON-hook install (Claude Code only). Writes a `hooks` block into the
- *    tool's settings.json with two entries:
- *      - SessionEnd: `hippo session-end --log-file <path>` - spawns a detached
- *        child that runs `hippo sleep` then `hippo capture --last-session` in
- *        sequence, writing both outputs to the log file. The parent returns in
- *        <100ms so the TUI teardown can't kill the child before it finishes.
- *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
- *        written by the previous session's detached worker on stderr and
- *        clears it. Stdout carries only a `systemMessage` problems line,
- *        because Claude Code shows that to the user, not the model.
- *    Earlier Claude Code forms are detected and migrated automatically:
- *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
- *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
- *      - 0.22.x: separate sleep + capture SessionEnd entries.
- *    PreCompact and PostCompact entries go in too: the first records the compaction and
- *    asks the summariser for a "Memories for hippo" list, the second saves that list.
- *    Codex's hooks.json gets only two groups (per-prompt memory and
- *    compact-resume); see installCodexHooks. Copilot gets a file of its own; see installCopilotHooks.
- *
- * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
- *    JSON-hook schema — its config has `additionalProperties: false` and no
- *    `hooks` key, so a JSON-hook install breaks opencode launch. Hippo
- *    installs a TypeScript plugin at
- *    `~/.config/opencode/plugins/hippo.ts` subscribing to opencode's
- *    `session.idle` (→ `hippo session-end`) and `session.created` (→
- *    `hippo last-sleep`) events. See OPENCODE_PLUGIN_SOURCE below for the
- *    plugin file content + design rationale; see installOpencodePlugin for
- *    the installer + the migration that removes any pre-existing broken
- *    `hooks` block from opencode.json.
- */
+/** Hook install/uninstall for AI coding tools. Claude Code gets a JSON `hooks` block in settings.json; older forms are migrated automatically.
+ * OpenCode rejects the JSON-hook schema (no `hooks` key), so it gets a TS plugin (OPENCODE_PLUGIN_SOURCE); see installCodexHooks, installCopilotHooks. */
 import * as fs from 'fs';
 import * as path from 'path';
 import { HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
@@ -66,7 +33,8 @@ export function resolveJsonHookPaths(target) {
 }
 // An unterminated quote runs to the end, as in a shell, which also keeps the scan linear.
 const QUOTED_SPAN = /'[^']*(?:'|$)|"(?:[^"\\]|\\[\s\S]?)*(?:"|$)/g;
-/** Hippo's command only at string start or after `(`, past env assignments and an install path, with quoted text ignored: `say hippo sleep`, `echo "a; hippo sleep"` and `./backup.sh && hippo sleep` stay a user's. */
+/** Hippo's command only at string start or after `(`, past env assignments and an install path, with quoted
+ * text ignored: `say hippo sleep`, `echo "a; hippo sleep"` and `./backup.sh && hippo sleep` stay a user's. */
 function isHippoCommand(command, marker) {
     const unquoted = command.replace(QUOTED_SPAN, '');
     return new RegExp(`(?:^|\\()\\s*(?:[A-Za-z_]\\w*=\\S*\\s+)*(?:[^\\s(]*[/\\\\])?${escapeRegex(marker)}(?![\\w.-])`).test(unquoted);
@@ -167,7 +135,8 @@ function nothingInstalled(target, settingsPath) {
 function codexCommandHook(command, timeout) {
     return { type: 'command', command, commandWindows: command.replace(/^hippo /, 'hippo.cmd '), timeout };
 }
-/** Assigns `settings.hooks = {}` when it is absent, then returns it if it is an object whose `events`, where present, are arrays; null when appending would overwrite anything else. */
+/** Assigns `settings.hooks = {}` when it is absent, then returns it if it is an object whose
+ * `events`, where present, are arrays; null when appending would overwrite anything else. */
 function ensureHooksObject(settings, events) {
     if (settings.hooks === undefined)
         settings.hooks = {};
@@ -310,27 +279,18 @@ const CLAUDE_APPENDED_EVENTS = CLAUDE_HOOK_MARKERS.map(([event]) => event).filte
 function appendSessionHooks(hooks, logFile) {
     const installedSessionEnd = appendHookIfMissing(hooks, 'SessionEnd', HIPPO_SESSION_END_MARKER, claudeCommandGroup(`hippo session-end --log-file "${logFile}"`, 5));
     const installedSessionStart = appendHookIfMissing(hooks, 'SessionStart', HIPPO_LAST_SLEEP_MARKER, claudeCommandGroup(`hippo last-sleep --path "${logFile}"`, 5));
-    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn,
-    // so pinned memories stay in context even after the model would otherwise
-    // "forget" them in a long session. Include the fresh write tail so lessons
-    // saved earlier in the same session become visible on the next prompt even
-    // before the user pins them explicitly.
+    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn, so pinned memories stay in context; the fresh write tail
+    // makes lessons saved earlier in the session visible on the next prompt even before they are pinned.
     const migratedPinnedInjectRecent = migratePinnedInjectRecentCommands(hooks.UserPromptSubmit);
     const installedUserPromptSubmit = appendHookIfMissing(hooks, 'UserPromptSubmit', HIPPO_PINNED_INJECT_MARKER, claudeCommandGroup(HIPPO_PINNED_INJECT_COMMAND, 5));
     return { installedSessionEnd, installedSessionStart, migratedPinnedInjectRecent, installedUserPromptSubmit };
 }
 function appendCompactionHooks(hooks) {
-    // PreCompact: fires on manual AND auto compaction (no matcher). Records the compaction, asks the
-    // summariser for a "Memories for hippo" list and saves a working-state snapshot before the summary drops detail.
-    // Exit-0 contract lives in the verb itself (src/capture.ts cmdPreCompact),
-    // not here — this is install-time wiring only.
+    // PreCompact: fires on manual AND auto compaction (no matcher); records it, asks the summariser for a "Memories for hippo" list and saves a snapshot.
+    // The exit-0 contract lives in the verb itself (cmdPreCompact, src/capture/compact.ts), not in this install-time wiring.
     const installedPreCompact = appendHookIfMissing(hooks, 'PreCompact', HIPPO_PRE_COMPACT_MARKER, claudeCommandGroup(`hippo pre-compact --log-file "${defaultPreCompactLogPath()}"`, 30));
-    // SessionStart(compact): a SECOND SessionStart entry alongside the
-    // un-matched last-sleep entry above. The matcher is an optimization, not
-    // a dependency — compact-resume itself checks payload.source too, so an
-    // older Claude Code that ignores the matcher just runs a silent no-op on
-    // normal starts. Marker check keys on the command string, so this stays
-    // idempotent alongside the sibling last-sleep entry.
+    // SessionStart(compact): a second SessionStart entry beside the unmatched last-sleep one. The matcher is an optimization, not a dependency:
+    // compact-resume checks payload.source itself, and the marker check keys on the command string, so this stays idempotent.
     const installedCompactResume = appendHookIfMissing(hooks, 'SessionStart', HIPPO_COMPACT_RESUME_MARKER, claudeCommandGroup('hippo compact-resume', 10, 'compact'));
     // PostCompact: saves the memories the summariser listed and prints one line, which Claude Code only shows.
     // PreCompact stdout, by contrast, is handed to the summariser as instructions, so pre-compact prints just the request.
@@ -346,9 +306,8 @@ function installClaudeCodeHooks(settingsPath, settings, logFile) {
     const migration = migrateLegacyClaudeHooks(hooks);
     const { installedSessionEnd, installedSessionStart, migratedPinnedInjectRecent, installedUserPromptSubmit } = appendSessionHooks(hooks, logFile);
     const { installedPreCompact, installedCompactResume, installedPostCompact } = appendCompactionHooks(hooks);
-    // PostToolUseFailure: a failed tool call becomes an error memory, after
-    // `hippo capture-error` drops routine failures (interrupts, declined
-    // permissions, empty searches) and repeats. Same hook the plugin ships.
+    // PostToolUseFailure: a failed tool call becomes an error memory, after `hippo capture-error` drops routine failures
+    // (interrupts, declined permissions, empty searches) and repeats. Same hook the plugin ships.
     const installedCaptureError = appendHookIfMissing(hooks, 'PostToolUseFailure', HIPPO_CAPTURE_ERROR_MARKER, claudeCommandGroup('hippo capture-error', 10, '.*'));
     const result = {
         target: 'claude-code',
@@ -380,7 +339,8 @@ function uninstallCodexHooks(hooks) {
         changed = stripHandlers(hooks, event, (c) => c === command) || changed;
     return changed;
 }
-/** One stderr line naming the handlers uninstall kept that still mention a hippo command (`nice hippo sleep`, `pnpm exec hippo ...`), so the user can remove them by hand. */
+/** One stderr line naming the handlers uninstall kept that still mention a hippo command
+ * (`nice hippo sleep`, `pnpm exec hippo ...`), so the user can remove them by hand. */
 function warnKeptHippoHandlers(settingsPath, hooks) {
     const kept = CLAUDE_HOOK_MARKERS.flatMap(([event, markers]) => {
         const groups = hooks[event];
@@ -421,7 +381,8 @@ export function uninstallJsonHooks(target) {
     writeSettingsFile(settingsPath, settings);
     return true;
 }
-/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
+/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists
+ * but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
 export function checkUninstallable(target) {
     const { settings: settingsPath } = resolveJsonHookPaths(target);
     if (!fs.existsSync(settingsPath))

package/dist/hooks/opencode.d.ts

@@ -1,42 +1,4 @@
 declare const HIPPO_OPENCODE_PLUGIN_MARKER = "HIPPO_OPENCODE_PLUGIN_V1";
-/**
- * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
- *
- * Per https://opencode.ai/docs/plugins/, plugins are TS/JS modules exporting an
- * async function returning hooks. We subscribe to `event` and route:
- *   session.idle    → `hippo session-end` (Claude Code's SessionEnd equiv)
- *   session.created → `hippo last-sleep` (Claude Code's SessionStart equiv)
- *
- * Design choices:
- *
- * 1. No `import type { Plugin } from "@opencode-ai/plugin"`. The package's npm
- *    publication status was unverifiable from the build sandbox (npmjs.com
- *    returned 403); an unresolved type-only import would still crash the TS
- *    runtime opencode uses to load the plugin. opencode infers plugin shape
- *    from the returned object, so the type was convenience-only.
- *
- * 2. Defensive `typeof $ !== 'function'` guard. opencode runs in Bun (where
- *    `$` is the shell-template helper), but a future Node-mode deployment
- *    would have `$` undefined in the destructured context and the plugin
- *    would throw on every session.idle, killing opencode sessions in a
- *    hard-to-recover way (the idempotence marker prevents auto-reinstall).
- *    Fail closed, let opencode continue.
- *
- * 3. `.quiet().nothrow()` on each `$\`...\`` so a missing hippo binary
- *    (e.g. PATH-misconfigured user) does NOT throw out of the event handler.
- *    The surrounding try/catch is belt-and-braces.
- *
- * 4. UserPromptSubmit equivalent NOT wired. opencode's `message.updated`
- *    fires per-token, not per-prompt-submit; no clean per-prompt event.
- *    Users wanting pinned-context auto-injection can call `hippo context`
- *    via the MCP server (`hippo mcp`).
- *
- * 5. Versioned marker `HIPPO_OPENCODE_PLUGIN_V1` allows future versions to
- *    overwrite cleanly. The installer's idempotence check requires BOTH
- *    marker match AND content equality, so a plugin-source revision under
- *    the same V1 marker re-writes the file on next install.
- */
-export declare const OPENCODE_PLUGIN_SOURCE = "// HIPPO_OPENCODE_PLUGIN_V1\n// hippo-memory opencode plugin. DO NOT EDIT \u2014 regenerated on every\n// `hippo hook install opencode` from src/hooks.ts OPENCODE_PLUGIN_SOURCE\n// in https://github.com/kitfunso/hippo-memory. Local changes will be lost.\n\nexport const HippoPlugin = async ({ $ }) => {\n  return {\n    event: async ({ event }) => {\n      // Defense in depth: opencode currently runs in Bun where $ is the shell\n      // template helper. A non-Bun runtime would have $ as undefined; fail\n      // closed instead of crashing the host session.\n      if (typeof $ !== \"function\") return;\n      try {\n        if (event.type === \"session.idle\") {\n          await $`hippo session-end`.quiet().nothrow();\n        } else if (event.type === \"session.created\") {\n          await $`hippo last-sleep`.quiet().nothrow();\n        }\n      } catch {\n        // hippo CLI not on PATH or other failure \u2014 never crash the host session.\n      }\n    },\n  };\n};\n";
 export { HIPPO_OPENCODE_PLUGIN_MARKER };
 export interface OpencodePluginInstallResult {
     installed: boolean;

package/dist/hooks/opencode.js

@@ -4,44 +4,9 @@ import { homeDir } from './shared.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
 import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
 const HIPPO_OPENCODE_PLUGIN_MARKER = 'HIPPO_OPENCODE_PLUGIN_V1';
-/**
- * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
- *
- * Per https://opencode.ai/docs/plugins/, plugins are TS/JS modules exporting an
- * async function returning hooks. We subscribe to `event` and route:
- *   session.idle    → `hippo session-end` (Claude Code's SessionEnd equiv)
- *   session.created → `hippo last-sleep` (Claude Code's SessionStart equiv)
- *
- * Design choices:
- *
- * 1. No `import type { Plugin } from "@opencode-ai/plugin"`. The package's npm
- *    publication status was unverifiable from the build sandbox (npmjs.com
- *    returned 403); an unresolved type-only import would still crash the TS
- *    runtime opencode uses to load the plugin. opencode infers plugin shape
- *    from the returned object, so the type was convenience-only.
- *
- * 2. Defensive `typeof $ !== 'function'` guard. opencode runs in Bun (where
- *    `$` is the shell-template helper), but a future Node-mode deployment
- *    would have `$` undefined in the destructured context and the plugin
- *    would throw on every session.idle, killing opencode sessions in a
- *    hard-to-recover way (the idempotence marker prevents auto-reinstall).
- *    Fail closed, let opencode continue.
- *
- * 3. `.quiet().nothrow()` on each `$\`...\`` so a missing hippo binary
- *    (e.g. PATH-misconfigured user) does NOT throw out of the event handler.
- *    The surrounding try/catch is belt-and-braces.
- *
- * 4. UserPromptSubmit equivalent NOT wired. opencode's `message.updated`
- *    fires per-token, not per-prompt-submit; no clean per-prompt event.
- *    Users wanting pinned-context auto-injection can call `hippo context`
- *    via the MCP server (`hippo mcp`).
- *
- * 5. Versioned marker `HIPPO_OPENCODE_PLUGIN_V1` allows future versions to
- *    overwrite cleanly. The installer's idempotence check requires BOTH
- *    marker match AND content equality, so a plugin-source revision under
- *    the same V1 marker re-writes the file on next install.
- */
-export const OPENCODE_PLUGIN_SOURCE = `// ${HIPPO_OPENCODE_PLUGIN_MARKER}
+/** The opencode plugin installed at ~/.config/opencode/plugins/hippo.ts: session.idle runs `hippo session-end`, session.created runs `hippo last-sleep`.
+ * No `@opencode-ai/plugin` type import (unresolved, it would crash the loader); `$` is guarded and `.nothrow()` keeps a missing hippo binary from throwing. */
+const OPENCODE_PLUGIN_SOURCE = `// ${HIPPO_OPENCODE_PLUGIN_MARKER}
 // hippo-memory opencode plugin. DO NOT EDIT — regenerated on every
 // \`hippo hook install opencode\` from src/hooks.ts OPENCODE_PLUGIN_SOURCE
 // in https://github.com/kitfunso/hippo-memory. Local changes will be lost.
@@ -73,23 +38,8 @@ export function resolveOpencodePluginPath() {
 function resolveOpencodeConfigPath() {
     return path.join(homeDir(), '.config', 'opencode', 'opencode.json');
 }
-/**
- * Return true iff a single hook-array entry's command string starts with
- * `hippo ` (the verb-prefix). Used to surgically remove only hippo-owned
- * commands when migrating an opencode.json. We own the install side, so only
- * the canonical `hippo <verb>` form needs to match — and only canonical verbs
- * hippo itself installs (session-end, last-sleep, sleep, capture, context),
- * not any third-party tool that happens to be named `hippo`.
- *
- * Structural check: substring matching against
- * arbitrary user content is unsafe — a user's
- * `echo "remember to hippo sleep your laptop"` is not a hippo-owned hook.
- *
- * Per-hook (not per-entry) granularity: an entry whose inner
- * hooks array mixes hippo-installed commands with user-authored commands
- * must NOT lose the user-authored commands. The migration filters the inner
- * array per-hook, then drops the entry only when its inner array is empty.
- */
+/** True iff a hook entry's command starts with `hippo ` plus a verb hippo itself installs (session-end, last-sleep, sleep, capture, context).
+ * Structural, not substring (`echo "remember to hippo sleep"` is not ours), and per hook so user-authored hooks in the same entry survive. */
 const HIPPO_OWNED_COMMAND_RE = /^\s*hippo\s+(session-end|last-sleep|sleep|capture|context)(?=\s|$)/;
 function hookIsHippoOwned(hook) {
     if (!isJsonObjectLiteral(hook))
@@ -97,23 +47,8 @@ function hookIsHippoOwned(hook) {
     const cmd = hook.command;
     return isJsonString(cmd) && HIPPO_OWNED_COMMAND_RE.test(cmd);
 }
-/**
- * Structurally strip every hippo-owned hook from opencode.json's hooks key.
- * Returns one of:
- *   { migrated: true,  jsonRepairFailed: false } — at least one hook removed.
- *   { migrated: false, jsonRepairFailed: false } — file fine, nothing to do.
- *   { migrated: false, jsonRepairFailed: true  } — file present but unparseable.
- *
- * Per-hook surgery:
- *   - For each entry in each event-key array, filter the inner `hooks` array
- *     to remove hippo-owned hooks only. User-authored hooks in the same
- *     inner array are preserved.
- *   - When an entry's inner `hooks` array becomes empty, that entry is
- *     removed from the outer array.
- *   - When an event-key array becomes empty, the key is deleted.
- *   - When the top-level `hooks` object becomes empty, it is deleted.
- *   - Other keys (theme, etc.) are always preserved.
- */
+/** Strip every hippo-owned hook from opencode.json's `hooks` key, deleting entries, keys and the object as they empty; user-authored hooks and other keys stay.
+ * Returns `{ migrated, jsonRepairFailed }`; jsonRepairFailed means the file is present but unparseable. */
 function migrateLegacyOpencodeHooksBlock() {
     const configPath = resolveOpencodeConfigPath();
     if (!fs.existsSync(configPath))
@@ -180,10 +115,8 @@ function stripHippoHooksFromEntries(entries) {
 export function installOpencodePlugin() {
     const pluginPath = resolveOpencodePluginPath();
     const { migrated, jsonRepairFailed } = migrateLegacyOpencodeHooksBlock();
-    // Idempotence: skip the write only if BOTH the marker is present AND the
-    // content matches the current source. Marker-only matches (with stale
-    // content) overwrite cleanly so future plugin-source patches reach
-    // existing installs.
+    // Skip the write only if BOTH the marker is present and the content matches; a marker-only match with stale
+    // content is rewritten so plugin-source patches reach existing installs.
     if (fs.existsSync(pluginPath)) {
         const existing = fs.readFileSync(pluginPath, 'utf8');
         if (existing.includes(HIPPO_OPENCODE_PLUGIN_MARKER) && existing === OPENCODE_PLUGIN_SOURCE) {

package/dist/hooks/shared.d.ts

@@ -20,9 +20,11 @@ export declare const HIPPO_POST_COMPACT_MARKER = "hippo post-compact";
 export declare function homeDir(): string;
 /** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
 export declare function codexHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
-/** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the Copilot apps resolve it (a HOME that differs from the profile must not move it). */
+/** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the
+ * Copilot apps resolve it (a HOME that differs from the profile must not move it). */
 export declare function copilotHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
-/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
+/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
+ * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
 export declare function claudeConfigDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
@@ -36,23 +38,12 @@ export declare function vscodeUserDirs(env?: Readonly<Record<string, string | un
 export declare function isCopilotPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
 export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
-/**
- * Default log path consumed by `hippo last-sleep`. Shared fallback when
- * a caller doesn't pass --path explicitly.
- */
+/** Default log path consumed by `hippo last-sleep` when a caller passes no --path. */
 export declare function defaultSleepLogPath(): string;
-/**
- * Diagnostic-only log path for `hippo pre-compact`. Deliberately separate
- * from the SessionEnd sleep log: `hippo last-sleep` truncates that file on
- * every SessionStart, which would wipe pre-compact lines before anyone
- * could read them. Nothing consumes this file programmatically — it exists
- * for manual troubleshooting only. Overridden by `--log-file`.
- */
+/** Diagnostic-only log path for `hippo pre-compact`, kept apart from the SessionEnd sleep log because `hippo last-sleep` truncates that one every SessionStart.
+ * Nothing reads it programmatically; overridden by `--log-file`. */
 export declare function defaultPreCompactLogPath(): string;
 export declare function ensureDir(dir: string): void;
-/**
- * Detect which AI coding tools are installed based on config directory presence.
- * Used by `hippo setup` to decide which JSON-hook installs to run.
- */
+/** Detect which AI coding tools are installed from config directory presence; `hippo setup` uses it to pick JSON-hook installs. */
 export declare function detectInstalledTools(): ToolDetection[];
 //# sourceMappingURL=shared.d.ts.map