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 Internals Knowledge | Use the signed bundled public Knowledge Pack, with an optional private android-internals-wiki checkout for approved local context. | Guide | | 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,

• Investigates continuous main-thread work during scrolling and window animations,

• Keeps Perfetto's timeline and SQL workflow, then adds an AI Assistant for

• Uses deterministic YAML Skills and Markdown strategies so factual evidence,

• Optionally selects registered local source per run, uses bounded on-demand

• Sends UI selections as identity and time bounds only; the backend re-queries

• Supports the browser UI, the smp CLI, and HTTP/SSE integration. See the

Quick Start

1. Choose A Distribution

• Windows desktop: download the windows-x64 archive from the

• macOS or Linux desktop: use the matching portable release asset. The

• 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 configure explicit provider credentials in backend/.env. Claude Code login does not configure the SDK. Do not configure every runtime for the first launch; choose one provider path and follow the Configuration Guide. Advanced Qoder users can also route models through the documented BYOK policy while keeping Qoder PAT or qodercli authentication separate. Saved providers also refresh their model suggestions from supported provider catalogs with a bounded cache; unsupported or unavailable catalogs keep the curated preset list.

3. Run Your First Analysis

1. Open the launcher's printed Open: URL, or

1. Load a .pftrace or .perfetto-trace file.
2. Open the AI Assistant panel.
3. Ask a question such as Analyze scrolling jank, Why is startup slow?, or

Server verification details are collapsed by default; expand them to read the full record. Verification warnings remain visible. Final conclusions retain all material findings, supporting evidence and limitations within the requested scope, even when intermediate tables are hidden. Length alone does not justify dropping findings or claims. Final answers prefer compact tables for comparable metrics, phase timings and trace differences, alongside explanations and evidence references. Single values and questions better answered in prose remain free-form.

Each round shows its analysis process and steps above its final conclusion, which stays before the next round's question.

For CLI use:

smp run trace.pftrace "Analyze scrolling jank"

Incomplete CLI runs show the termination reason and available diagnostics; a report body can still fail evidence or declaration checks. See the CLI result guidance.

Documentation

• Start here: Documentation Center,

• Product setup: Windows Guide,

• Integration: CLI,

• Internals: Architecture Overview,

Contributing And Support

Read CONTRIBUTING.md before opening a pull request. Use GitHub Issues for bugs and feature requests, and the private advisory or [email protected] 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.

System investigation across scenes

Performance investigations relate critical tasks to CPU frequency, system load, thread states, CPU placement and scheduling evidence when relevant to the question. Root-cause strategy details are read in full. Answers report missing evidence explicitly; investigation coverage is assessed independently of report headings and native runtime completion. See Basic Usage.

The conclusion body is retained in full. Web, CLI and exported reports expose each claim's evidence and server verification details, including failed or unchecked claims. Finding a source does not establish that a claim or root cause is verified.