ContextQMD
Back to Perfetto

Using AI with Perfetto

docs/getting-started/using-ai.md

57.13.4 KB
Original Source

Using AI with Perfetto

This page is the starting point for using AI tooling with Perfetto. Today that means installing Perfetto's agentskills.io skills into your coding agent so it can load, query, and reason about traces; over time it will grow to cover other AI-assisted workflows (for example in the Perfetto UI).

The skills teach an agent how to invoke trace_processor, write PerfettoSQL, and follow guided analysis workflows. Each install also bundles a trace_processor wrapper, so the agent has a working binary with no extra setup.

The design behind this work is described in RFC-0025 and RFC-0026.

Install into your coding agent

Pick the row for your agent and run the command:

AgentInstall
Claude Code/plugin marketplace add google/perfetto@ai-agents
Codexcodex plugin marketplace add google/perfetto --ref ai-agents
OpenCodeAdd to opencode.json: "skills": { "urls": ["https://raw.githubusercontent.com/google/perfetto/ai-agents/plugins/perfetto/skills"] }
AntigravityUse the fallback installer (below)
Other (Cursor, Continue, ...)Use the fallback installer (below)

Fallback installer

For any agent without a native plugin command, use the fallback installer. It works on any platform with Python 3:

bash
# macOS / Linux
curl -fsSL https://get.perfetto.dev/agents-install | python3 - --target <path>
powershell
# Windows (use curl.exe, not the PowerShell curl alias)
curl.exe -fsSL https://get.perfetto.dev/agents-install | python - --target <path>

Pass --agent <claude|codex|opencode|antigravity|pi> instead of --target to install into that agent's default directory. The installer also bundles trace_processor, so there is no separate binary to install.

Share the setup with your team

To give everyone on a project the same baseline, check the install into a shared repository directory. Most agents look for a per-agent directory in the repo root (for example .claude/skills/ for Claude Code or .opencode/skills/ for OpenCode); point the fallback installer's --target at that directory and commit the result:

bash
curl -fsSL https://get.perfetto.dev/agents-install | python3 - --target .claude/skills

Once committed, the setup travels with the repo and needs no per-developer install step.

What gets installed

A single perfetto skill. Its SKILL.md is a router that the agent loads when you ask about a trace, then dispatches to the right on-demand reference or workflow file. It covers:

  • Setup — how to invoke trace_processor in your environment (the bundled binary in a plugin install, or fetching it plus the perfetto Python client in a standalone install).
  • Querying — load a trace, run a PerfettoSQL query, and discover the available tables, views, columns, and stdlib modules.
  • Android memory workflows — guided investigations of an Android Java heap graph (heap dump): finding leaks and what retains memory, clustering multiple dumps for a process to spot common leaks, and proposing caching to cut memory.

Contributing

To author a new skill or modify an existing one, see ai/skills/README.md in the Perfetto repository.