perfetto-analyzer 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# perfetto-analyzer
+
+AI skill for Android performance analysis using [Perfetto](https://perfetto.dev).
+
+Automatically installs into all supported AI agents on your machine.
+
+## Installation
+
+```bash
+# Run once — installs for all supported agents
+npx perfetto-analyzer install
+
+# Or install globally (auto-installs via postinstall)
+npm install -g perfetto-analyzer
+```
+
+## Supported AI Agents
+
+| Agent | Skills directory |
+|---|---|
+| Claude Code | `~/.claude/skills/perfetto-analyzer/` |
+| GitHub Copilot | `~/.github/copilot/skills/perfetto-analyzer/` |
+| Cursor | `~/.cursor/skills/perfetto-analyzer/` |
+| Antigravity | `~/.antigravity/skills/perfetto-analyzer/` |
+| Codex (OpenAI) | `~/.codex/skills/perfetto-analyzer/` |
+| Devin | `~/.devin/skills/perfetto-analyzer/` |
+
+Directories are created automatically if they don't exist.
+
+## Uninstall
+
+```bash
+npx perfetto-analyzer uninstall
+```
+
+## What it does
+
+After installation, ask your AI assistant to analyze an Android app's performance:
+
+- **Collect a trace** from a connected device via `adb`
+- **Analyze CPU, memory, frames (jank), and battery** from a `.pb` Perfetto trace
+- **Generate a markdown report** with insights and actionable recommendations
+
+### Prerequisites
+
+- `adb` installed and in PATH (Android SDK Platform-Tools)
+- Python 3.9+
+- `pip install perfetto`
+
+## Usage example
+
+> "Analyze the performance of com.myapp.debug, collect a 30s frames trace"
+
+The skill will:
+1. Verify the device is connected
+2. Launch the app if it isn't running
+3. Collect the Perfetto trace
+4. Parse callstacks and frame timelines
+5. Generate a report with hotspots and jank causes
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const SKILL_NAME = "perfetto-analyzer";
+const SKILL_SRC = path.join(__dirname, "..", "skill");
+
+const AGENTS = [
+  { name: "Claude Code",    dir: path.join(os.homedir(), ".claude",      "skills") },
+  { name: "GitHub Copilot", dir: path.join(os.homedir(), ".github",      "copilot", "skills") },
+  { name: "Cursor",         dir: path.join(os.homedir(), ".cursor",      "skills") },
+  { name: "Antigravity",    dir: path.join(os.homedir(), ".antigravity", "skills") },
+  { name: "Codex",          dir: path.join(os.homedir(), ".codex",       "skills") },
+  { name: "Devin",          dir: path.join(os.homedir(), ".devin",       "skills") },
+];
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function removeDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+function padEnd(str, len) {
+  return str + " ".repeat(Math.max(0, len - str.length));
+}
+
+function install(silent) {
+  if (!silent) {
+    console.log(`\nInstalling ${SKILL_NAME} skill...\n`);
+  }
+
+  for (const agent of AGENTS) {
+    const dest = path.join(agent.dir, SKILL_NAME);
+    try {
+      copyDir(SKILL_SRC, dest);
+      if (!silent) {
+        console.log(`  ✓ ${padEnd(agent.name, 16)} → ${dest}`);
+      }
+    } catch (err) {
+      console.error(`  ✗ ${padEnd(agent.name, 16)} ERRO: ${err.message}`);
+    }
+  }
+
+  if (!silent) {
+    console.log(`\nDone! Restart your AI assistant to activate the skill.\n`);
+  }
+}
+
+function uninstall() {
+  console.log(`\nRemoving ${SKILL_NAME} skill...\n`);
+
+  for (const agent of AGENTS) {
+    const dest = path.join(agent.dir, SKILL_NAME);
+    const removed = removeDir(dest);
+    if (removed) {
+      console.log(`  ✓ ${padEnd(agent.name, 16)} removed`);
+    } else {
+      console.log(`  - ${padEnd(agent.name, 16)} not found (skipped)`);
+    }
+  }
+
+  console.log(`\nDone!\n`);
+}
+
+function showHelp() {
+  console.log(`
+${SKILL_NAME} — AI skill for Android performance analysis using Perfetto
+
+Usage:
+  npx ${SKILL_NAME}              Install skill for all supported AI agents
+  npx ${SKILL_NAME} install      Install skill for all supported AI agents
+  npx ${SKILL_NAME} uninstall    Remove skill from all AI agent directories
+  npx ${SKILL_NAME} help         Show this help
+
+Supported agents:
+${AGENTS.map((a) => `  - ${a.name}`).join("\n")}
+`);
+}
+
+const args = process.argv.slice(2);
+const command = args[0] || "install";
+const isPostinstall = args.includes("--postinstall");
+
+switch (command) {
+  case "install":
+    install(isPostinstall);
+    break;
+  case "uninstall":
+    uninstall();
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    showHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    showHelp();
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "perfetto-analyzer",
+  "version": "1.0.0",
+  "description": "AI skill for Android performance analysis using Perfetto — works with Claude Code, Cursor, GitHub Copilot, Codex, Antigravity and Devin",
+  "bin": {
+    "perfetto-analyzer": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skill/"
+  ],
+  "scripts": {
+    "postinstall": "node bin/cli.js install --postinstall"
+  },
+  "keywords": [
+    "android",
+    "perfetto",
+    "performance",
+    "tracing",
+    "claude",
+    "cursor",
+    "copilot",
+    "codex",
+    "skill",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: perfetto-analyzer
+description: >
+  Analisa performance de apps Android usando Perfetto — abstrai adb, configuração de traces e interpretação de métricas.
+  Use quando o usuário quiser medir performance de um app Android, coletar traces, analisar memória (heap), CPU,
+  frames dropados, battery drain, ou quando mencionar Perfetto, profiling, trace .pb, jank, ANR, ou quiser entender
+  gargalos de performance no Android. Também use quando o usuário tiver um arquivo .pb do Perfetto e quiser insights.
+  Dispare mesmo que o usuário não mencione Perfetto explicitamente — se ele falar em "app lento", "memória crescendo",
+  "frames dropando", "CPU alta", "bateria acabando rápido" no contexto Android, esta skill é o caminho.
+---
+
+# Perfetto Analyzer
+
+Você é especialista em performance Android usando Perfetto. Seu papel é:
+1. **Coletar traces** via `adb` (Modo A) ou **analisar traces existentes** (Modo B)
+2. **Interpretar métricas** de memória, CPU, frames e battery
+3. **Gerar relatório markdown** com insights e recomendações acionáveis
+
+---
+
+## Antes de começar — perguntas obrigatórias
+
+Antes de executar qualquer script, colete as informações necessárias perguntando ao usuário. **Nunca assuma valores padrão para duração ou tipo de trace** — são escolhas do usuário, não técnicas.
+
+**Modo A (Coleta automática)** — device Android conectado:
+
+Pergunte explicitamente (em uma única mensagem):
+1. **Package** do app — se não souber, sugira `adb shell pm list packages | grep <nome>` para descobrir
+2. **Tipo de trace** — apresente as opções: `frames` (jank/UI), `memory` (heap/leak), `cpu` (bottlenecks), `battery` (drain), `all` (análise completa)
+3. **Duração** — quantos segundos de gravação? Dica: 10–15s para fluxos específicos, 30s+ para leaks/battery
+
+Só execute o script após ter as três respostas.
+
+**Modo B (Análise de trace existente)** — usuário tem arquivo `.pb`:
+→ Precisa apenas do caminho do arquivo. Prossiga diretamente para a análise.
+
+Se não ficou claro qual modo o usuário quer, pergunte antes de qualquer ação.
+
+---
+
+## Pré-requisitos
+
+| Ferramenta | Como verificar | Instalação |
+|---|---|---|
+| `adb` | `adb version` | Android SDK Platform-Tools |
+| Python 3.9+ | `python3 --version` | python.org |
+| `perfetto_trace_processor` (Python) | `python3 -c "import perfetto"` | `pip install perfetto` |
+
+Verifique antes de executar. Se faltar algo, oriente o usuário.
+
+---
+
+## Modo A — Coleta via adb
+
+### 1. Verificar device conectado
+
+```bash
+adb devices
+```
+
+Se `no devices` ou `offline`, oriente o usuário a:
+- Ativar Opções do Desenvolvedor no Android
+- Ativar Depuração USB
+- Aceitar a permissão no device
+
+### 2. Coletar o trace
+
+Execute o script de coleta:
+
+```bash
+python3 <SKILL_DIR>/scripts/collect_trace.py \
+  --package <PACKAGE> \
+  --type <TRACE_TYPE> \
+  --duration <SEGUNDOS> \
+  --output /tmp/perfetto_trace.pb
+```
+
+Onde `<TRACE_TYPE>` é um dos: `memory`, `cpu`, `frames`, `battery`, `all`
+
+O script vai:
+- Empurrar a config pro device via `adb push`
+- Executar `adb shell perfetto` com a config
+- Aguardar a duração especificada
+- Puxar o arquivo `.pb` para `/tmp/perfetto_trace.pb`
+
+Aguarde e mostre progresso ao usuário (o trace pode levar alguns segundos).
+
+Após coleta bem-sucedida, prossiga para a etapa de análise.
+
+### 3. Instalar dependências se necessário
+
+```bash
+pip install perfetto 2>/dev/null || pip3 install perfetto
+```
+
+---
+
+## Modo B — Análise de trace existente
+
+Use o arquivo `.pb` fornecido como entrada para a análise.
+
+```bash
+cp <ARQUIVO_DO_USUARIO> /tmp/perfetto_trace.pb
+```
+
+---
+
+## Análise do Trace
+
+### Passo 1: Parsing
+
+```bash
+python3 <SKILL_DIR>/scripts/parse_perfetto_pb.py \
+  --input /tmp/perfetto_trace.pb \
+  --output /tmp/perfetto_parsed.json \
+  --package <PACKAGE>
+```
+
+O script extrai via SQL queries na Trace Processor API:
+- Alocações de heap (nativo + ART)
+- Samples de CPU por callstack
+- Frame timeline (frames renderizados vs dropados)
+- Contadores de battery
+
+### Passo 2: Análise de métricas
+
+```bash
+python3 <SKILL_DIR>/scripts/analyze_metrics.py \
+  --input /tmp/perfetto_parsed.json \
+  --output /tmp/perfetto_insights.json
+```
+
+Calcula: top callstacks, percentis de frame, anomalias, recomendações.
+
+### Passo 3: Gerar relatório
+
+```bash
+python3 <SKILL_DIR>/scripts/generate_report.py \
+  --insights /tmp/perfetto_insights.json \
+  --package <PACKAGE_OU_UNKNOWN> \
+  --trace-type <TIPO_OU_all>
+```
+
+O relatório vai para stdout. Apresente ao usuário formatado como markdown.
+
+---
+
+## Formato do Relatório
+
+O relatório gerado segue este template. Apresente-o completo, sem truncar:
+
+```markdown
+# Relatório de Performance — <package>
+**Dispositivo:** <device> | **Data:** <data> | **Duração:** <Xs> | **Tipo:** <tipo>
+
+## Resumo Executivo
+> Top 3-5 findings mais críticos, em ordem de impacto
+
+## Memória
+### Maiores Alocadores (Heap Nativo)
+<tabela: callstack | bytes não-liberados | % total>
+
+### Objetos Java/Kotlin Retidos (ART)
+<tabela: classe | instâncias | bytes>
+
+### Alertas
+- ⚠️ [se heap churn alto, possível leak, etc.]
+
+## CPU
+### Top Funções (Self Time)
+<tabela: função | thread | % CPU>
+
+### Callstacks Mais Frequentes
+<top 5 por ocorrência>
+
+### Alertas
+- ⚠️ [se main thread bloqueada, GC excessivo, etc.]
+
+## Frames
+| Métrica | Valor | Threshold OK |
+|---|---|---|
+| Total de frames | N | — |
+| Frames dropados | N (X%) | < 1% |
+| Frame P50 | Xms | < 16ms |
+| Frame P95 | Xms | < 32ms |
+| Frame P99 | Xms | < 50ms |
+
+### Causas de Jank
+<tabela: causa | ocorrências>
+
+## Battery
+| Métrica | Valor |
+|---|---|
+| Carga drenada | X mC (miliCoulombs) |
+| Duração do trace | Xs |
+| Taxa média de drain | X mC/s |
+
+### Top Consumidores
+<tabela: componente | consumo estimado>
+
+## Recomendações
+1. **[Título]** — [Descrição do problema + ação concreta]
+2. ...
+
+## Próximos Passos
+- [ ] Verificar X em flame graph no perfetto.dev/ui
+- [ ] Correlacionar Y com Z
+```
+
+---
+
+## Referências
+
+Leia estes arquivos quando precisar de mais contexto:
+
+| Arquivo | Quando ler |
+|---|---|
+| `references/perfetto-traces-reference.md` | Quais traces coletar, configs textproto, quando usar cada um |
+| `references/metrics-interpretation.md` | O que significa cada métrica, thresholds, red flags |
+| `references/adb-quick-start.md` | Setup adb, troubleshooting de device, permissões |
+
+---
+
+## Erros Comuns
+
+**`no devices/emulators found`** → Verificar USB debugging e `adb devices`
+
+**`ImportError: No module named 'perfetto'`** → `pip install perfetto`
+
+**`Error opening trace file`** → Arquivo .pb corrompido ou versão incompatível do Perfetto. Tentar reabrir no perfetto.dev/ui para validar.
+
+**Trace vazio ou sem dados** → App pode não ter sido usada durante a coleta. Instruir o usuário a interagir com o app durante a gravação.
+
+**`permission denied` no device** → `adb shell su -c perfetto ...` (requer root) ou usar heapprofd com `run-as`

package/skill/references/adb-quick-start.md

@@ -0,0 +1,139 @@
+# ADB Quick Start — Setup para Perfetto
+
+## Instalação do adb
+
+### macOS
+```bash
+brew install android-platform-tools
+# ou baixar manualmente:
+# https://developer.android.com/tools/releases/platform-tools
+```
+
+### Linux (Ubuntu/Debian)
+```bash
+sudo apt install android-tools-adb
+```
+
+### Verificar instalação
+```bash
+adb version
+# Android Debug Bridge version 1.0.41
+```
+
+---
+
+## Conectar device
+
+### Via USB (recomendado para traces)
+
+1. No Android: **Configurações → Sobre o dispositivo → Número da compilação** (toque 7x)
+2. **Configurações → Opções do desenvolvedor → Depuração USB** → Ativar
+3. Conectar cabo USB
+4. Aceitar prompt "Permitir depuração USB?" no device (marque "Sempre permitir")
+
+```bash
+adb devices
+# List of devices attached
+# XXXXXXXX    device    ← OK
+# XXXXXXXX    offline   ← Precisa aceitar no device
+# XXXXXXXX    unauthorized  ← Precisa aceitar no device
+```
+
+### Via Wi-Fi (Android 11+)
+
+1. **Opções do desenvolvedor → Depuração sem fio**
+2. **Parear device** → anotar IP:porta
+3. `adb pair <ip>:<porta>`
+4. `adb connect <ip>:<porta>`
+
+**Atenção:** Traces via Wi-Fi podem ser mais lentos para fazer `pull`. Para traces grandes (> 50 MB), prefira USB.
+
+---
+
+## Troubleshooting
+
+### `no devices/emulators found`
+```bash
+# Reiniciar servidor adb
+adb kill-server
+adb start-server
+adb devices
+```
+
+### `device offline` ou `unauthorized`
+- Desconectar e reconectar cabo
+- Aceitar prompt no device
+- Se persistir: **Opções do desenvolvedor → Revogar autorizações de depuração USB** e re-autorizar
+
+### `permission denied` ao executar Perfetto no device
+
+O Perfetto requer permissão para coletar traces. Em Android 9+, o `traced` daemon já está rodando e aceita conexões de apps com permissão ou via shell.
+
+```bash
+# Verificar se traced está rodando
+adb shell pgrep -a traced
+
+# Se não estiver:
+adb shell setprop persist.traced.enable 1
+adb shell start traced
+adb shell start traced_probes
+```
+
+Para heap profiling (heapprofd), o app precisa ser debuggable OU o device precisa estar rootado:
+```bash
+# Verificar se app é debuggable
+adb shell pm dump <PACKAGE> | grep DEBUGGABLE
+```
+
+Se o app não for debuggable, use um build de debug ou:
+```bash
+# Root: habilitar profiling em release builds
+adb shell setprop security.perf_harden 0
+```
+
+### `Error: Detach failed`
+
+Alguns devices exigem:
+```bash
+adb shell "echo 0 > /proc/sys/kernel/perf_event_paranoid"
+```
+
+---
+
+## Coleta manual via adb (referência)
+
+O método mais robusto usa `adb exec-out` com stdin/stdout — sem gravar nada no device:
+
+```bash
+# Config via stdin, trace via stdout — sem permissões no device
+cat frames.textproto | adb exec-out perfetto --txt -c - -o - > /tmp/trace.pb
+```
+
+Funciona em emuladores e devices físicos porque:
+- `--txt` indica config em texto (textproto)
+- `-c -` lê a config de stdin
+- `-o -` escreve o trace em stdout
+- `adb exec-out` transfere binário sem conversão de newlines (ao contrário de `adb shell`)
+
+**Importante:** Não use `-o /sdcard/...` — o daemon do Perfetto roda com UID diferente do shell e não tem permissão de escrita no sdcard. Use stdout (`-o -`) ou `/data/misc/perfetto-traces/` (que exige pull separado).
+
+---
+
+## Comandos úteis durante troubleshooting de trace
+
+```bash
+# Ver logs do sistema em tempo real
+adb logcat -s perfetto traced heapprofd
+
+# Verificar se o traced daemon está rodando
+adb shell pgrep -a traced
+
+# Ativar daemon manualmente se não estiver rodando
+adb shell setprop persist.traced.enable 1 && adb shell start traced
+
+# Listar processos do app
+adb shell ps -ef | grep <PACKAGE>
+
+# Ver PID do app (útil para heapprofd)
+adb shell pidof <PACKAGE>
+```