CN

SmartPerfetto v1.0.28 Release Notes

Word count: 4.2kReading time: 26 min
2026/06/04
loading

SmartPerfetto 2026-05-17 to 2026-06-04 update cover

The previous SmartPerfetto update was published on May 17. At that point the project had already moved from “an AI Assistant inside Perfetto UI” to “a reusable trace analysis platform.” By June 4, the new work is concentrated in five areas: Smart Mode, selected-range quick analysis, CLI capture, stronger evidence rules for Power / ANR / Input / IO / Network, and four Agent runtimes.

This article is based on the SmartPerfetto main branch on June 4, 2026. The latest public release at this point is v1.0.28. The goal is simple: list what changed after May 17, explain how runtimes and evidence sources are handled, and show what information makes a useful bug report.

Project links:

Historical version note (reviewed October 14, 2026): This article retains its June 4 perspective. The code baseline is v1.0.28 / e275f2b, released June 2; the later 3c6d2ed commit only adds release-verification documentation. “Now” below refers to that historical version. The latest release at review time is v1.16.2. Runtime, authentication, and per-claim verification have evolved, so do not reuse the old configuration unchanged.

2026-05-17 to 2026-06-04 Overview

The feature map in the previous article still showed SmartPerfetto v1.0.7. The public release is now v1.0.28. At this commit, the repository has 230 *.skill.yaml files. After excluding _template, 226 of them are functional Skill files. backend/strategies/ has 20 .strategy.md files and 35 .template.md files.

These are v1.0.28 file counts, not independent scenarios or passing tests. In particular, smart.strategy.md is a contract_only report contract excluded from ordinary scene classification. May 17 to June 4 spans 18 days; “three weeks” is the series cadence.

The count changed, but the useful change is not the count itself. Users will notice the changes in six areas:

Area May 17 state Current state
Analysis entry Ask questions inside Perfetto UI with fast / full / auto modes Smart Mode starts with scene inventory, selected-range quick analysis focuses on the selected scope, and CLI uses the shared analysis core
CLI and capture CLI / API were already documented and shipped smp capture, smp analyze, compare workflows, CLI turn files, and npm package checks are now part of release verification
Scene coverage startup, scrolling, ANR, interaction, touch, memory, power, network, and related strategies already existed smart.strategy.md and io.strategy.md were added, and Power / ANR / Input / Display / IO / Network / Observability now have stricter evidence requirements
Evidence reliability SQL guardrails, evidence IDs, and sentence-level citations were already in place Failed SQL no longer becomes frontend evidence; final report checks, claim verification, and scene-specific evidence rules cover more scenes
Model integration Claude Agent SDK and OpenAI Agents SDK were first-class runtimes claude-agent-sdk, openai-agents-sdk, pi-agent-core, and opencode now share one output format
Release verification Docker, portable packages, source, and CLI were in release docs The June 2 record reports 8 strict E2E runs across four runtimes and two scenes, 6 canonical trace regressions, and npm / portable / Docker release checks

The main direction is clear: more scenes now have verifiable analysis flows. The model still explains and prioritizes. The numbers still come from trace_processor_shell, SQL, Skill tables, and structured evidence in reports.

Deterministic queries provide source values; they do not automatically make the model’s restatement, attribution, or advice correct. Check the cited rows, units, and identities.

Current Feature Map

SmartPerfetto v1.0.28 feature map

Historical diagram: the counts and four runtimes describe v1.0.28. The English tables below explain the same surfaces and their limits.

SmartPerfetto now has five practical layers: entry, analysis, evidence, runtime, and distribution.

Surface Current behavior Good fit
Perfetto UI / Smart Mode Load .pftrace / .perfetto-trace, ask questions directly, or let Smart Mode identify startup, scrolling, click, navigation, ANR, and device-state ranges first Mixed traces where you want to find the useful ranges before spending full-analysis tokens
Selected-range quick analysis Perfetto area selection / track event selection carries selectionContext; the backend runs quick analysis in that bounded scope Understanding a short time window, one frame, or what happened around a suspicious slice
CLI / Capture smp / smartperfetto reuse backend runtimes, MCP tools, Skills, reports, and session snapshots Terminal analysis, scripts, CI, and remote environments
Skills + Strategies 226 non-template Skill files, 20 strategy files (including contract-only), and 35 templates covering startup, scrolling, ANR, interaction, memory, power, network, pipeline, IO, Smart Mode, and more Routing natural-language questions to deterministic SQL, Skills, and report requirements
Reports + Evidence Supports HTML reports, result snapshots, claim refs, and data-source narration; CLI also has turn files. Artifacts depend on the entry and completion state Mapping “what the AI said” back to SQL, Skills, rows, and evidence IDs
Agent Runtimes Claude, OpenAI, Pi Agent Core, and OpenCode are selected explicitly through Provider Manager or env config Running one trace-analysis output format through different SDK or server orchestration modes
Runtime Guardrails Provider Manager, request-scoped MCP tools, session snapshots, and /health diagnostics constrain runtime behavior Debugging cases where connection testing passes but the actual analysis runtime is not the one expected
Distribution Docker Hub, Windows / macOS / Linux portable packages, source ./start.sh, and npm CLI all have verification Trial use, developer work, team deployment, and script integration

One rule matters before everything else: SmartPerfetto does not push the whole trace into the prompt. The model sees SQL results returned by backend tools, Skill output, scene context, report summaries, and structured evidence. New runtimes do not bypass that rule.

Those results can still contain process names, application markers, or network information and be sent to the configured provider. Not sending the whole trace does not mean all data stays local. Source excerpts in code-aware analysis have separate explicit authorization, described below.

Feature One: Smart Mode, Selected-Range Quick Analysis, and CLI Share One Core

Smart Mode and CLI share the analysis core

This diagram summarizes entry points, not a mandatory sequence. Selected-range questions need no prior Smart preview; capture requires a later analyze command or explicit --analyze. “Bounded scope” describes the main conclusion scope, with necessary global context still allowed.

The previous article already covered fast / full / auto analysis modes. After May 17, SmartPerfetto added two more practical entries: Smart scene selection and range-scoped quick analysis.

Smart Mode starts with scene inventory: detected scenes have ranges, eligibility, confidence, and related context; the preview report also carries reconstruction verification and a report ID. Users can select all eligible scenes, scene types, or scene IDs for deeper analysis. Detection can miss or misclassify events. Eligibility controls routing, confidence is not calibrated accuracy, and a preview is not completed root-cause analysis.

Selected-range quick analysis solves a smaller but common problem. In Perfetto UI, users often select a time range or one track event and ask “why is this range slow?” or “what happened around this slice?” The backend now passes that selected context into the request. The quick path gathers evidence around that range instead of treating the whole trace as the analysis target.

This is an analysis constraint, not storage or tool-access isolation. The selection template explicitly allows global context such as VSync timing. Separate in-range contribution from outside context rather than charging an entire overlapping slice to the window.

The CLI entry also became a real terminal product instead of a thin backend wrapper. smp capture handles capture, smp analyze handles analysis, and compare workflows, session files, report output, and Provider/runtime selection reuse the Web logic. CLI does not start the Web UI, and it still uses the shared analysis core.

In v1.0.28, the implemented target is smp capture android, requiring an authorized ADB device; use --serial with multiple devices. API 29+ defaults to device Perfetto; older devices or --sideload need an available tracebox. There was no smp capture linux target. --kill-stale kills device tracing processes/services by name without proving they are orphaned, so it is not a default retry step. Capture success does not establish data-source completeness: check import, data loss, and required signals. See the CLI documentation.

Scenario Before Now
Mixed-trace triage Inspect the timeline manually and ask about one scene Smart Mode lists scenes first, then the user chooses what to deep-dive
A selected jank range Copy timestamps or type a range manually Selection context enters the backend; quick analysis focuses on the selection and distinguishes global context
Remote-machine capture Capture with external tools, then move the trace into the UI smp capture android records an ADB-connected device; smp analyze uses the shared analysis flow
Regression comparison Pick a reference trace or Result ID in the UI CLI compare workflows and analysis-result snapshots can be scripted

This is the reason the four-runtime work can fit into the product. The entry may be UI, CLI, or API, but the implementation returns to AgentAnalyzeSessionService, Skills, MCP tools, and report checks.

A shared core does not make every entry feature-identical. The Smart SceneReport preview ID, AnalysisResultSnapshot ID, and final HTML report ID identify different objects. Deep analysis enters the common Agent path, but preview success does not prove that every artifact exists or can be restored. Raw two-trace comparison also differs from result-snapshot comparison; check metric definitions, identities, and windows.

Feature Two: Evidence Rules Now Cover More Scenes

Scene evidence rules

Earlier SmartPerfetto work was heavily focused on startup and scrolling. The late-May work expands the rule set for what a report must prove in more scenes.

Scene Added or strengthened evidence What users get
Power battery drain, power rails, wakelock, CPU freq / idle, JobScheduler, modem / network related Skills A report can connect background power, rail energy, wakeups, and scheduler events instead of only listing CPU hotspots
ANR anr_context_in_range, main thread states / slices, futex wait, logcat, and ANR detail requirements The report can separate running, waiting, futex, Binder, and logcat signals instead of turning any stall into an ANR root cause
Input / Interaction input events, scroll response latency, click response analysis / detail Input-to-response latency has its own evidence path, so not every jank is pushed into RenderThread by default
Display / Pipeline fence wait decomposition and display evidence rules in pipeline strategy Producer, SurfaceFlinger, HWC, fence, and report conclusions are tied to explicit evidence
IO / Network io.strategy.md and network request-stage evidence templates IO wait, network request phases, and scene conclusions have concrete entry points
Observability diagnostics evidence templates, missing-signal policy, trace completeness probing Missing tables or categories are reported as missing signals instead of becoming confident conclusions

This is bigger than adding a few SQL queries. Before, report quality relied mostly on prompts asking the model to cite evidence. Now strategy frontmatter, Skill evidence rules, final report checks, and claim verification work together. When key numbers, threads, processes, frame counts, or percentages appear in a report, they need to point back to their evidence source.

These are mechanisms and output requirements. The v1.0.28 finalReportContractGate mainly matches keywords/regular expressions for required sections; it does not establish their correctness. Claim verification supports only the assertions actually covered. SQL success, citation availability, section completeness, and semantic verification are separate checks.

That is also why failed SQL diagnostics cannot become frontend evidence. Failed SQL is useful for maintainers. It is not a trace fact for the user. Successful query data, diagnostics, visible report text, and snapshot provenance are handled separately. The SQL definition still needs review.

Feature Three: Four Runtimes Share One Product Output

Four runtimes share one product output

The previous article covered Claude Agent SDK and OpenAI Agents SDK. In v1.0.28, SmartPerfetto has four public runtimes:

Runtime Provider fit Boundary
claude-agent-sdk Anthropic, Bedrock, Vertex, DeepSeek, Anthropic-compatible gateways, local Claude Code config Default path; keeps in-process MCP server, verifier, sub-agent, and SDK resume behavior
openai-agents-sdk OpenAI, Ollama, OpenAI-compatible gateways Reuses the shared SmartPerfetto MCP tool registry through function tools
pi-agent-core custom provider Optional public runtime; reuses SmartPerfetto prompt, tools, and report flow; does not enable .pi discovery, package extensions, shell tools, or file tools
opencode custom provider or explicit OpenAI-compatible config Uses a request-scoped SmartPerfetto MCP bridge; does not read the user’s own OpenCode login state or project state, and does not enable built-in file / shell / web / edit tools

Provider Manager and env config do not guess the runtime from whichever key exists. The priority is request/session providerId, active Provider Manager profile, SMARTPERFETTO_AGENT_RUNTIME, then the default claude-agent-sdk. Once an analysis session is created, it pins the credential source used at that moment. Restoring an old session does not silently switch to a new active provider.

This summarizes ordinary new sessions. Restored sessions use the bound profile or runtime snapshot; explicit providerId: null pins env/default selection and bypasses the active profile. A deleted bound profile fails. Changes within the same profile can invalidate SDK restoration and start a fresh SDK session. Pinning the source does not permanently freeze model, credentials, or all context.

The internal mechanisms differ. Claude runtime exposes an in-process MCP server. OpenAI runtime adapts the shared tool descriptors into function tools. Pi Agent Core uses request-scoped native tools. OpenCode calls SmartPerfetto tools through an isolated server and a request-scoped MCP bridge.

The shared artifacts can be summarized as follows. This is a responsibility sketch, not a strict call order or a guarantee that every run creates every artifact:

1
2
3
4
5
6
runtime result
-> agentResultNormalizer
-> finalReportContractGate
-> evidence rules / claim verification / identity resolutions
-> HTML report / CLI turn files / analysis-result snapshot
-> frontend visible projection

The June 2 verification record reports passing strict E2E for four runtimes × startup / scrolling: eight runs, each recording 12 checked claims, 0 unsupported / issues, and a non-partial final report. Twelve is the result of those runs, not a universal claim-count threshold. The record also lists six canonical trace regressions, frontend/CLI pack checks, and post-release npm fresh-install, three-platform packaging, GitHub Release, and Docker manifest checks. This article review inspected the historical record and release metadata without rerunning those E2Es. Those samples do not establish coverage of every model, device, scene, or current release.

This does not mean every runtime prints identical wording. Different SDKs have different tool-call timing, streaming events, context recovery, cost, and timeout behavior. SmartPerfetto constrains the shared surfaces: SSE events, HTML reports, CLI turn files, analysis-result snapshots, claim verification, and session resume semantics.

Feature Four: Reports and Debugging Data Are Easier to Inspect

Some changes are less visible than runtime support, but they matter more in daily use.

The first group is report completeness. Changes such as ensure complete agent final reports, final report presentation hardening, evidence table readability, and analysis quality rules all address one problem: running many tools does not guarantee a complete user-facing report. A report now needs to satisfy the final report rules defined by the scene, and its claims need to pass claim verification. The frontend may clean up visible text. Provenance needed by reports, CLI, or snapshots must stay intact.

The second group is SQL and diagnostics. Raw SQL artifacts, failed SQL diagnostics, and trace processor startup failures are handled more explicitly. Failed SQL diagnostics can go into logs and debugging material, but they should not be mixed into the evidence table for the current trace. If trace_processor_shell fails to start, a prebuilt binary is missing, or trace loading fails, the error should show up in health checks or error output, not as a vague AI-quality problem.

The third group is codebase-aware analysis. SmartPerfetto can include local codebase context in an analysis task. This helps map trace evidence to code. It does not replace trace evidence. Code locations can explain possible fixes; performance judgment still comes from trace data.

The historical Code-Aware documentation requires session opt-in: registration alone does not expose a codebase to every session. metadata_only gives the model CodeRef metadata. Sending filtered excerpts requires sendToProvider permission at registration and provider_send for the analysis. A code reference does not prove a proposed fix works.

Later developments (through October 14, 2026): v1.11.0 added per-claim delivery status backed by retained execution evidence and a bounded whole-answer review. v1.16.2 repaired location declarations, ambiguous identities, and report recovery, and improved private-document retrieval. Its release notes still mark full strict claim verification incomplete in real-model startup / scrolling / Binder runs where references, units, or coverage are insufficient. A delivered report and fully verified claims remain separate outcomes.

This makes bug reports more useful. Instead of only saying “the AI conclusion is wrong,” users can attach a Result ID, HTML report, evidenceRefId, claim ref, related SQL, Skill table, and /health runtime data.

Usability Fixes

Recent fixes also focus on whether a real user can run the first trace and diagnose a failure.

Fix area User-visible effect
trace processor prebuilts Source and npm CLI paths more reliably get the pinned trace_processor_shell; startup failure messages are clearer
Provider debug status /health shows actual runtime, credential source, provider mode, and diagnostics
Node 24 hardening Source and CLI require Node.js >=24 <25, reducing build/runtime drift
npm CLI bin smp / smartperfetto are valid package bins; fresh installs can run version and doctor smoke checks
service port config Ports are configurable; TCP LISTEN matching excludes client sockets but does not prove the listener belongs to this project
Docker healthcheck Docker healthcheck syntax is fixed, so release checks can cover runtime image smoke
frontend evidence table Evidence tables in AI Assistant are easier to read in chat and reports
final SSE conclusion SSE conclusion, analysis_completed, and HTML report final state are more stable
raw SQL artifact Raw SQL, final executable SQL, failed diagnostics, and user-visible evidence are separated
release verification npm, portable assets, GitHub Release, Docker latest, and Docker version tags are verified after publishing

The port fix is not a full ownership check. v1.0.28 start.sh still terminates configured-port listeners and runs pkill -f "trace_processor_shell.*--httpd", which can match other sessions. Do not treat this as harmless cleanup on a host with shared tracing services. Likewise, /health and doctor diagnose configuration/dependencies; they do not replace a real analysis run.

These fixes are not flashy. They decide whether Android performance teams can use the tool on real traces. SmartPerfetto crosses Perfetto UI, Express backend, SSE, trace processor, Provider protocol, model SDK, CLI, Docker, and portable packages. State drift in any of these surfaces usually shows up to the user as “the AI analysis is unreliable.”

How to Choose a Run Path

For most users, Docker or the portable package is still the first choice. Developers and script users can choose source or CLI.

Run mode Good fit Notes
Docker Hub Fast trial or deployment Does not use host Claude Code login state; needs Provider Manager or .env provider config
Portable package Users who do not want Node.js or Docker This release has Windows x64, macOS arm64, and Linux x64 assets bundling Node.js 24, backend, prebuilt frontend, and pinned trace processor
Local source ./start.sh Developers changing backend / Skills / strategies Uses committed prebuilt frontend; normal backend and Skill work does not require rebuilding Perfetto UI
Dev mode ./scripts/start-dev.sh People changing the AI Assistant plugin UI Requires the perfetto/ submodule and frontend watch build
npm CLI smp Terminal capture, analysis, CI, and scripts Does not start Web UI; reuses shared runtime selection, MCP tools, Skills, reports, and session snapshots

For runtime config, pick one mode first:

The table preserves v1.0.28 configuration. Later change: v1.11.0 removed implicit local Claude Code login fallback. Configure a provider or explicit authentication environment instead; see the v1.11.0 migration note. Later versions are also no longer limited to these four runtimes.

What you have Recommended choice
Local source, and claude already works in the same terminal Default claude-agent-sdk; no OpenAI key needed
OpenAI, Ollama, or OpenAI-compatible gateway openai-agents-sdk
Pi Agent Core model config custom provider + pi-agent-core
OpenCode model config custom provider + opencode
Docker / portable, and you do not want env files Create and activate a provider profile in UI Provider Manager

Do not put provider names into SMARTPERFETTO_AGENT_RUNTIME. In v1.0.28, that variable only accepts claude-agent-sdk, openai-agents-sdk, pi-agent-core, and opencode. Providers such as DeepSeek, Qwen, Kimi, MiMo, and TokenHub should be configured through Provider Manager or the matching protocol env block.

How to File a Useful Bug Report

SmartPerfetto bug report checklist

The image is the historical checklist, not a complete current runtime list. Before public submission, remove keys, tokens, private URL parameters, personal data, and restricted source. Check logs, traces, reports, and turn files individually for shareability; the English table below describes the fields.

SmartPerfetto bug reports still belong in GitHub Issues. Security reports should not be filed as public issues; use GitHub private advisory or the security contact instead.

After v1.0.28, a useful report should include:

Category What to include
SmartPerfetto version version, commit, Docker image tag, portable filename, or npm CLI version
Run mode Docker, portable, source ./start.sh, dev mode, npm CLI, or API
Runtime / Provider claude-agent-sdk, openai-agents-sdk, pi-agent-core, or opencode; provider name, model ID, Base URL, protocol type
Trace information device, Android version, scenario, trace categories, FrameTimeline availability, trace size
Analysis scope full trace, selected range, Smart scene, CLI capture, and whether the issue happened during follow-up turns or mode switching
Evidence pointer Result ID, HTML report, evidenceRefId, claim ref, Q/C row, related SQL, or Skill table
Failure surface chat text, SQL, Skill table, report, provider connection, runtime selection, session resume, or CLI output
Artifacts backend logs, CLI turn files, /health aiEngine snippet, screenshot, HTML report
Expected vs actual smallest repro steps, actual output, expected output, and the manual evidence behind the expectation

Provider issues should separate “the model can chat” from “the model can run stable tool / function calls.” SmartPerfetto depends on streaming output, structured tool arguments, context recovery, and long report generation. Normal chat success does not prove full trace analysis works.

Trace issues also need capture conditions. Android 12+ FrameTimeline adds frame-level display evidence, but is not a universal prerequisite for startup, CPU, or IO questions. Power, ANR, network, and IO require different data sources, subject to device and OS support. When the data source is missing, the correct behavior is to report missing signals, not to invent a confident conclusion.

Feedback That Helps Most Right Now

SmartPerfetto needs feedback that can become a code fix, a Skill branch, or a regression test.

Useful samples look like this:

  • A power trace where the report blames CPU, but manual inspection points to wakelock or modem activity. Attach power rails, wakelock, CPU freq / idle evidence.
  • An ANR trace where the report says the main thread is blocked by futex, but logcat or thread state does not support it. Attach the ANR range, main-thread state table, futex wait table, and logcat snippet.
  • An OpenAI-compatible provider passes connection testing but mutates tool arguments during full analysis. Attach runtime, provider, model ID, protocol type, session log, and /health.
  • An OpenCode or Pi Agent Core config passes smoke but startup / scrolling E2E quality is unstable. Attach model config, command, Result ID, and HTML report.
  • Smart scene detection picks the wrong range. Attach the trace range, scene inventory output, expected scene type, and manual evidence.
  • CLI capture or analyze fails on a remote machine. Attach Node version, platform, smp doctor --format json, CLI turn files, and trace processor error.

A screenshot plus “the result is wrong” is hard to act on. The maintainer needs to know whether the problem is trace capture, SQL, Skill logic, scene strategy, Provider protocol, runtime session, frontend display, or report rules.

Closing

Between May 17 and June 4, SmartPerfetto moved from answering trace questions inside Perfetto UI toward delivering trace-analysis results through multiple entries, multiple runtimes, and shared evidence rules.

It is still moving quickly. Provider presets, runtime config, public APIs, report rules, and the Skill system will continue to change. For ordinary users, the best next step is to run Docker or a portable package on a real trace. For contributors, the most useful inputs are reproducible traces, wrong-attribution reports with evidence pointers, SQL that can improve a Skill or strategy, and regression samples.

From the June 4 perspective, the May 17 article no longer covered these additions: Smart Mode, selected-range quick analysis, CLI, and four runtimes. For installation or upgrades now, consult the current version’s documentation rather than treating this article as the latest configuration guide.


SmartPerfetto Discussion Group

The historical group QR code below states an August 28 expiration date. It is expired at review time and is not a current join link:

SmartPerfetto discussion group

See the About page for current contact details; group availability depends on the actual reply.

CATALOG
  1. 1. 2026-05-17 to 2026-06-04 Overview
  2. 2. Current Feature Map
  3. 3. Feature One: Smart Mode, Selected-Range Quick Analysis, and CLI Share One Core
  4. 4. Feature Two: Evidence Rules Now Cover More Scenes
  5. 5. Feature Three: Four Runtimes Share One Product Output
  6. 6. Feature Four: Reports and Debugging Data Are Easier to Inspect
  7. 7. Usability Fixes
  8. 8. How to Choose a Run Path
  9. 9. How to File a Useful Bug Report
  10. 10. Feedback That Helps Most Right Now
  11. 11. Closing
  12. 12. SmartPerfetto Discussion Group