echolot 0.9.0

Turns a huge Android trace into 20 rows of facts an AI agent can actually use.

• Finds the line to fix. From a slow screen to a file and line, with the numbers that prove it.
• Same answer, every run. A pinned trace_processor: the same trace always gives the same report.
• No tracing code needed. Works on apps with zero trace {} calls; it places temporary markers itself.
• Works with your agent. Claude Code out of the box; Cursor, Codex and others via echolot guide.

Contents · Quick start · How it works · What it saves · What you get · What changed

Reference · Detectors · Commands · Requirements · Project layout · Documentation · Status

Quick start

You need Python 3.10+, adb, and a phone or emulator with USB debugging on. The full list is under Requirements.

1. Install

pipx install echolot

echolot --version names what you got. Installed with pip into an environment whose scripts are not on PATH, python -m echolot is the same command.

2. Set up your project

cd ~/my-app && echolot init

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

3. Open the agent and type one word

/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

The first run builds echolot.yml from your repository and a probe trace, asking you four questions along the way. Every run after that hunts down the regression you describe.

What to ask

Describe the problem the way you would to a colleague:

Coming back later

echolot on its own prints where the project stands and the next step. After upgrading the package, run echolot init again: it brings the .claude/ layer up to date and leaves the 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 compare before.json .echolot/out/report.json             # what changed since
echolot doctor -q                                                # is this environment sane? exit 0 yes, 1 no or not checked, 2 trace_processor not downloaded

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

How it works

echolot runs thirteen SQL detectors over a Perfetto 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.

The recording, the detectors and the comparison are scripts that run the same way every time. In each round the agent makes one decision: where to look next. The loop ends when the report names a place in the code, or when the rounds run out.

The investigation

Each question you bring gets an investigation. echolot hunt "cold start was 3s, now 7s" --since "the tab redesign" opens one, sets the previous traces aside without deleting them, and files every round of traces and every report under it, so a question asked weeks ago still knows what was measured to answer it. /echolot opens and closes them for you. The commands, and what each one keeps, are in The agent layer.

What it saves

Cost is the measure because it includes the work of the agent's subagent: token counts leave that out, and time went both ways across the four models.

What you get

A Marker Report: what was measured, then one section per detector that fired. The silent ones are named too.

# Marker Report

Runs: **5**, numbers are medians across them
Traces: `coldStart_iter000`, `coldStart_iter001`, `coldStart_iter002`, `coldStart_iter003`, `coldStart_iter004`
Process: `com.example.app` (pid 12903)
Scenario window: **1184.37 ms** (from 1102.14 to 1291.52)
Main thread: 49% on a CPU · 8% waiting for a CPU · 10% blocked in the kernel · 33% sleeping
Covered by the findings below: **31%** of the main thread's window, each moment counted once
Device: clock **1481 MHz** (from 1204 to 1622 across repeats), peak 54 °C, 1536 MB free at the low point
Detectors fired: **5 of 13**
Config: `/home/you/my-app/echolot.yml` (sha 3f9a1c2b7d40) · thresholds: built-in defaults

## Markers
_the names `domains` lists and the `AGENTTMP_` ones; medians per run, self time with children subtracted_

| Marker | Runs | N | Self, ms | Total, ms | Max, ms | Threads |
|---|---|---|---|---|---|---|
| collection_load | 5/5 | 1 | 212.4 | 212.4 | 212.4 | (async) |
| collection_mapping | 5/5 | 1 | 96.0 | 118.3 | 118.3 | arch_disk_io_1 |

## Frames that missed their deadline
_the platform classifies every frame itself, and says whose fault it was. The only detector that answers "which frames stuttered" rather than "where did the total go" — and it needs no instrumentation in the app at all._

| Where | Runs | N | Total, ms | Max, ms | Evidence |
|---|---|---|---|---|---|
| App Deadline Missed | 5/5 | 14 | 412.0 | 70.1 | Self Jank · 14 of 300 frames · longest 86.2 ms |

<sub>detector `frame_jank`, params: {'min_frames': 3, 'min_overrun_ms': 4}</sub>

## Where the main thread spent its time
_measured as SELF time, children subtracted — otherwise one event lands in the report several times at different depths and the agent counts it twice_

| Where | Runs | N | Self, ms | Total, ms | Max, ms | Evidence |
|---|---|---|---|---|---|---|
| draw | 5/5 | 4 | 125.4 | 130.1 | 61.2 | com.example.app |
| TextLayout:initLayout | 5/5 | 61 | 88.0 | 88.0 | 4.1 | com.example.app |
| inflate | 5/5 | 12 | 47.3 | 162.4 | 21.7 | com.example.app |

<sub>detector `main_thread_block`, params: {'min_slice_ms': 16}</sub>

## Single occurrences far longer than the same work usually takes
_the pair to main_thread_block. That one asks where the main thread's time went in total; this one asks which single occurrence was out of line with its own history. A heavy tail hides from every sum._

| Where | Runs | N | Total, ms | Max, ms | Evidence |
|---|---|---|---|---|---|
| inflate | 2/5 | 1 | 86.2 | 86.2 | median 12.9 ms of 12 · worst 6.7× |

<sub>detector `main_thread_outlier`, params: {'factor': 4, 'min_abs_ms': 40, 'min_occurrences': 5}</sub>

## Monitor contention
_ART writes a "Lock contention on ..." slice with the owner's tid — ready-made evidence_

| Where | Runs | N | Total, ms | Max, ms | In the code | Evidence |
|---|---|---|---|---|---|---|
| com.example.app | 5/5 | 9 | 61.5 | 22.4 | owner at StoreRepository.kt:30 · blocked at StoreRepository.kt:66 | monitor contention with owner DefaultDispatcher-worker-3 (12931) at void com.example.app.data.StoreRepository.update(com.example.app.data.Item)(StoreRepository.kt:30) waiters=0 blocking from com.example.app.data.Item com.example.app.data.StoreRepository.find(long)(StoreRepository.kt:66) |

<sub>detector `monitor_contention`, params: {'min_block_ms': 8, 'max_total_ms': 50, 'name_glob': 'Lock contention on a monitor lock*', 'name_glob_alt': 'monitor contention with owner*'}</sub>

## Blind spots: threads burning CPU with no instrumentation
_the ONLY detector that finds a problem inside uninstrumented code. The agent does not guess — it is handed the fact "thread T ran for 340 ms, zero slices". That is exactly where adding trace{} pays off._

| Where | Runs | N | Total, ms | Instrumented, ms | Evidence |
|---|---|---|---|---|---|
| DefaultDispatch | 5/5 | 0 | 340.2 | 0.0 | 100.0% of CPU outside slices |

<sub>detector `uninstrumented_cpu`, params: {'min_running_ms': 50, 'max_covered_pct': 50}</sub>

**Silent:** anr, anr_risk, app_init, binder_txn, gc_pressure, io_wait, repeated_work, runnable_starvation

<sub>trace_processor v56.1</sub>

report.md is for you, report.json for the agent. An 81 MB trace with 475k slices comes out as a 14 KB report.json in about five seconds.

What changed

The report says where the time went in one set of traces. The question people arrive with has a second half — it was 3 s, now it is 7 s — and that needs two sets.

echolot compare                       # inside an investigation: previous round vs latest
echolot compare old.json new.json     # or name them

One table, sorted by how far each row moved. The top row is usually the answer.

A report built against other thresholds, or on a device whose clock moved or throttled between the rounds, is named above the table. See Comparing.

Detectors

uninstrumented_cpu, io_wait and frame_jank find a problem where nobody wrote a trace{} call. What each detector sees is in Analysing, and writing your own in Detectors.

Commands

echolot --help lists every command in four groups. Every verb after /echolot is an echolot command of the same name, except setup, which only the agent has. The pipeline — collect, analyze, compare — is under Without an agent.

Yours

Requirements

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

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

echolot init adds the last two to .gitignore at the root of a git checkout, and otherwise prints the two lines to add: a trace is tens of megabytes.

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. What each detector was checked against, from the synthetic fixture to live traces, is in Determinism.

A failed detector never fails the run: the error goes to stderr and into report.json. Working on the tool itself starts at CONTRIBUTING.md, which GitHub shows as a tab beside this README.

License

Apache 2.0