Architecture

Project Structure

src/perfetto_cli/
├── cli.py                 # Main CLI entry point (Click groups)
├── types.py               # Shared type definitions
├── core/
│   ├── trace_processor.py # TraceProcessor wrapper
│   ├── query_engine.py    # SQL query execution engine
│   ├── trace_config.py    # Trace capture configuration
│   ├── trace_session.py   # Device trace session management
│   ├── adb.py             # ADB device communication
│   └── skill_manager.py   # Skills plugin system
├── commands/
│   ├── anr.py             # ANR detection commands
│   ├── frame.py           # Frame performance commands
│   ├── cpu.py             # CPU analysis commands
│   ├── memory.py          # Memory analysis commands
│   ├── binder.py          # Binder profiling commands
│   ├── query.py           # SQL query commands
│   ├── trace.py           # Trace capture commands
│   └── skills.py          # Skills management commands
├── formatters/
│   ├── text_fmt.py        # Rich text formatter
│   ├── table_fmt.py       # ASCII table formatter
│   └── json_fmt.py        # JSON formatter
└── utils/
    └── sql_helpers.py     # SQL query utilities

Key Design Decisions

Click-based CLI

The CLI uses Click with nested command groups. Each domain (anr, frame, cpu, etc.) is a Click group with subcommands.

TraceProcessor Wrapper

All trace analysis goes through core/trace_processor.py, which manages the lifecycle of the trace_processor binary from the Perfetto SDK. Queries are executed via the Perfetto Python API.

Formatter Pattern

Output formatting is decoupled from analysis logic. Each command returns structured data, and the formatter layer handles presentation based on the -f flag.

Query Engine

core/query_engine.py provides a reusable interface for executing PerfettoSQL queries. Analysis commands compose complex queries using utils/sql_helpers.py.

Dependencies

Package	Purpose
click	CLI framework and argument parsing
rich	Terminal formatting and colored output
perfetto	Trace processing (bundles trace_processor)