AI-Powered Usage¶

perfetto-cli integrates with AI coding assistants like Claude Code, Cursor, Codex, and Gemini CLI through a skills system. This enables AI tools to understand perfetto-cli's capabilities and guide you through trace analysis interactively.

How It Works¶

The skills system installs knowledge files into your AI tool's configuration directory. When you ask the AI about trace analysis, it automatically knows how to use perfetto-cli — which commands to run, how to interpret results, and what to do next.

Supported AI tools:

Tool	Config Directory
Claude Code	`~/.claude/skills/`
Cursor	`~/.cursor/skills/`
Codex	`~/.codex/skills/`
Gemini CLI	`~/.gemini/skills/`
OpenCode	`~/.opencode/skills/`

Installing Skills¶

Interactive Mode¶

perfetto-cli skills install

This launches an interactive wizard that: 1. Shows available skills 2. Detects which AI tools are installed on your system 3. Lets you choose install scope (global or project-level) 4. Installs skills to selected tools

Install All Skills¶

# Install all skills to all detected tools (global scope)
perfetto-cli skills install --all --target all --scope global

Install to Specific Tool¶

# Install to Claude Code only
perfetto-cli skills install perfetto-cli-usage --target claude --scope global

# Install to Cursor only
perfetto-cli skills install perfetto-cli-usage --target cursor --scope global

Project-Level Install¶

# Install to current project only (creates .claude/skills/ in project root)
perfetto-cli skills install --all --scope project

Project-level skills take precedence over global skills and are useful when you want project-specific AI guidance.

Checking Installation Status¶

perfetto-cli skills list

Shows each skill and its installation status across all detected tools:

Skill: perfetto-cli-usage
Description: Guide for using perfetto-cli to analyze Android Perfetto trace files...
Status (global):
  ✓ claude     ~/.claude/skills/perfetto-cli-usage
  ✓ cursor     ~/.cursor/skills/perfetto-cli-usage
  ✗ codex      (not installed)
  - gemini     (not detected)

Uninstalling Skills¶

# Interactive uninstall
perfetto-cli skills uninstall

# Uninstall specific skill from all tools
perfetto-cli skills uninstall perfetto-cli-usage --target all --scope global

# Uninstall all skills
perfetto-cli skills uninstall --all --target all --scope global

Using with Claude Code¶

After installing skills, you can interact with Claude Code naturally:

> I have a trace file at ./app-trace.perfetto-trace, the app feels laggy

Claude will automatically:
1. Run frame jank analysis
2. Check CPU hotspots
3. Look for binder latency issues
4. Provide a diagnosis with next steps

Example Conversations¶

ANR diagnosis:

> My app got an ANR, analyze this trace: ./anr-trace.perfetto-trace

Claude runs:
  perfetto-cli -t ./anr-trace.perfetto-trace -p com.myapp anr detect
  perfetto-cli -t ./anr-trace.perfetto-trace -p com.myapp anr root-cause --anr-timestamp <ts>

Performance audit:

> Do a full performance check on this trace for com.example.app

Claude runs:
  perfetto-cli -t trace.perfetto-trace -p com.example.app frame summary
  perfetto-cli -t trace.perfetto-trace -p com.example.app cpu utilization
  perfetto-cli -t trace.perfetto-trace -p com.example.app memory leak
  perfetto-cli -t trace.perfetto-trace -p com.example.app binder profile

Capturing traces:

> Capture a 15-second trace from my device

Claude runs:
  perfetto-cli trace run --duration 15s -o ./traces

Using with Cursor¶

With skills installed, Cursor's AI assistant can:

Suggest perfetto-cli commands in the terminal
Interpret trace analysis results inline
Provide fix suggestions based on performance data

Open Cursor's terminal and ask the AI to analyze traces naturally.

Using with Other AI Tools¶

The skills system works with any AI coding tool that supports a skills/ directory in its config. The skill file (SKILL.md) contains structured guidance that helps the AI understand when and how to use perfetto-cli.

Creating Custom Skills¶

Skills are directories containing a SKILL.md file with YAML frontmatter:

---
name: my-custom-analysis
description: Custom analysis workflow for my project
---

# My Custom Analysis

When the user asks about [specific scenario], run:

\`\`\`bash
perfetto-cli -t <trace> -p com.myapp [commands...]
\`\`\`

Place custom skills in the skills/ directory at your project root, then install them with perfetto-cli skills install.

Tips¶

Install skills globally (--scope global) for convenience across all projects
Use project-level install when you have project-specific analysis workflows
Skills are symlinked by default — updates to skill files take effect immediately
Use --copy flag if you need isolated copies instead of symlinks
Use --force to update existing installations