How jgorodetsky/agenttrail works
agenttrail captures AI-agent activity through native harness hooks or an MCP stdio proxy, represents it as AOS audit events, maps events to OCSF, and delivers them locally or through a central HTTP collector. The primary workflow is hook installation → harness event → normalization and event creation → OCSF mapping → shipping and output routing. The MCP proxy is a separate fallback path for tool calls and session events. The README documents additional capture categories and output backends; those are shown where the tree supports their modules, though their implementations were not all sampled.
Main entry points: collector.py HTTP collector · proxy.py MCP proxy · handler.py Hook handler · cli.py CLI commands
Components 21
Event capture
- Hook installer
src/agenttrail/collectors/hooks/install.py - Hook handler
src/agenttrail/collectors/hooks/handler.py - MCP proxy
src/agenttrail/collectors/mcp/proxy.py - Proxy config
src/agenttrail/collectors/mcp/config.py
Event modeling
- AOS event models
src/agenttrail/schema/event.py - OCSF mapping
src/agenttrail/schema/ocsf.py
Central collection
- HTTP collector
src/agenttrail/server/collector.py
Event delivery
- Output interface
src/agenttrail/server/outputs/base.py - JSONL output
src/agenttrail/server/outputs/jsonl.py - Stdout output
src/agenttrail/server/outputs/stdout.py - Webhook output
src/agenttrail/server/outputs/webhook.py - S3 output
src/agenttrail/server/outputs/s3.py - SQS output
src/agenttrail/server/outputs/sqs.py
User interface
- CLI commands
src/agenttrail/cli.py
Other components
- Agent harness
- MCP client
- MCP server
- Local JSONL file
- Webhook destination
- AWS S3
- AWS SQS
Connections 27
- CLI commands → Hook installer: installs hooks
- Hook installer → Agent harness: registers handler
- Agent harness → Hook handler: dispatches events
- Hook handler → AOS event models: creates events
- Hook handler → OCSF mapping: maps events
- Hook handler → HTTP collector: posts events
- Hook handler → Local JSONL file: appends JSONL
- CLI commands → Proxy config: builds config
- CLI commands → MCP proxy: starts proxy
- MCP client → MCP proxy: sends messages
- MCP proxy → MCP server: relays messages
- MCP proxy → MCP client: relays responses
- MCP proxy → AOS event models: creates events
- MCP proxy → OCSF mapping: maps events
- MCP proxy → HTTP collector: posts events
- MCP proxy → Local JSONL file: appends JSONL
- CLI commands → HTTP collector: configures outputs
- HTTP collector → Output interface: routes events
- HTTP collector → JSONL output: writes events
- HTTP collector → Stdout output: writes events
- HTTP collector → Webhook output: writes events
- HTTP collector → S3 output: writes events
- HTTP collector → SQS output: writes events
- JSONL output → Local JSONL file: appends JSONL
- Webhook output → Webhook destination: posts events
- S3 output → AWS S3: uploads batches
- SQS output → AWS SQS: sends events