SmartPerfetto is now fully open source. Open the repository and you can see the runnable mainline project as it exists today: the Perfetto UI fork, the agentv3 backend, MCP tools, YAML Skills, scene strategies, scripts, and documentation. There is no private core module kept outside the repository, and this is not just a thin demo shell.
The project comes from a very concrete daily workflow: you have a trace in hand, Perfetto has already exposed the facts, but moving from facts to judgment still means jumping through tables, writing SQL, matching threads, checking FrameTimeline, finding the Binder peer, and then returning to the timeline to confirm everything again. SmartPerfetto tries to turn those repeated actions into tools, so performance engineers can spend more time on judgment.
It is still in development. I am releasing it now because trace analysis grows from real samples: real devices, real vendor differences, real product traces, and real PRs all change how Skills and strategies should be written. Waiting until every capability is stable before publishing it one way would miss the stage where samples matter most.
If you often open Perfetto to inspect scrolling jank, startup, ANR, Binder, CPU scheduling, or rendering pipelines, SmartPerfetto provides a Perfetto UI with an AI Assistant. After loading a trace, you ask questions in natural language. The backend queries trace_processor_shell, invokes YAML Skills, organizes evidence, and streams conclusions plus data tables back into the browser.
Project links:
- Main repository: https://github.com/Gracker/SmartPerfetto
- Perfetto UI fork: https://github.com/Gracker/perfetto
For normal trial use, you only need the main repository. Gracker/perfetto is the frontend fork used by the perfetto/ submodule. It mainly matters to developers who want to modify the AI Assistant plugin UI.
The previous two technical articles are better for readers who want the engineering details:
- From Trace to Insight: Harness Engineering in SmartPerfetto AI Agent: the architecture of the SmartPerfetto AI Agent and the Harness Engineering process.
- SmartPerfetto Architecture Q&A: 8 In-Depth Technical Questions: Q&A around the Agent, Workflow, and YAML Skills.
Those two articles go deep into the internal architecture. Once the source is public, readers usually care more about what is actually in the repository, whether it can run, and which parts are not stable yet. This article focuses on the open-source release itself: what is open, what works today, how the internal pieces are divided, how to run it locally, and where collaboration is most useful.
Version note (reviewed October 14, 2026): This is the April 29 open-source announcement. Its architecture, 165 Skills, 12 strategies, and tool list are checked against that evening’s d08b066. Diagrams and screenshots retain the earlier design; they are not a current capability inventory. “How to Run It” below now targets v1.16.2; other sections preserve the historical context and identify later changes.
What Is Open Source
SmartPerfetto open sources the full engineering stack from UI to analysis rules. It keeps Perfetto’s timeline, SQL, and trace visualization capabilities, adds an AI Assistant panel inside the UI, and uses a TypeScript backend for Agent orchestration, MCP tool calls, Skill execution, report generation, and SSE streaming output.
The repository contains these parts:
The original Chinese diagram maps the UI fork, backend, MCP tools, Skills, strategies, and scripts. Its counts describe April. v1.16.2 contains 253 non-template Skill files, 4 template files, and 22 strategy files. File counts do not measure supported scenarios or analysis accuracy.
- Perfetto UI plugin and prebuilt frontend: the
perfetto/submodule integratescom.smartperfetto.AIAssistant, and the repository also includes the prebuiltfrontend/artifacts. Normal trial use does not require rebuilding Perfetto UI. - Backend Agent runtime: scene routing, Prompt building, MCP Server, Verifier, Artifact Store, and SSE Bridge under
backend/src/agentv3/. - YAML Skill system: there were 165
*.skill.yamlfiles underbackend/skills/, covering scrolling, startup, ANR, memory, CPU, GPU, Binder, rendering pipelines, and more. - Scene strategies: 12
.strategy.mdfiles underbackend/strategies/, used to inject different analysis steps and output constraints for different questions. - Engineering scripts and documentation: Docker Hub Compose, source-build Compose,
start.sh, frontend plugin development scripts, MCP tool references, Skill guides, technical architecture docs, and rendering pipeline references.
This release opens the whole project. If a capability is not good enough yet, that is the real state of the development-stage system. There is no separate private core implementation outside the repository. The UI, backend runtime, and Skill system are already usable, while public APIs and internal protocols will continue to evolve.
Why Open Source Now
Perfetto trace analysis depends heavily on samples. Different Android versions, vendors, rendering frameworks, and business scenarios can make the same kind of jank appear in different data shapes. One person or one team cannot cover all of those branches.
During SmartPerfetto development, the same pattern appeared repeatedly: SQL can find facts, but facts do not automatically become conclusions. Many analysis mistakes look like the model is “not smart enough,” but the real cause is often that a Skill missed a branch, a table was not covered, there were too few trace samples, or a strategy assumed a specific device behavior.
Open sourcing now is about putting three things into the open and letting them be tested by real traces:
- Runnable tools: readers can load their own traces locally and verify how the AI Assistant handles real data.
- Reviewable rules: YAML Skills, scene strategies, and MCP tools are all in the repository, so the SQL and strategy behind a conclusion can be inspected, modified, and reused.
- Accumulated samples: complex performance problems need trace samples and regression tests that accumulate over time, and an open-source repository is a better place to preserve those cases.
For Android performance engineers, a trace that reproduces a problem, a more accurate Perfetto SQL query, a more reliable Skill branch, or a review that points out a wrong attribution is often more useful than a large block of feature code.
That is also the meaning of open sourcing during development: SmartPerfetto does not need to wait until every analysis path is mature before accepting outside feedback. The earlier it meets real devices, real vendor differences, and real product traces, the easier it is to add the right Skills, strategies, and regression samples.
What Problems It Targets
Perfetto’s data is powerful, but analyzing a trace is not easy. A trace that is tens or hundreds of MB can contain millions of events. Threads, slices, counters, FrameTimeline, Binder, CPU frequency, and SurfaceFlinger composition state are scattered across different tables and tracks.
The most exhausting part is usually the middle of the investigation: after seeing a frame exceed the budget, you still need to decide whether the cause is main-thread queuing, a busy RenderThread, a slow GPU, SurfaceFlinger composition blocking, or an earlier Binder, scheduling, or IO delay.
SmartPerfetto gives repeated data collection and initial judgment to the tool system, while leaving attribution that needs experience to the Agent and the engineer together.
It is suited for problems such as:
- Scrolling jank: identify janky frames, VSync budget overruns, App/SF/GPU responsibility, and main-thread or RenderThread state.
- Startup performance: split cold start, warm start, lifecycle phases, main-thread time, Binder, class loading, GC, and IO.
- ANR: locate main-thread blocking, Binder peer, lock waits, scheduling delay, and system load.
- Interaction latency: break down time from input event to frame production and then to display.
- Memory and GC: observe GC pause, memory pressure, LMK, dmabuf, and system memory state.
- Rendering pipelines: identify Standard View, Compose, Flutter, WebView, SurfaceView, TextureView, game, Vulkan, and related paths.
It does not replace performance engineers. Trace capture quality, business context, device differences, and reproduction conditions still require human judgment. SmartPerfetto is closer to an analysis assistant that can reliably run SQL, organize tables, and check missing items according to strategies.
Runtime Screenshots
At runtime, the AI Assistant can appear as a floating window inside Perfetto UI, and it can also work together with the timeline, scene markers, and analysis reports. After users load a trace, they can ask questions, inspect tool calls, expand evidence, and review conclusions in the same interface.
The four Chinese screenshots below preserve the April UI and model output: floating chat, tool timeline, structured report, and an attribution tree. The report’s “67% confidence” must not be treated as a calibrated probability of correctness, and a screenshot does not establish that the analysis passed verification.
The floating window is useful when you want to ask follow-up questions without leaving the Perfetto timeline. It keeps the current conversation, scene entries, session history, and input box together, so you can watch the trace while deciding the next analysis direction.
The conversation timeline records Agent initialization, plan submission, Skill calls, SQL queries, and data-detail fetches. You can review the intermediate actions, not just the final conclusion.
The analysis report puts startup events, data quality, phase durations, suspicious slices, and recommendations into one result, making it easier to move from a natural-language conclusion back to concrete evidence.
The old report overstates several exclusions. Low D-state time does not exclude memory pressure; near-peak frequency does not exclude thermal constraints; JIT running on big cores does not prove that it blocked the main thread. The claimed ~17 ms Release-build saving needs a matched comparison. Without that evidence, retain these as hypotheses.
Root-cause analysis tries to tie each judgment back to threads, timestamps, SQL results, and trace slices. Engineers still need to review it with business context, but they do not have to start from a blank SQL page.
Overall Architecture
The main SmartPerfetto architecture has three layers: the frontend is still Perfetto UI, the backend orchestrates the Agent and tools, and data queries are handled by Perfetto’s official trace_processor_shell.
Several boundaries in this architecture are important:
- The AI Assistant plugin delegates Agent orchestration to the backend. Perfetto UI itself can still parse and query traces through a browser WASM or HTTP RPC engine; it is not merely a display client.
- The backend
agentv3is the main runtime. It handles scene recognition, Prompt assembly, MCP tool registration, Verifier checks, and report generation. - Backend analysis queries use
trace_processor_shell. Observed metrics should come from SQL or deterministic Skill calculations; model-written numbers and attributions still require individual verification. - YAML Skills package common analysis flows into reusable units, so the Agent does not need to write complex SQL from scratch every time.
The design judgment is straightforward: large models are good at understanding questions, choosing directions, and organizing causal relationships. Databases and Skills are good at querying, aggregating, paginating, formatting, and repeating execution.
Skill: Turning Performance Experience into Executable Analysis Units
SmartPerfetto keeps much of its domain logic in YAML Skills and prefers existing queries. When no Skill covers the case, the model can still write SQL and submit it through execute_sql. The tool boundary controls the execution path; it does not establish statistical or causal correctness.
A Skill can declare input parameters, required tables, SQL, display columns, layered output, conditional branches, iterators, and parallel steps. For example, the argument object for the MCP tool invoke_skill is:
1 | {"skillId": "scrolling_analysis", "params": {"process_name": "com.example.app"}} |
The backend Skill Engine executes the corresponding SQL and composite steps, then wraps the result into a DataEnvelope that the frontend can render. This has three benefits:
The function call in the diagram is schematic; the JSON above gives the actual MCP argument structure.
- Repeatable results: deterministic queries have a reproducible comparison basis when the trace, Trace Processor version, Skill version, and parameters are held fixed.
- Renderable output: column names, data types, timestamp jumps, and duration formatting are declared in the Skill.
- Lower contribution cost: performance engineers who know Perfetto SQL can modify YAML and SQL without first understanding the whole backend codebase.
Skill file distribution in the April 29 snapshot:
| Type | Count | Location | Purpose |
|---|---|---|---|
| Atomic | 87 | backend/skills/atomic/ |
Single SQL queries, such as CPU frequency, Binder, GC, and FrameTimeline |
| Composite | 29 | backend/skills/composite/ |
Multi-step analyses, such as scrolling_analysis, startup_analysis, and anr_analysis |
| Deep | 2 | backend/skills/deep/ |
Deep analysis such as call stacks and CPU profiling |
| Pipeline | 29 | backend/skills/pipelines/ |
Rendering pipeline detection and teaching content |
| Module | 18 | backend/skills/modules/ |
Layered expert modules for app, framework, kernel, and hardware |
This Skill system is part of the SmartPerfetto runtime, and it should be separated from development-tool Skills. Claude Code Skills help developers build SmartPerfetto. SmartPerfetto YAML Skills help users analyze traces. Their names are similar, but their runtime location, inputs, outputs, and goals are different.
MCP: Letting the Agent Touch Traces Only Through Tools
SmartPerfetto exposes tools to the Agent through MCP (Model Context Protocol). Full mode exposes up to 20 tools, while Fast mode keeps only 3 lightweight tools.
Common tools fall into several categories:
- Data access:
execute_sql,invoke_skill,list_skills,lookup_sql_schema,query_perfetto_source,list_stdlib_modules,lookup_knowledge, anddetect_architecture. - Planning and hypotheses:
submit_plan,update_plan_phase,revise_plan,submit_hypothesis,resolve_hypothesis, andflag_uncertainty. - Result management:
fetch_artifact,write_analysis_note, andrecall_patterns. - Comparative analysis:
execute_sql_on,compare_skill, andget_comparison_context.
In the historical Full path with planning state enabled, execute_sql and invoke_skill require a submitted plan; informational queries are exempt. Fast mode registers only three core tools and passes no planning state, so it does not require the absent submit_plan tool. Comparison tools are registered only with a reference trace. See the MCP implementation.
Tool results are also compressed and layered. Layered Skill results can enter the Artifact Store for summaries and later detail reads; not every query has a complete pageable copy. The historical execute_sql normal response returns at most 200 rows and reports totalRows and truncated. Aggregate in SQL or explicitly query batches when complete results are needed; a truncated response length is not the total count.
From Question to Conclusion
When the user enters “analyze scrolling jank,” the backend queries the trace and sends tool results, the question, and context to the model; the raw binary trace is not placed directly in the prompt. Query results can contain process names, slice names, and business parameters, so those texts may leave the machine with a remote provider. A remote backend also receives the uploaded trace. Avoiding the entire file in the prompt does not mean entirely local processing or automatic redaction.
A scrolling jank analysis usually goes through these steps:
- The frontend sends the question, traceId, and analysis mode to the backend.
- The backend classifies the scene, such as
scrolling,startup,anr,memory,pipeline, orgeneral. - Prompt Builder injects the corresponding
.strategy.md, architecture template, output format, and required knowledge. - The Full planning path submits a plan before analysis tools; Fast mode does not use this gate.
- The preferred path is
invoke_skillfor predefined analysis. If a Skill does not cover the case, the Agent useslookup_sql_schemaandexecute_sqlto add queries. - Skill and SQL results return as DataEnvelopes, Artifacts, tables, or summaries.
- Verifier checks evidence support, hypothesis state, scene coverage, and common missing items.
- The backend pushes progress, tool results, answer tokens, conclusions, and the final report through SSE.
The final user experience includes a natural-language conclusion, tables, timestamp jumps, a report URL, and a session that can continue with follow-up questions.
How to Run It
The commands below now target v1.16.2 in a fresh directory. For an existing installation, read that version’s Quick Start and migration notes first. The repository includes prebuilt Perfetto UI, so normal trial use does not require initializing the perfetto submodule or a local C++ build environment.
1 | git clone --branch v1.16.2 https://github.com/Gracker/SmartPerfetto.git |
The April description of macOS-first development and insufficient Linux testing is historical. The v1.16.2 release provides Windows x64, macOS arm64, and Linux x64 portable packages with their runtime included. Windows trial users can use the portable package directly. Docker still requires Desktop/Engine, with the WSL2 backend on Windows; run source scripts in the project’s supported Unix environment.
The Docker Hub image does not require Node.js on the host. The commands below select tag 1.16.2; the image contains the backend, prebuilt frontend, and Trace Processor. After startup, add, test, and activate one provider in the Web Providers settings.
1 | SMARTPERFETTO_DOCKER_TAG=1.16.2 docker compose -f docker-compose.hub.yml pull |
After startup, open http://localhost:10000, load a .pftrace or .perfetto-trace file, and then open the AI Assistant panel. The backend health check is http://localhost:3000/health. Ports publish to the host loopback address by default. Uploads, logs, provider configuration, and runtime data use separate Docker volumes. Ordinary restarts and the down command below without -v do not remove those volumes; back them up separately.
To stop the containers:
1 | docker compose -f docker-compose.hub.yml down |
You only need the source-build path when testing Dockerfile changes or building local code that has not been published to the image:
1 | docker compose up --build |
The source-build path still uses the prebuilt frontend/ artifacts in the repository. It does not rebuild the perfetto/ submodule.
Local source startup requires Node.js 24 (>=24.0.0 <25.0.0); use ./start.sh. This script uses the prebuilt frontend/ artifacts in the repository and downloads a pinned trace_processor_shell when needed:
1 | cp backend/.env.example backend/.env |
You only need to initialize the Perfetto submodule and use the frontend development script when modifying the AI Assistant plugin UI, such as ai_panel.ts or styles.scss:
1 | git submodule update --init --recursive |
Both local scripts start two services:
- Frontend:
http://localhost:10000 - Backend:
http://localhost:3000
For daily backend, Skill, strategy, or normal documentation changes, prefer ./start.sh. Switch to ./scripts/start-dev.sh only when modifying the Perfetto plugin UI.
The April entry point centered on Anthropic-compatible APIs. v1.16.2 offers Claude Agent SDK, OpenAI Agents SDK, Pi Agent Core, OpenCode, and Qoder runtime paths. Choose one for initial setup and follow the Provider guide; Claude Code login does not supply SDK provider credentials. Reliable streaming and tool calls remain necessary. A successful chat does not establish SQL or Skill-analysis acceptance.
Later versions also add a standalone CLI, per-turn source and document-knowledge selection, and semantic review after answer delivery. Source and document transmission require their respective authorization. Incomplete review remains unverified: the v1.16.2 release explicitly retains strict-verification gaps in some real-model runs, so additional runtimes and a published release do not establish acceptance of every long report.
Where to Contribute
If this project becomes reliable later, the most valuable inputs will be reproducible traces, runnable SQL, Skills that explain failure causes, and regression samples that keep accumulating.
Good starting points:
- Provide small traces you are authorized to share. A trace that shows the problem is easier to turn into a test or Skill than an abstract description. Inspect and handle business data, identifiers, and parameters before attaching them to a public Issue; construct a shareable minimal reproduction when the original cannot be published.
- Improve YAML Skills: add SQL, display columns, empty-data hints, vendor differences, and edge cases.
- Improve scene strategies: make
scrolling,startup,anr, and other strategies cover more common analysis steps. - Fix the Perfetto plugin UI: the AI panel, tables, charts, jumps, and scene navigation all live in the frontend plugin.
- Add regression tests: the historical scene-reconstruction suite covers 6 canonical traces, and new failure samples can become long-term protection.
The project changes quickly during development. Before contributing, sync the main SmartPerfetto repository. If you modify the AI Assistant plugin UI, also sync the perfetto/ submodule. When you find a bug, an improvement opportunity, or have already fixed something in your fork, prefer opening an Issue or PR with the reproduction trace, expected output, and test results.
If you want to participate in Skill, Agent, or frontend development over the long term, you can use the contact information in the README to discuss collaboration. Include your GitHub account and email so it is easier to add you to core development collaboration later.
The backend commands below preserve the April contribution workflow; they are not the complete current PR gate:
1 | cd backend |
The April rules varied by PR type: code changes should at least run scene trace regression. Skill changes should run validate:skills plus regression. Strategy and template changes should run validate:strategies plus regression. Type or build issues should add npx tsc --noEmit.
In v1.16.2, root npm run verify:dev combines development checks; before opening or landing a PR, run npm run verify:pr plus applicable surface checks. See testing.md. Six scene-reconstruction traces do not establish coverage of every Skill, device, or real provider.
License and Current Boundaries
SmartPerfetto core code uses AGPL-3.0-or-later. The perfetto/ submodule is a fork of Google Perfetto and continues to use Apache-2.0. Before internal enterprise modification, external service deployment, or commercial integration, you should carefully understand the obligations of AGPL. If you need commercial licensing without AGPL obligations, use the contact information in the README.
Open sourcing the full project does not mean every analysis path is complete. Several runtime boundaries remain:
- Frame analysis benefits from Android 12+ traces containing FrameTimeline. CPU, Binder, and other analyses have their own data prerequisites; an Android version alone does not establish data availability.
- The model needs stable support for streaming and tool/function calling.
- Third-party model compatibility still needs more real testing. The emphasis on Anthropic records the April testing context; use the v1.16.2 configuration guidance above for current setup.
- When trace capture misses required fields, many conclusions can only degrade into missing-data explanations.
- Agent output still needs engineer review, especially for vendor customization, non-standard rendering paths, and complex cross-process waits.
After open sourcing, SmartPerfetto puts repeatable trace queries, scene steps, data presentation, and quality checks into the repository. Performance analysis will not become a single prompt. Complex problems still need Perfetto, SQL, trace evidence, and engineering experience.
SmartPerfetto aims to turn that experience into engineering artifacts that can be modified, reviewed, reused, and protected by regression tests.
Discussion Group
If you are trying SmartPerfetto, want to report bugs, discuss trace analysis results, submit PRs, or help build Skill, Agent, and frontend capabilities, use the contact below to request an invitation. The image retains the old entry point:
The image states that the QR code was valid before August 28; it is expired as of the October 2026 review. This does not mean the discussion group has closed.
If the group QR code is full or expired, add me on WeChat at 553000664 and include SmartPerfetto in the note. I will invite you to the group.