SmartPerfetto

English | 中文

AI-powered Android performance analysis built on Perfetto.

SmartPerfetto adds an AI analysis layer to Perfetto traces. Load a trace, ask a natural-language question, and get an evidence-backed answer with SQL results, Skill outputs, root-cause reasoning, and optimization suggestions.

The project is open source and in active development. The Web UI, CLI, backend runtime, and Skill system are usable today, while public APIs and internal contracts may still evolve.

Android performance ecosystem

The Android Performance Ecosystem brings its navigation Hub and seven core projects into an optional path from instrumentation and capture to analysis, system knowledge, and reproducible cases.

Stage	Project	Purpose	Address
Navigate	Android Performance Ecosystem	Maintain the shared project map, handoff metadata, generated README navigation, and drift checks.	GitHub
Instrument	TraceFix	Inject app-side android.os.Trace sections at build time so method work is visible at runtime.	GitHub
Capture and measure	Perfetto Tools	Capture repeatable Perfetto traces and collect FPS or Simpleperf measurements.	GitHub
Analyze	SmartPerfetto	Investigate traces with an AI-assisted Web UI, CLI, reports, sessions, comparisons, and evidence workflow.	GitHub
Agent analysis	Perfetto Skills	Give agents a portable Perfetto analysis Skill for Android, Linux, and Chromium, with selected assets synchronized through pinned workflows.	GitHub
Learn	Android Performance Blog	Teach Perfetto and Systrace analysis through articles, system explanations, and case studies.	AndroidPerformance.com · GitHub
System knowledge	Android Internal Wiki	An alpha knowledge base for Android mechanisms from App to Framework, Native, and Kernel.	Coming soon
Reproduce	Trace for Blog (SystraceForBlog)	Provide the Perfetto, Systrace, and related case files used by articles for hands-on reproduction.	GitHub

What It Does

• Analyzes Android Perfetto traces for scrolling jank, startup, ANR, interaction latency, memory, game, and rendering-pipeline issues.
• Keeps Perfetto's timeline and SQL workflow, then adds an AI Assistant for evidence-backed conclusions, follow-up questions, comparisons, and reports.
• Uses deterministic YAML Skills and Markdown strategies so factual evidence, model interpretation, and report provenance remain separate.
• Supports the browser UI, the smp CLI, and HTTP/SSE integration. See the Feature Overview for the complete scope.

Quick Start

1. Choose A Distribution

• Windows desktop: download the windows-x64 archive from the latest release, extract it completely, and run SmartPerfetto.exe. Follow the Windows Guide.

• macOS or Linux desktop: use the matching portable release asset. The package includes Node.js, the backend, pre-built UI, and trace processor.

• Docker: clone the repository, then run:

  docker compose -f docker-compose.hub.yml up -d

• Source checkout: requires Node.js 24 LTS. Clone the repository, then run:

  ./start.sh

• Terminal or automation: install the standalone CLI with Node.js 24:

  npm install -g @gracker/smartperfetto
  smp doctor

The complete prerequisites and distribution choices are in the Quick Start.

2. Configure One AI Provider

After the Web UI starts, open AI Assistant Settings → Providers, add one provider, save it, test it, and activate it. Local source runs may instead use an existing Claude Code login from the same terminal. Do not configure every runtime for the first launch; choose one provider path and follow the Configuration Guide.

3. Run Your First Analysis

1. Open the launcher's printed Open: URL, or http://localhost:10000 for the default Docker or source setup.
2. Load a .pftrace or .perfetto-trace file.
3. Open the AI Assistant panel.
4. Ask a question such as Analyze scrolling jank, Why is startup slow?, or Analyze the ANR in this trace.

For CLI use:

smp run trace.pftrace "Analyze scrolling jank"

Documentation

• Start here: Documentation Center, Quick Start, and Basic Usage
• Product setup: Windows Guide, Configuration, Application Updates, and Troubleshooting
• Integration: CLI, HTTP/SSE API, and MCP Tools
• Internals: Architecture Overview, Technical Architecture, and Skill System

Contributing And Support

Read CONTRIBUTING.md before opening a pull request. Use GitHub Issues for bugs and feature requests, and the private advisory or smartperfetto@gracker.dev for security reports. Sponsorship and commercial support details are in docs/sponsor.en.md.

License

AGPL-3.0-or-later for SmartPerfetto core code. The perfetto/ submodule remains under Apache-2.0. For commercial licensing without AGPL obligations, contact the maintainer on WeChat: 553000664.