Agent Hooks Playground

A TypeScript/Node.js CLI toolkit that normalizes lifecycle events from three different AI coding agents (Claude Code, Codex, Pi) into a shared JSONL log file.

Overview

Each AI coding agent uses different hook mechanisms:

• Claude Code: Shell-based hooks in settings.json
• Codex: JavaScript hooks in hooks.json with trust flow
• Pi: TypeScript extensions with event subscriptions

All three agents funnel events to a single normalized logger that writes to logs/agent-events.jsonl.

Quick Start

1. Install dependencies:

   npm install

2. Build the project:

   npx tsc

3. Test the logger:

   npm run summary

Integration Guides

Choose your agent:

Claude Code Integration

• Copy claude/settings.example.json to ~/.claude/settings.json
• Ensure hook scripts are executable
• Automatic event logging on Claude session

Codex Integration

• Copy codex/hooks.example.json to .codex/hooks.json
• Run /hooks in Codex to review and trust hooks
• Automatic event logging after trust

Pi Integration

• Copy or symlink pi/extensions/agent-hooks-logger.ts to ~/.pi/agent/extensions/
• Restart Pi (or run /reload) to load extension
• Automatic event logging via extension events (source: "extension")

CLI Commands

log

Log events programmatically:

npm run log -- --agent claude --event session_start --summary "Session started" --source hook < data.json

summary

Display event statistics and recent events:

npm run summary

Output includes:

• Total event count by agent
• Event breakdown by type
• Last 10 events with timestamps

welcome

Generate welcome message for specific agent:

npm run welcome -- --agent claude

reset-logs

Clear the log file:

npm run reset-logs

Event Schema

All events follow a standardized format:

type AgentEvent = {
  id: string;           // Unique event ID
  ts: string;           // ISO 8601 timestamp
  agent: AgentName;     // "claude" | "codex" | "pi" | "manual"
  event: string;        // Event type (e.g., "session_start", "tool_call")
  sessionId?: string;   // Optional session identifier
  cwd?: string;         // Current working directory
  toolName?: string;    // Tool name for tool events
  promptPreview?: string; // First 100 chars of user prompt
  summary: string;      // Human-readable event summary
  source: "hook" | "extension" | "manual"; // Event source
  raw?: unknown;        // Original agent-specific data
};

Supported Events

Claude Code

• SessionStart: Session initialization
• UserPromptSubmit: User submits a prompt
• PreToolUse: Before tool execution
• PostToolUse: After tool execution completes
• Stop: Claude completes its response

Codex

• SessionStart: Session initialization
• UserPromptSubmit: User submits a prompt
• PreToolUse: Before tool execution
• PostToolUse: After tool execution completes
• Stop: Codex completes its response

Pi

• session_start: Session initialization
• tool_call: Tool execution

Log Format

Events are written as JSONL (one JSON object per line) to logs/agent-events.jsonl:

{"id":"evt_2026-05-23T12-00-00-000Z_abc1","ts":"2026-05-23T12:00:00.000Z","agent":"claude","event":"SessionStart","summary":"Claude Code session started","source":"hook"}
{"id":"evt_2026-05-23T12-00-05-000Z_abc2","ts":"2026-05-23T12:00:05.000Z","agent":"claude","event":"UserPromptSubmit","summary":"User submitted prompt","source":"hook","promptPreview":"Implement feature X"}

Agent Comparison

| Feature | Claude Code | Codex | Pi | |---------|-------------|-------|-----| | Hook Type | Shell scripts | JavaScript hooks | TypeScript extensions | | Configuration | settings.json | hooks.json | Extension files | | Trust Required | No | Yes (/hooks command) | No | | Event Source | Hook API | Hook API | Extension events | | Session Events | Yes | Yes | Yes | | Tool Events | Yes | Yes | Yes | | Setup Complexity | Low | Medium | Low |

Architecture

Agent Session → Hook/Extension → Normalized Event → Logger → JSONL
                                                      ↓
                                              Summary CLI reads

Components

• src/logger.ts: Core logger that writes to JSONL
• src/cli.ts: CLI interface with four commands
• src/schema.ts: TypeScript event schema definitions
• src/summarize.ts: Summary generation logic
• src/welcome.ts: Welcome message generation
• claude/hooks/: Claude-specific hook scripts
• codex/hooks/: Codex-specific hook scripts
• pi/extensions/: Pi-specific TypeScript extension

Error Handling

• Logger never throws — failures display as warnings to stderr
• CLI commands surface errors to user
• All scripts use absolute path resolution from git root
• Failed log attempts don't interrupt agent operation

Testing

Manual verification per agent:

1. Follow the integration guide for your agent
2. Trigger events by using the agent normally
3. Run npm run summary to verify events logged
4. Check for warning output on failures

License

MIT