add-a-claude-code-hook

Add a Claude Code Hook

How to add a new lifecycle hook to the agentic-memory system. There are 4 lifecycle hooks today (PreToolUse, SessionStart, Stop/PostToolUse, plus a 5th log redirect helper); this is how to add a 6th.

The 60-second version

1. Create hooks/memory_your_event.py at the repo root.
2. Wire it into the user's Claude Code config (typically ~/.claude/settings.json or opencode config).
3. The hook receives JSON on stdin, prints to stdout (NOT stderr — that was a 2-day bug).
4. Test with a manual JSON invocation: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | python hooks/memory_your_event.py

Total: ~30 minutes for a read-only hook, ~2 hours for one that mutates state.

Lifecycle event types

Event	When it fires	What you get	What you can do
SessionStart	New session begins	session_id, cwd, hook_event_name	Inject context, load memory
UserPromptSubmit	User types a message	prompt, session_id, cwd	Pre-process prompt, inject context
PreToolUse	Before any tool call	tool_name, tool_input, session_id	Modify tool_input, inject context, deny
PostToolUse	After any tool call	tool_name, tool_input, tool_output, session_id	React to result, save, validate
Stop	Agent stops responding	session_id, last_user_message, last_assistant_message	Save snapshot, ping user
SessionEnd	Session deleted	session_id, reason, duration_seconds	Final save, cleanup

The current lifecycle hooks: memory-proactive-context.py (PreToolUse), memory-session-start.py (SessionStart), memory-session-end.py (Stop/PostToolUse, enforces Rule #7), and the log redirect _log_error.py. The auto-save flow runs on PostToolUse via auto_save.py.

Step 1: write the hook

#!/usr/bin/env python3
"""Hook: <event> — what this does in one line.

Triggered by: <where in claude config>
Input: JSON on stdin with <list of fields>
Output: <what to print, where>
"""
import sys
import json
import os

# Use the user's Python (M8 fix)
sys.path.insert(0, os.path.expanduser("~/.config/agentic-memory"))

def main():
    try:
        # Read input
        raw = sys.stdin.read()
        data = json.loads(raw) if raw else {}
    except Exception as e:
        # NEVER crash a hook silently. Print to stderr, return.
        print(f"hook: failed to parse stdin: {e}", file=sys.stderr)
        return

    # Extract what you need
    event = data.get("hook_event_name", "unknown")
    session_id = data.get("session_id", "unknown")
    tool_name = data.get("tool_name", "")
    tool_input = data.get("tool_input", {})

    # Do your work
    result = your_logic(event, session_id, tool_name, tool_input)

    # Print to STDOUT — this is what Claude Code injects
    print(result)

if __name__ == "__main__":
    main()