echolot 0.3.0

Find where Android startup time actually goes — from a Perfetto trace down to a line of code.

Contents · What it is · Requirements · Quick start · What you get · Commands · Detectors · How it works · Project layout · Documentation · Status

What it is

A Perfetto trace of one cold start holds around half a million slices in eighty megabytes. Nobody reads that, and an AI agent pointed at the raw file produces confident guesses instead of answers.

echolot sits in between. It runs six SQL detectors over the trace and returns about twenty rows: where the time went, how much of it, and the evidence behind each claim. Same trace in, same report out — the trace_processor version is pinned and verified on every run.

[!TIP] The intended way to use it is through Claude Code: you describe the regression in plain words, the agent collects traces, reads the report and walks down to the code. The command line works on its own too — see without an agent.

Requirements

Validated on Android 14 (emulator) and Android 13 (Galaxy A51).

Quick start

1. Install

pipx install echolot

2. Set up your project

Run this once inside your Android project:

cd ~/my-app && echolot init

This installs the .claude/ layer — a skill, the perf-hunter agent and three commands — then checks that this machine computes traces correctly.

3. Open the agent and type one word

/echolot

That is the only entry point you need to remember. It asks the tool where the project stands and takes the next step by itself:

• first run — builds echolot.yml from your repository and a probe trace, asking you four questions along the way;
• every run after — hunts down the regression you describe.

/echolot                          reads the state, does whatever is next
/echolot why is cold start slow   hunt, with that as the question
/echolot init | setup | hunt | reflect | doctor

Coming back later

echolot

Prints where the project stands — layer, config, traces, last report, last doctor — and one line saying what to do next.

[!IMPORTANT] After upgrading the package, run echolot init again. It brings the .claude/ layer up to date and leaves files you edited alone.

Without an agent

The same work, by hand or in CI:

echolot collect -c echolot.yml -n 5                              # 5 repeats of the scenario
echolot analyze .echolot/traces/*.perfetto-trace -c echolot.yml  # build the report
echolot doctor -q                                                # exit 0/1: is this environment sane?

Results land in .echolot/out/ — report.md for you, report.json for the agent.

What you get

A Marker Report: one section per detector that fired, nothing else.

# Marker Report

Runs: **5**, numbers are medians across them
Process: `com.example.app` (pid 12903)
Scenario window: **1184 ms** (from 1102 to 1291)
Detectors fired: **3 of 6**

## Where the main thread spent its time

_measured as SELF time, children subtracted_

| Where | N | Self, ms | Total, ms | Max, ms |
|---|---|---|---|---|
| draw | 4 | 125.4 | 130.1 | 61.2 |
| TextLayout:initLayout | 61 | 88.0 | 88.0 | 4.1 |
| inflate | 12 | 47.3 | 210.7 | 12.9 |

## Blind spots: threads burning CPU with no instrumentation

_the only detector that finds a problem inside uninstrumented code_

| Where | Total, ms | Instrumented, ms | Evidence |
|---|---|---|---|
| DefaultDispatcher-worker-2 | 340.2 | 0.0 | 0 slices |

## Monitor contention

| Where | N | Total, ms | Max, ms | Evidence |
|---|---|---|---|---|
| Lock contention on a monitor lock | 9 | 61.5 | 22.4 | owner tid 12931 |

**Silent:** gc_pressure, binder_txn, runnable_starvation

The report is written for two readers at once: report.md reads like a findings list, report.json carries the same numbers in a shape the agent can walk. An 81 MB trace with 475k slices comes out as a 14 KB report.json in about five seconds.

Commands

Three audiences share one CLI, and echolot --help says which is which — the grouping below is generated from the same registration, so the two cannot drift apart.

Every argument after /echolot is a verb of the same name, doing the same thing plus whatever loop needs an agent. One word, one meaning, both surfaces.

Yours

The pipeline — for CI, and for traces by hand

The investigation

.echolot/traces/ and .echolot/out/report.json mean "the latest set". An investigation is the label that says which question that set was recorded for, so that coming back a week later does not answer a question about scrolling with cold-start traces.

echolot hunt "cold start was 3s, now 7s" --since "the tab redesign"

That opens one, moves the previous set of traces aside without deleting it, and says whether the last investigation left temporary markers in your sources. echolot hunt on its own says what is open.

echolot hunt --list          every investigation, newest first
echolot hunt --show 2        one of them in full — including where its traces went
echolot hunt --resume        carry on with the open one
echolot hunt --done "..."    record what it came to

Each one is numbered, and everything it produces is filed under it: every round of traces by path, every report as a copy in .echolot/hunts/<n>/reports/. So a question asked three weeks ago still knows what was measured to answer it, and what each round concluded on the way.

Nothing moves to make this work — collect still writes to .echolot/traces/ and the latest report is still .echolot/out/report.json, so every example above and any CI job keep working unchanged.

You rarely type any of it. /echolot reads the state and, when an investigation has been sitting untouched with traces behind it, asks whether to carry on or start something new — and never asks inside the hunting loop, which re-records and re-instruments on purpose.

Detectors

That last one is the only detector that finds a problem inside code nobody instrumented. It does not guess — it states a fact:

thread DefaultDispatcher-worker-2 was Running for 340 ms, zero slices

Which is exactly where to add trace{} and record again.

[!NOTE] Each detector is one self-contained .sql file with its metadata in the header. Drop a file into echolot/sql/detectors/ and it is picked up — there is no registration step in code. See docs/detectors.md.

How it works

flowchart LR
    A["Android device"]
    B["trace<br/>81 MB · 475k slices"]
    C["6 SQL detectors<br/>pinned trace_processor"]
    D["report.md<br/>~20 rows"]
    E["report.json<br/>14 KB"]
    F(["You"])
    G(["The agent"])

    A -->|"echolot collect"| B
    B -->|"echolot analyze"| C
    C --> D --> F
    C --> E --> G

Project layout

android-project/
├── echolot.yml       ← the project half, committed
├── local.yml         ← device serials, binary path; in .gitignore
└── .echolot/         ← traces, reports, run log, reflect reports; in .gitignore

Read it the way you read gradle.properties and local.properties: one tool per machine, and the binding to a project living inside that project's repository.

Documentation

Start at the documentation index, or jump straight in:

Agent-facing reference material ships inside the package under echolot/claude/skills/echolot/references/ — the report schema, the config schema, how ART names things, and how to capture a trace by hand.

Status

v0. Everything planned for it is in place except CI mode.

The detectors were validated against a synthetic trace — 46 checks inside doctor — and against live traces from Android 14 (emulator) and Android 13 (Galaxy A51). The naming masks for GC, locks and binder were narrowed against those real traces, and every narrowing is pinned by a check.

[!WARNING] CI mode is not done. scenario.budget_ms is declared in the config but never read. What is missing is analyze with an exit code — either against the budget or on "any detector fired", which after calibrate amounts to a comparison against the baseline.

A failed detector never fails the run: the error goes to stderr and into report.json.

License

Apache 2.0