Internal Hooks: Event-Driven Automation for Agent Commands

This PR introduces internal hooks, a new first-class feature that enables event-driven automation in response to agent commands and lifecycle events. Hooks allow you to trigger custom TypeScript functions when events like /new, /reset, or /stop occur, without modifying Clawdbot's core code.

What Are Internal Hooks?

Internal hooks provide an extensible system for automating actions in response to agent events:

• Listen to agent commands - React when users issue /new, /reset, /stop
• Run custom TypeScript code - Full access to Node.js APIs, file system, external services
• No core modifications needed - Extend behavior without touching Clawdbot internals
• Event-driven architecture - Handlers are called automatically when events fire

Use cases:

• Save session context to memory when starting a new conversation
• Log all commands for auditing and debugging
• Automatically commit code changes before resetting
• Send notifications to external services
• Archive conversations to cloud storage
• Any automation triggered by agent lifecycle events

Example: Simple Hook Handler

import type { InternalHookHandler } from '../../src/hooks/internal-hooks.js';

const myHandler: InternalHookHandler = async (event) => {
  if (event.type !== 'command' || event.action !== 'new') {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  console.log(`  Session: ${event.sessionKey}`);
  
  // Your custom logic here - file operations, API calls, etc.
  
  // Optionally send message to user
  event.messages.push('✨ Hook executed!');
};

export default myHandler;

Hooks System: First-Class Feature Alongside Skills

This implementation makes hooks a first-class feature with the same patterns as skills: automatic discovery, CLI management, and eligibility gating.

Automatic Directory-Based Discovery

Hooks are automatically discovered from three tiers (matching skills pattern):

1. Workspace hooks (<workspace>/hooks/) - Per-agent, highest precedence
2. Managed hooks (~/.clawdbot/hooks/) - User-installed, shared across workspaces
3. Bundled hooks (<clawdbot>/dist/hooks/bundled/) - Shipped with Clawdbot (compiled)

No manual config editing required.

CLI Management Suite

# List all available hooks
clawdbot hooks internal list [--eligible] [--json] [--verbose]

# Get detailed information
clawdbot hooks internal info <name> [--json]

# Check eligibility status
clawdbot hooks internal check [--json]

# Enable/disable hooks with one command
clawdbot hooks internal enable session-memory
clawdbot hooks internal disable command-logger

HOOK.md Metadata Format

Each hook is a directory containing:

• HOOK.md - YAML frontmatter + JSON metadata + Markdown documentation
• handler.ts (source) / handler.js (compiled) - Handler implementation

---
name: my-hook
description: "Short description"
homepage: https://docs.clawd.bot/hooks/my-hook
metadata: {"clawdbot":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
---

Eligibility Gating

Hooks can declare requirements that are automatically checked:

• Required binaries on PATH
• Required environment variables
• Required config values
• OS platform compatibility

Only eligible hooks are loaded and presented to users.

Onboarding Integration

The onboarding wizard now automatically discovers eligible hooks and presents them for selection, just like skills. No hardcoded lists.

Configuration Format

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}

Legacy handlers[] format still supported for backwards compatibility.

Architecture

New Modules (8):

• src/hooks/types.ts - Core type definitions
• src/hooks/workspace.ts - Three-tier directory scanning
• src/hooks/frontmatter.ts - HOOK.md metadata parser
• src/hooks/config.ts - Eligibility checking
• src/hooks/bundled-dir.ts - Bundled hooks resolver (supports both dev and compiled paths)
• src/hooks/hooks-status.ts - Status report builder
• src/cli/hooks-internal-cli.ts - Full CLI suite
• scripts/copy-hook-metadata.ts - Build step to copy HOOK.md files alongside compiled JS

Core Hook System:

• src/hooks/internal-hooks.ts - Event registration and triggering
• src/hooks/loader.ts - Updated for directory discovery + legacy support
• src/commands/onboard-hooks.ts - Uses discovery instead of hardcoded config
• src/gateway/server-startup.ts - Loads hooks on startup

Event Triggers:

• src/auto-reply/reply/commands-core.ts - Triggers command events
• src/auto-reply/reply/commands-session.ts - Triggers session events

Bundled Hooks: Real-World Examples

1. Session Memory Hook (Solves Real User Pain)

Problem: Users have reported that some of the cheaper models (Minimax, z.ai, DeepSeek, etc.) are less eager to update memories on their own during conversations. They often need explicit prompting to save context to memory, which creates friction.

Solution: The session-memory bundled hook automatically saves session context when you issue /new, forcing memory updates without requiring model cooperation.

What it does:

1. Triggers on /new command
2. Finds the previous session file (most recent before reset)
3. Extracts the last 15 lines of conversation
4. Uses LLM to generate a descriptive filename slug
5. Saves session metadata and conversation content to ~/clawd/memory/YYYY-MM-DD-slug.md

Example output files:

• 2026-01-16-vendor-pitch.md
• 2026-01-16-api-design.md
• 2026-01-16-bug-fix.md
• 2026-01-16-1430.md (fallback timestamp if slug generation fails)

Onboarding Option:

During clawdbot onboard, users are now prompted to enable this hook:

? Enable internal hooks?
  [ ] Skip for now
  [x] 💾 session-memory - Save session context to memory when /new command is issued

This ensures memory is always captured, regardless of which model you're using.

2. Command Logger Hook

Logs all command events to ~/.clawdbot/logs/commands.log in JSONL format for auditing and debugging.

What it does:

• Captures all command events (/new, /reset, /stop, etc.)
• Logs timestamp, action, session key, sender ID, source
• Appends to log file in JSONL format
• Runs silently in the background

Use cases:

• Debugging: Track when commands were issued and from which source
• Auditing: Monitor command usage across different channels
• Analytics: Analyze command patterns and frequency

NPM Distribution & Compilation

Fixes Applied:

1. Bundled Hooks Compilation (c227a83)

Issue: Initial implementation shipped bundled hooks as TypeScript source files, which failed to load when installed via npm with error:

Stripping types is currently unsupported for files under node_modules

Solution:

• Moved bundled hooks from hooks/bundled/ to src/hooks/bundled/ for TypeScript compilation
• Added scripts/copy-hook-metadata.ts build step to copy HOOK.md files alongside compiled JS
• Updated resolveBundledHooksDir() to resolve both compiled (dist/hooks/bundled/) and source (src/hooks/bundled/) locations
• Bundled hooks now ship as compiled JavaScript in dist/hooks/bundled/ with metadata files

2. LLM Slug Generator Import Path (c227a83)

Issue: Session-memory hook failed with module not found error due to incorrect import path (dist/hooks/dist/hooks/llm-slug-generator.js).

Solution: Fixed import path resolution to correctly locate llm-slug-generator.js at dist/hooks/llm-slug-generator.js from compiled handler location.

3. Conversation Content in Memory Files (5cab0c7)

Issue: Session-memory hook was only saving session metadata (session key, ID, source) without the actual conversation content.

Solution:

• Store sessionContent in accessible scope (not just for slug generation)
• Add "## Conversation Summary" section to memory file output
• Include the last 15 lines of conversation in the saved memory

This ensures hooks work correctly in both development (TypeScript source) and production (compiled JavaScript from npm), and that memory files contain complete conversation context.

Documentation

• docs/internal-hooks.md - Complete guide (779 lines)

  • What internal hooks are and how they work
  • Directory-based discovery system
  • Three-tier hierarchy explanation
  • HOOK.md metadata format
  • CLI command reference
  • Bundled hooks documentation
  • Creating custom hooks guide
  • Event types and handler API
  • Best practices and troubleshooting

• docs/cli/hooks.md - CLI reference (232 lines)

  • All hooks internal commands
  • Usage examples
  • Bundled hooks quick reference

Testing

• ✅ All hook tests passing (43 tests)
• ✅ CLI commands tested and verified
• ✅ Gateway integration confirmed with compiled bundled hooks
• ✅ Build successful
• ✅ Lint checks pass (0 warnings, 0 errors)
• ✅ 3406/3407 tests passing (99.97%)
• ✅ Hooks load correctly when installed via npm/Volta
• ✅ Session-memory hook tested end-to-end with real conversation capture

The 1 failing test is a pre-existing timezone flaky test unrelated to this PR.

Benefits

• New Capability - Event-driven automation without core modifications
• Consistency with Skills - Same discovery, management, and eligibility patterns
• No Manual Config Editing - Simple CLI commands for enable/disable
• Automatic Discovery - Hooks are found automatically from standard locations
• Better Documentation - Each hook has its own HOOK.md with full docs
• Eligibility Checking - Hooks with missing requirements are clearly identified
• Improved UX - Onboarding wizard presents available hooks automatically
• Solves Real Problems - Session memory hook addresses pain with cheaper models
• Production Ready - Hooks compile to JavaScript and work in npm distribution

This introduces internal hooks as a first-class feature alongside skills, with two practical bundled examples that demonstrate the system's capabilities and solve real user needs.