echolot documentation
Twelve documents. If you are here for the first time, read them in the order of
the workflow: collect → mark → analyse → compare → calibrate. The rest
explains why the tool is built the way it is.
Using it
The path from a device to an answer, in the order you walk it.
| document |
read it when |
| 🎬 Collecting traces |
you need traces — the three modes (launch, command, gradle), what the trace config must contain, callstack sampling and what it costs, and why repeats are merged rather than averaged |
| 🧊 ANRs |
the app stopped answering and the report came from a phone you do not have — reading it, pointing its frames at your files, and measuring the freeze when you can record it |
| 🏷️ Marking |
your project has no instrumentation and the report has nothing to attach findings to — mark writes the first markers from the platform's vocabulary, --apply / --remove |
| 🔎 Analysing |
you have a trace and need a place in the code — probe, names, domains, and the slice-to-code map |
| 🔀 Comparing |
you have two sets of traces and need the difference — what appeared, what grew, and whether the repeats support calling it a change |
| 📏 Calibrating |
the shipped thresholds fire on everything, or on nothing — derive them from known-healthy runs instead, and why rank beats percentile |
Understanding it
Why the answers can be trusted, and what the tool refuses to do.
| document |
about |
| 🔒 Determinism |
the pinned trace_processor, the synthetic fixture, what doctor actually checks, and where determinism ends |
| 🤖 The agent layer |
what echolot init installs, and a private install git does not see; the plugin for Claude Code and Codex, why a CLI rather than an MCP server, why the loop lives in a subagent |
Extending it
| document |
about |
| ⚙️ Detectors |
writing your own — the context views, why two duration columns are not a duplicate, self time versus total |
| 🪞 Reflect |
the same kind of report, over an agent session: how the tool was used, where it got in the way |
Maintaining it
| document |
about |
| 📦 Publishing |
cutting a release — the tag, Trusted Publishing, how the notes are grouped, checking artefacts locally |
| 🗺️ Planning |
where work is tracked — filing an issue, the four fields the roadmap board sorts by, when a spike comes first, and how a card reaches Done |
Also shipped inside the package
Reference material the agent reads, under
echolot/claude/skills/echolot/references/:
| file |
about |
report.md |
the Marker Report schema — the shape of report.json |
config.md |
the echolot.yml schema, field by field |
naming.md |
how ART names things, and what the detector masks match |
collect.md |
capturing a trace by hand, without collect — and what happens while a collect runs and when it fails |