agtrace: Skill for Claude Code

Agtrace Provider Normalization Expert

This skill provides deep knowledge of how agtrace normalizes diverse AI agent log formats into unified domain types. Use this when working with provider implementations, tool normalization, or understanding the schema-on-read architecture.

Quick Reference

mise run test:providers          # Run provider tests
mise run test:types              # Run types tests
mise run lab:grep -- "pattern" --json --limit 5  # Search real event data
mise run verify                  # Full check (fmt + clippy + test + build)

Three-Tier Provider Architecture

Tier 1: Trait-Based Adapter Pattern

Every provider implements three core traits bundled in a ProviderAdapter:

LogDiscovery  -> File discovery and session location
SessionParser -> Raw log parsing to AgentEvent timeline
ToolMapper    -> Tool call normalization and classification

Key Files:

• crates/agtrace-providers/src/traits.rs - trait definitions
• crates/agtrace-providers/src/registry.rs - adapter factory

Tier 2: Provider-Specific Implementation

Each provider has this structure:

provider/
├── discovery.rs      # LogDiscovery trait impl
├── parser.rs         # SessionParser trait impl
├── mapper.rs         # ToolMapper trait impl
├── io.rs             # Raw file I/O
├── schema.rs         # Provider-specific schemas
├── tools.rs          # Provider-specific tool args
├── tool_mapping.rs   # Tool classification
└── models.rs         # Data structures

Provider directories:

• crates/agtrace-providers/src/claude/
• crates/agtrace-providers/src/codex/

Tier 3: Unified Domain Types

All providers normalize to common types in agtrace-types:

Type	Location	Variants
EventPayload	event/payload.rs	User, Reasoning, ToolCall, ToolResult, Message, TokenUsage, Notification, SlashCommand
ToolCallPayload	tool/payload.rs	FileRead, FileEdit, FileWrite, Execute, Search, Mcp, Generic
ToolKind	tool/types.rs	Read, Write, Execute, Plan, Search, Ask, Other
ToolOrigin	tool/types.rs	System, Mcp