# jgorodetsky/agenttrail architecture

> Architecture diagram of the GitHub repository jgorodetsky/agenttrail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jgorodetsky/agenttrail
- Repository: https://github.com/jgorodetsky/agenttrail

## Overview

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: [`src/agenttrail/server/collector.py`](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/collector.py) (HTTP collector), [`src/agenttrail/collectors/mcp/proxy.py`](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/mcp/proxy.py) (MCP proxy), [`src/agenttrail/collectors/hooks/handler.py`](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/hooks/handler.py) (Hook handler), [`src/agenttrail/cli.py`](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/cli.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Event capture"]
  node_hook_install["Hook installer<br/>[install.py]"]
  node_hook_handler["Hook handler<br/>[handler.py]"]
  node_mcp_proxy["MCP proxy<br/>[proxy.py]"]
  node_proxy_config["Proxy config<br/>[config.py]"]
end

subgraph group_schema["Event modeling"]
  node_audit_events["AOS event models<br/>[event.py]"]
  node_ocsf_mapping["OCSF mapping<br/>[ocsf.py]"]
end

subgraph group_collection["Central collection"]
  node_collector["HTTP collector<br/>[collector.py]"]
end

subgraph group_delivery["Event delivery"]
  node_output_base["Output interface<br/>[base.py]"]
  node_jsonl["JSONL output<br/>[jsonl.py]"]
  node_stdout["Stdout output<br/>[stdout.py]"]
  node_webhook["Webhook output<br/>[webhook.py]"]
  node_s3["S3 output<br/>[s3.py]"]
  node_sqs["SQS output<br/>[sqs.py]"]
end

subgraph group_interface["User interface"]
  node_cli["CLI commands<br/>[cli.py]"]
end

node_agent(("Agent harness"))
node_mcp_client(("MCP client"))
node_mcp_server["MCP server"]
node_local_file[("Local JSONL file")]
node_siem["Webhook destination"]
node_aws_s3[("AWS S3")]
node_aws_sqs["AWS SQS"]

node_cli -->|"installs hooks"| node_hook_install
node_hook_install -->|"registers handler"| node_agent
node_agent -->|"dispatches events"| node_hook_handler
node_hook_handler -->|"creates events"| node_audit_events
node_hook_handler -->|"maps events"| node_ocsf_mapping
node_hook_handler -.->|"posts events"| node_collector
node_hook_handler -.->|"appends JSONL"| node_local_file
node_cli -->|"builds config"| node_proxy_config
node_cli -->|"starts proxy"| node_mcp_proxy
node_mcp_client -->|"sends messages"| node_mcp_proxy
node_mcp_proxy -->|"relays messages"| node_mcp_server
node_mcp_proxy -->|"relays responses"| node_mcp_client
node_mcp_proxy -->|"creates events"| node_audit_events
node_mcp_proxy -->|"maps events"| node_ocsf_mapping
node_mcp_proxy -.->|"posts events"| node_collector
node_mcp_proxy -.->|"appends JSONL"| node_local_file
node_cli -->|"configures outputs"| node_collector
node_collector -->|"routes events"| node_output_base
node_collector -->|"writes events"| node_jsonl
node_collector -->|"writes events"| node_stdout
node_collector -->|"writes events"| node_webhook
node_collector -->|"writes events"| node_s3
node_collector -->|"writes events"| node_sqs
node_jsonl -->|"appends JSONL"| node_local_file
node_webhook -->|"posts events"| node_siem
node_s3 -->|"uploads batches"| node_aws_s3
node_sqs -->|"sends events"| node_aws_sqs

click node_cli "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/cli.py"
click node_hook_install "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/hooks/install.py"
click node_hook_handler "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/hooks/handler.py"
click node_mcp_proxy "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/mcp/proxy.py"
click node_proxy_config "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/mcp/config.py"
click node_audit_events "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/schema/event.py"
click node_ocsf_mapping "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/schema/ocsf.py"
click node_collector "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/collector.py"
click node_output_base "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/base.py"
click node_jsonl "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/jsonl.py"
click node_stdout "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/stdout.py"
click node_webhook "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/webhook.py"
click node_s3 "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/s3.py"
click node_sqs "https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/sqs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hook_install,node_hook_handler,node_mcp_proxy,node_proxy_config,node_mcp_client toneBlue
class node_audit_events,node_ocsf_mapping,node_local_file,node_aws_s3 toneAmber
class node_collector,node_mcp_server,node_siem toneMint
class node_output_base,node_jsonl,node_stdout,node_webhook,node_s3,node_sqs toneRose
class node_cli,node_agent,node_aws_sqs toneIndigo
```

## Components

### Event capture

- [Hook installer](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/hooks/install.py): `src/agenttrail/collectors/hooks/install.py`
- [Hook handler](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/hooks/handler.py): `src/agenttrail/collectors/hooks/handler.py`
- [MCP proxy](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/mcp/proxy.py): `src/agenttrail/collectors/mcp/proxy.py`
- [Proxy config](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/collectors/mcp/config.py): `src/agenttrail/collectors/mcp/config.py`

### Event modeling

- [AOS event models](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/schema/event.py): `src/agenttrail/schema/event.py`
- [OCSF mapping](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/schema/ocsf.py): `src/agenttrail/schema/ocsf.py`

### Central collection

- [HTTP collector](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/collector.py): `src/agenttrail/server/collector.py`

### Event delivery

- [Output interface](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/base.py): `src/agenttrail/server/outputs/base.py`
- [JSONL output](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/jsonl.py): `src/agenttrail/server/outputs/jsonl.py`
- [Stdout output](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/stdout.py): `src/agenttrail/server/outputs/stdout.py`
- [Webhook output](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/webhook.py): `src/agenttrail/server/outputs/webhook.py`
- [S3 output](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/s3.py): `src/agenttrail/server/outputs/s3.py`
- [SQS output](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/server/outputs/sqs.py): `src/agenttrail/server/outputs/sqs.py`

### User interface

- [CLI commands](https://github.com/jgorodetsky/agenttrail/blob/main/src/agenttrail/cli.py): `src/agenttrail/cli.py`

### Other components

- **Agent harness**
- **MCP client**
- **MCP server**
- **Local JSONL file**
- **Webhook destination**
- **AWS S3**
- **AWS SQS**

## Connections

- 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