@principal-ai/agent-monitoring

Agent event monitoring and processing system for AI coding assistants.

Overview

This package provides a unified monitoring and event processing system for various AI coding assistants including Claude, Cline, and OpenCode. It offers:

• Normalized event types across different agents
• Path normalization and file operation detection
• Event processors for each supported agent
• Hook configuration utilities
• Type-safe event handling

Installation

bun install @principal-ai/agent-monitoring

Features

Supported Agents

• Claude (Anthropic's CLI)
• Cline (VS Code extension)
• OpenCode (Open source CLI)
• Droid (Factory AI)

Event Processing

• Unified event normalization across agents
• Tool usage tracking
• File operation detection
• Path context analysis

Hook Configuration

• Agent-specific hook types
• Configurable matchers
• Event filtering

Usage

import {
  SupportedAgent,
  ClaudeEventProcessor,
  AgentEventPipeline,
  CLAUDE_HOOK_TYPES,
} from "@principal-ai/agent-monitoring";

// Process a raw Claude event
const processor = new ClaudeEventProcessor();
const universalEvent = processor.normalize(rawClaudeHookData);

// Or use the full pipeline with path normalization
const pipeline = new AgentEventPipeline(pathAdapter, {
  metrics: {
    onEventProcessed: (event, durationMs, agent) => {
      console.log(`Processed ${agent} event in ${durationMs}ms`);
    },
  },
});

const normalizedEvent = await pipeline.processRawEvent(
  SupportedAgent.CLAUDE,
  rawClaudeHookData
);

// Access normalized data
console.log(normalizedEvent.repository?.branch);
console.log(normalizedEvent.files?.map(f => f.displayPath));

API Reference

Types

• SupportedAgent - Enum of supported AI agents (claude, cline, opencode, droid)
• UniversalAgentSessionEvent - Agent-normalized event format (intermediate)
• RepoNormalizedUniversalAgentSessionEvent - Final event format with repository context
• NormalizedPathInfo - File path with repository metadata and context
• PathContext - File classification enum (REPO_FILE, SYSTEM_FILE, USER_FILE, TEMP_FILE, CONFIG_FILE)
• FileOperation - Operation type enum (READ, WRITE, CREATE, DELETE, EDIT, SEARCH, LIST)

Event Processors

• ClaudeEventProcessor - Normalize Claude hook events
• ClineEventProcessor - Normalize Cline hook events
• OpenCodeEventProcessor - Normalize OpenCode hook events
• DroidEventProcessor - Normalize Droid hook events

Pipeline

• AgentEventPipeline - Full processing pipeline with path normalization
• PathNormalizationService - Service for enriching paths with repository context

Hook Types

• CLAUDE_HOOK_TYPES - Available Claude hook event types
• CLINE_HOOK_TYPES - Available Cline hook event types
• OPENCODE_HOOK_TYPES - Available OpenCode hook event types
• DROID_HOOK_TYPES - Available Droid hook event types

Utility Functions

• getAvailableHookTypes(agent) - Get hook types for a specific agent
• getHookTypeDisplayName(hookType) - Get human-readable hook type name
• getHookTypeDescription(hookType) - Get hook type description
• isToolEvent(event) - Check if event is a tool use event
• isStopEvent(event) - Check if event is a stop event
• getEventFilePaths(event) - Extract file paths from an event
• classifyPath(path) - Classify a file path into a PathContext

License

MIT