Skip to content

Automate

heaptrail's reports are plain text for people. Every mode can also write the same result as JSON, so a script, a CI job or an agent can read it. This section covers the machine-readable side: the files heaptrail writes, how to gate a build on a result, and how to hand the whole investigation to Claude Code.

Start here

  1. JSON output shows --json and --json-out, what each mode writes, and jq recipes.
  2. Gate a build on a leak threshold turns a report into a pass or fail.
  3. The Claude Code plugin lets an agent run heaptrail for you.

Your goal, and the page

Your goal Page
Write a report to a file with a name I choose JSON output
Pull one number out of a report JSON output
Fail a build when memory use crosses a line Gate a build on a leak threshold
Know which exit status means what Errors and exit codes
Let Claude run the triage The Claude Code plugin
See every field of every JSON file JSON schemas

Why heaptrail suits automation

  • It is a single binary with no runtime. A CI job downloads it and runs it. See Install.
  • Output is deterministic in shape. The same command on the same dump prints the same fields. Row order among equal counts can vary, so gate on values, not on positions.
  • Exit status says what happened. 0 for success, 1 for a heaptrail error, 2 for a bad command line, 101 for a panic.
  • JSON paths are yours to choose, with --json-out.