SmartPerfetto: putting an AI assistant in front of Android Perfetto traces

The assistant sits on top of Perfetto rather than replacing it

SmartPerfetto is described as AI-powered Android performance analysis built on Perfetto, and the first thing it says it does is add an AI analysis layer to Perfetto traces. The workflow it describes is: load a trace, ask a natural-language question, and get an answer backed by evidence, with SQL results, Skill outputs, root-cause reasoning and optimization suggestions.

The critical design decision is that it keeps Perfetto's timeline and SQL workflow and then adds the assistant. So the underlying instrument is the one Android engineers already trust, with its own trace processor and its own SQL interface, and the AI layer sits above it rather than replacing the query step. The README also carries a badge for a Perfetto UI fork, and the repository contains a perfetto directory alongside backend/, frontend/ and Trace/.

The scope of investigation is stated concretely: scrolling jank, startup, ANR, interaction latency, memory, game and rendering-pipeline issues. There is a specific claim about the scrolling case, namely that it investigates continuous main-thread work during scrolling and window animations, including tasks between doFrame callbacks, their execution and wait time and source clues. The note that FrameTimeline provides outcome evidence and missing frames do not hide tasks is the kind of detail that separates a tool built from real investigations from a wrapper around a chat model.

The project is TypeScript, with a Node.js 24 LTS badge and a TypeScript strict badge pointing at the backend tsconfig. The last push was on 2026-10-16, and the release history is dense: v1.16.2 on 2026-10-14, v1.16.1 on 2026-10-12 and v1.16.0 the same day, with the package version at 1.16.2.

Skills and strategies are what keep interpretation out of the evidence

The mechanism that makes the answers checkable is described as deterministic YAML Skills and Markdown strategies, used so that factual evidence, model interpretation and report provenance remain separate.

That separation is the whole argument for the project. A trace analysis tool that mixes what was measured with what the model concluded produces answers that are pleasant to read and impossible to audit. Here the SQL results and Skill outputs are the evidence, the model contributes the interpretation and the root-cause reasoning, and the report records where each claim came from.

The Skills are also where the domain knowledge lives. A Skill is an entry point that a scene-wide investigation starts from when its trace and process prerequisites are satisfied, and when the evidence is missing the tool says so explicitly rather than proceeding with a plausible narrative. There is a separate system for relating critical tasks to CPU frequency, system load, thread states, CPU placement and scheduling evidence when the question needs them.

The analysis surface is broader than the Web UI. The README describes an AI-assisted Web UI, a CLI, reports, sessions, comparisons and an evidence workflow, and the ecosystem table places SmartPerfetto at the Analyze stage of a seven-project path that runs from instrumentation through capture, agent analysis, learning, system knowledge and reproduction.

The project also describes its own maturity honestly. It says the Web UI, CLI, backend runtime and Skill system are usable today, while public APIs and internal contracts may still evolve. The AI assistant adds follow-up questions and comparisons, and at the turn limit it delivers a conclusion from the evidence collected with the remaining gaps named, and follow-ups inherit authorized history in the same session, including after reopening the page or restarting the backend.

Private knowledge bases are background, never a substitute for the trace

The most interesting capability is the one that handles the fact that private traces use tag names that no public documentation explains.

The idea is to bring your own device or team knowledge. You add documents describing private trace tags, trace passages and version differences, from the AI Assistant context control, and index them so you can select them per turn. The model can look up definitions and cite files and lines, and below each answer you can see retrieved passages and answer citations separately. The stated purpose is to reduce guesses about private names, while SQL and Skills establish current-trace facts.

The constraint the README attaches to this is important and worth repeating: a knowledge base is background, never a substitute for current-trace evidence. The same care is taken with local source code. You can select registered local source per run, with bounded on-demand lookup that does not require an index, and source occurrence in the trace is kept separate from CodeRef mechanism evidence in the Web, report, CLI, snapshot and API provenance.

Both features have a cost the project states plainly. Matching text is sent to the AI service you authorize, relevant source snippets are sent to the configured service, and source lookup adds analysis time. Results and quoted source can be retained in local history and exports, but retention on the AI service side depends on that service's policy. That is a real consideration for anyone handling proprietary application source or unreleased device internals.

The repository carries the corresponding guides, a private knowledge guide and an Android internals knowledge guide, and the public Android Internals Wiki can be registered the same way as a team document base.

Two processes, two ports, and a healthcheck that probes both

The deployment shape is visible in the Docker Compose file, and it is a single-service web application with two processes with a specific port convention.

The service is called smartperfetto, it builds from the local context with the repository Dockerfile, and it publishes two ports. The first is the backend API, bound to a publish host that defaults to 127.0.0.1 and to the backend port with a default of 3000. The second is the Perfetto UI, on the frontend port with a default of 10000.

      - "${SMARTPERFETTO_PUBLISH_HOST:-127.0.0.1}:${SMARTPERFETTO_BACKEND_PORT:-3000}:${SMARTPERFETTO_BACKEND_PORT:-3000}"      # Backend API
      - "${SMARTPERFETTO_PUBLISH_HOST:-127.0.0.1}:${SMARTPERFETTO_FRONTEND_PORT:-10000}:${SMARTPERFETTO_FRONTEND_PORT:-10000}"  # Perfetto UI

The defaults are what make this safe to run locally. Binding the publish host to loopback means the analysis UI is not exposed to the network by accident, while the container itself binds to 0.0.0.0 so the port mapping works. A team deploying this for a group would set the publish host deliberately, and the environment file is where that decision belongs.

The environment example confirms the port convention for source runs as well, with the backend port preferred and a PORT variable kept for Node, Docker and PaaS compatibility as a fallback. The compose file also persists four named volumes, for uploads, logs, provider data and runtime data, so UI-created provider profiles and uploaded traces survive a restart, and the container is set to restart unless-stopped.

The healthcheck is worth noting because it probes both processes rather than one:

      test: ["CMD-SHELL", "curl -fsS \"http://127.0.0.1:$${SMARTPERFETTO_BACKEND_PORT:-$${PORT:-3000}}/health\" >/dev/null && curl -fsS \"http://127.0.0.1:$${SMARTPERFETTO_FRONTEND_PORT:-10000}/health\" >/dev/null"]

If the frontend process is serving the Perfetto UI but the backend is down, the service is reported unhealthy, which is the behaviour you want from an orchestrator that has to decide whether to route traffic.

The build pins a Rust analyzer and a baseline x86 binary for a reason

The Dockerfile is a multi-stage build, and two of its stages are worth reading closely because they explain what the tool needs at runtime.

The first stage builds the backend from node:24-bookworm, installing dependencies with npm ci and copying in two pin files, one for the trace processor and one for the Perfetto recording tools, along with a docs directory for rendering pipelines. It then copies in three prebuilt data files, a light SQL index, the full SQL documentation and the standard library symbols, which are the data the SQL assistant queries against.

The second stage builds a Rust flamegraph analyzer from rust:1-bookworm, copying the Cargo manifest and the source directory. The repository therefore contains a rust/ directory, and a flamegraph analyzer compiled from Rust is a separate binary in the final image rather than a Node dependency.

The comment about pinning the runtime OpenCode executable is the most revealing line in the build. The upstream postinstall selects an AVX2 binary based on the build machine's /proc/cpuinfo, and copying that selection into an amd64 image would make the image fail on baseline x86_64 hosts. So the build branches on uname -m and picks either the baseline x64 binary or the arm64 one, then verifies the destination is a non-empty file and runs it with --version as a smoke test. A container image that only works on a machine with AVX2 is a portability bug, and this build handles it explicitly.

The final size is managed by pruning dev dependencies before the runtime stage, which is the standard trick and the reason the image ships one production dependency set rather than the whole development tree.

One provider block, and the choice is in the environment file

The environment example is unusually instructive about how to configure the AI side, and its first rule is a beginner rule: uncomment exactly one provider block.

The file states that the Claude Agent SDK, the OpenAI Agents SDK, the Pi Agent Core and OpenCode are alternatives, and that you should not configure multiple runtimes for a first setup. The remaining steps are spelled out: replace only the placeholders such as your_*_api_key_here, sk-your-*, model IDs or Base URLs, and when your provider console says they differ, restart the backend or container after editing, and be aware that if a UI Provider Manager profile is active it overrides the environment file, so you choose System Default in the provider switcher to use the file again.

That last point is the kind of precedence rule that causes confusion when it is undocumented, and here it is documented in the file itself. There is also a warning specific to the Claude Agent SDK, that it needs explicit provider credentials in the UI Provider Manager or an env block in every run mode, and that a Claude Code login and a Base URL alone do not configure that SDK.

The scripts in the root package.json show the rest of the engineering discipline. Linting is done with biome over a specific set of configuration files, there is a format check separate from the lint, a deadcode script using knip with a maximum of 50 reported issues, shellcheck over start.sh and the shell scripts, and a governance test script that chains a set of checks, including one for orphaned modules, one for unused exports and one that verifies test registration, plus a check for the Perfetto Skills impact.

The Docker Compose file, the Dockerfile and the scripts all point at a project that is being run as a product rather than as a demo, even though the licence question below remains open.

Editorial conclusion

SmartPerfetto is worth evaluating for a team that already works with Perfetto traces and wants the SQL power of the tool combined with a faster path from symptom to suspect, because the Skill and evidence separation means the model cannot quietly substitute a plausible story for a measurement. It is the wrong tool if you have never used Perfetto, since it does not replace learning the trace format, and it is the wrong tool if you cannot accept sending trace-derived text to an external model, because the knowledge base and source lookup features deliberately send matching text to whichever AI service you authorize. Before you deploy it, verify three things yourself: that the Node.js 24 requirement and the Docker Compose layout match your build environment, that you configure exactly one AI provider block in the environment file rather than several, since the file says explicitly not to configure multiple runtimes for a first setup, and that you read the LICENSE file rather than trusting the badge, because the badge says AGPL-3.0-or-later while the repository licence field is recorded as a custom one that GitHub cannot classify.

Frequently asked questions

Official sources

1. Gracker/SmartPerfetto on GitHub
2. Issues
3. README
4. Releases