@monoes/hooks

A library, not a runtime dispatcher. Provides hook type definitions, an in-memory HookRegistry/HookExecutor for defining handlers, and a WorkerManager with 9 background workers for Monomind.

Part of the Monomind ecosystem.

Architecture: this is not the live hook path

The Claude Code hooks that actually fire on every edit/command/task/session run through the plain CJS handlers in .claude/helpers/ (see .claude/helpers/hook-handler.cjs), wired up via settings.json. That is the authoritative, "live" dispatch system.

This package is bridged in as optional enrichment at a handful of lifecycle events (SessionStart, PreTask, PostTask, PostEdit, SessionEnd, AgentSpawn) when it's installed and built. HookRegistry lets you define handlers the CJS layer can call into, but since each hook event runs in a fresh subprocess, in-memory registrations don't survive across events. What persists is the workers' output: they write JSON metrics files under .monomind/metrics/ that the statusline, router, and doctor read back.

Install

npm install @monoes/hooks

Native module install blocked? The SQLite-backed background workers depend on better-sqlite3. If it fails to load with Could not locate the bindings file, your npm's allowScripts policy blocked its native build — run npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3.

Quick start

import { HookRegistry, HookExecutor, HookEvent, HookPriority } from '@monoes/hooks';

const registry = new HookRegistry();
const executor = new HookExecutor(registry);

// Register a hook
registry.register(
  HookEvent.PreEdit,
  async (context) => {
    console.log(`Editing: ${context.file?.path}`);
    return { success: true };
  },
  HookPriority.Normal,
  { name: 'log-edits' }
);

// Execute
const result = await executor.preEdit('src/app.ts', 'modify');

Hook events

| Event | When it fires | |-------|---------------| | PreToolUse / PostToolUse | Before/after any tool call | | PreEdit / PostEdit | Before/after file modification | | PreRead / PostRead | Before/after file reads | | PreCommand / PostCommand | Before/after shell commands | | PreTask / PostTask / TaskProgress | Task lifecycle | | SessionStart / SessionEnd / SessionRestore | Session lifecycle | | AgentSpawn / AgentTerminate | Agent lifecycle | | PreRoute / PostRoute | Task routing decisions | | PatternLearned / PatternConsolidated | Pattern learning |

Priorities

| Priority | Value | Use case | |----------|-------|----------| | Critical | 1000 | Security validation | | High | 100 | Pre-processing | | Normal | 50 | Standard hooks | | Low | 10 | Logging, metrics | | Background | 1 | Async, runs last |

Background workers

9 on-demand workers, all registered in WORKER_CONFIGS, each a factory function managed by WorkerManager:

| Worker | Purpose | |--------|---------| | health | Monitor disk, memory, CPU, processes | | ddd | DDD progress → .monomind/metrics/ddd-progress.json | | security | Scan for secrets and vulnerabilities | | cache | Clean temp files, old logs, stale cache | | progress | Track implementation progress | | map | Codebase map → .monomind/metrics/codebase-map.json | | audit | Security audit → .monomind/metrics/security-audit.json | | consolidate | Memory consolidation → .monomind/metrics/consolidation.json | | reflexion | Self-learning from failures — reflects on failed tasks, stores lessons for future retrieval |

The metrics-producing workers run at session start (via the CJS session handler) and are staleness-gated: each only runs when its output file is missing or older than 6 hours, with a hard per-worker timeout so session start is never blocked. WorkerManager can also schedule them on intervals, persist run state to .monomind/metrics/workers-state.json, raise threshold alerts, and export statusline data.

import { WorkerManager, createHealthWorker } from '@monoes/hooks';

const manager = new WorkerManager(process.cwd());
manager.register('health', createHealthWorker(process.cwd()));
const result = await manager.runWorker('health');

What this package does NOT do

Earlier versions carried MCP tool schemas, agent synthesis, observability traces, interrupt checkpoints, statusline generation, and swarm messaging subsystems. None of it was wired into a running server, so it was deleted. The CLI (packages/@monomind/cli/src/mcp-tools/) owns the real MCP tools; this package is just types + registry/executor + workers.

Links

• GitHub
• Documentation
• Issues

License

MIT