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.	GitHub
Reproduce	Trace for Blog (SystraceForBlog)	Provide the Perfetto, Systrace, and related case files used by articles for hands-on reproduction.	GitHub

Register the public Android Internals Wiki (or your own team documents) as a document knowledge base so analyses can search it on demand and cite its sources. See the Android Internals Knowledge guide.

What It Does

• Analyzes Android Perfetto traces for scrolling jank, startup, ANR, interaction latency, memory, game, and rendering-pipeline issues.
• Investigates continuous main-thread work during scrolling and window animations, including tasks between doFrame callbacks, their execution/wait time and source clues. FrameTimeline provides outcome evidence; missing frames do not hide tasks.
• Keeps Perfetto's timeline and SQL workflow, then adds an AI Assistant for evidence-backed conclusions, follow-up questions, comparisons, and reports. At the turn limit, it delivers a conclusion from collected evidence with remaining gaps. Follow-ups inherit authorized history in the same session, including after reopening the page or restarting the backend.
• Uses deterministic YAML Skills and Markdown strategies so factual evidence, model interpretation, and report provenance remain separate.
• Relates critical tasks to CPU frequency, system load, thread states, CPU placement and scheduling evidence when the question needs them. Scene-wide investigations start with the strategy's entry Skill when its trace and process prerequisites are satisfied; missing evidence remains explicit.
• Optionally selects registered local source per run, uses bounded on-demand lookup without requiring an index, and separates trace occurrence from CodeRef mechanism evidence in safe Web, report, CLI, snapshot, and API provenance. Choose a folder and Add and use for analysis to get started; see the source analysis guide for excluded paths and optional indexing. Relevant snippets are sent to the configured AI service; source lookup adds analysis time. Results and quoted source can be retained in local history and exports; AI-service retention depends on its policy.
• Optionally selects registered document knowledge bases per turn (such as the Android Internals Wiki or team documents), searched on demand and cited; a knowledge base is background, never a substitute for current-trace evidence. See Android Internals Knowledge.
• Delivers first, verifies after: the Claude and OpenAI runtimes stream the answer as a draft while it is written. A finished answer remains readable while an eligible, budgeted no-tool review checks it. Stopping that review keeps the answer; full and forced stops have separate semantics.
• Opens a critical-path wait-chain drawer on a selected thread_state, and a flamegraph page for CPU call-stack hotspots, both with a rule-based fallback AI summary. See Critical Path And Flamegraph.
• Captures traces from a connected Android device with smp capture, from presets or your own config, optionally analyzing right after capture.
• Sends UI selections as identity and time bounds only; the backend re-queries descriptive facts and runs /anr or /jank through the same evidence and verification pipeline.
• 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

If npm reports that dependency install scripts were blocked or skipped, review those scripts and retry with approval limited to the required packages:

npm install -g @gracker/smartperfetto --allow-scripts=better-sqlite3,opencode-ai

better-sqlite3 provides the native SQLite binding used by core CLI commands; opencode-ai needs its install script when selecting the OpenCode runtime. Package-publisher approvals do not approve scripts for your installation. See npm's install policy and the CLI installation guide for project-local approval and doctor/query checks.

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.

Pi users can configure reasoning in model JSON; see the Pi configuration for provider defaults, explicit off and supported effort mappings.

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.

Server verification details are collapsed by default; expand them to read the full record. Verification warnings remain visible. Completed analyses are delivered normally, with verification concerns and coverage gaps labelled separately for users to assess against the evidence. Web, CLI and exported reports retain each claim's evidence and verification status. A malformed claim leaves other valid claims eligible for checking; missing proof and a contradicted claim remain distinct outcomes. Explicitly bound numeric displays are checked against captured evidence before semantic review, including unit conversion and rounding; model agreement cannot override a wrong display. Raw citations and propositions retain full precision. Correct formatting proves neither scope nor causality; older output retains the conservative rounding-warning path. 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. HTML reports retain captured table columns, nested values and provenance. Metric tables show declared units and explicit warning labels; ordinary observations carry no health verdict. Save HTML uses a local browser download, and printing expands captured details. See HTML analysis reports for historical report limits.

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, 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

GitHub Actions runs clean Linux build/contract checks on every PR/main push, with Rust, macOS/Windows and Docker checks scoped to affected paths. Run the complete npm run verify:pr locally before opening or landing a PR; full hosted regression is available by manually running backend-agent-regression-gate.yml with full=true. See verification ownership.

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.