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.

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