
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:
- SmartPerfetto main repository: https://github.com/Gracker/SmartPerfetto
- Previous update: https://www.androidperformance.com/en/2026/05/17/SmartPerfetto-Two-Week-Update/
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

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

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

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

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 | runtime result |
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

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:

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