Heap snapshot diagnostics (memory bloat investigation via CLI)
A CLI endpoint that captures a heap snapshot of the renderer (the default) or of the main process (?target=main), parses it, and returns a small summary of where the memory is going — the supported way to answer "Omniscio is using 2 GB of RAM, where is it going?" without opening DevTools.
On this page
What it is
POST /diagnostics/heap-snapshot is a CLI endpoint on Omniscio's local control server (port 19519) that captures a V8 heap snapshot of the renderer process — or, with ?target=main, of the main process — parses it, and returns a small JSON summary describing where the memory is going. It's the supported way for an agent — Claude Code, the in-app chat, an external tool reading ~/.amc/cli-token — to investigate "Omniscio is using 2 GB of RAM, where is it going?" without the user having to open DevTools.
Why this exists. Omniscio strips the Windows menu accelerators (mainWindow.removeMenu()), so Ctrl+Shift+I does not open DevTools. The standard developer workaround — launching with --remote-debugging-port — is forbidden by the project's security postmortem (it would expose an authenticated debugger socket on every Omniscio start). This endpoint lets agents drive a memory diagnosis programmatically while keeping Omniscio's debugger surface closed.
Where to find it
How to use it
Calling the endpoint
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST diagnostics/heap-snapshot
For the MAIN process — the isolate that owns the backups and every git spawn, and the one a
"JavaScript heap out of memory" crash actually names — add ?target=main:
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST "diagnostics/heap-snapshot?target=main&keep=true"
The response carries target (renderer or main) so a caller always knows which isolate it
captured.
One thing main no longer covers. Main also owns the original auto-lander's loop — until
Lander V3 is switched into own mode (the landing-v3-own switch), at which point the landing
loop runs in its own Electron utility process. This endpoint captures only the renderer or main,
so a main snapshot no longer reaches the train loop; read that process's state from the control
server's Lander V3 status route instead (Lander V3). Everything else a main
snapshot is used for — the backups, every git spawn, the rest of the app's main-process work — is
unchanged.
A successful response looks like:
{
"ok": true,
"snapshotBytes": 312654321,
"summary": {
"totals": {
"nodeCount": 8421337,
"edgeCount": 31845121,
"totalSelfSize": 2147483648
},
"byNodeType": [
{ "type": "string", "count": 5132904, "totalSelfSize": 1612345678 },
{ "type": "object", "count": 1842031, "totalSelfSize": 412345122 },
{ "type": "array", "count": 421873, "totalSelfSize": 98123455 }
],
"topClassNames": [
{ "name": "system / Module", "count": 8123, "totalSelfSize": 142312345 },
{ "name": "HTMLDivElement", "count": 142003, "totalSelfSize": 84123887 }
],
"largeStrings": {
"count": 1247,
"totalSize": 783451123,
"categories": { "dataImage": 612345128, "dataOther": 41205555, "generic": 129900440 },
"samples": [{ "size": 4823472, "preview": "data:image/png;base64,iVBORw0KGgoAAAANSU…" }]
}
}
}
Reading the summary
totals.totalSelfSizeis what to compare against the OS reported renderer RSS. It's the sum of every node'sself_sizein bytes — close to JS-reachable memory, not counting V8 internals or native buffers.byNodeTypeis your first triage cut. Ifstringdominates, you're looking at retained text/base64/buffers; ifobjectdominates, you're looking at retained DOM or app objects; ifcodedominates, you have many compiled functions resident (rare).topClassNames(capped at 25 bytotalSelfSize) names the worst object retainers. Names are pulled from the V8stringstable for non-string-type nodes — for plain objects this is the constructor name (HTMLDivElement,Map, custom classes, etc.).largeStringsisolates the >1 KB string nodes and splits them intodataImage(base64-encodeddata:image/...),dataOther(otherdata:URLs — Office docs, blobs), andgeneric(everything else — long JSON blobs, pasted text, agent message buffers). The 10 largest are returned assampleswith truncated previews so you can sanity-check what's pinned.
Optional behavior
?keep=true— the captured.heapsnapshotfile is normally deleted after parsing to save disk. Withkeep=true, the response includessnapshotPathso you (or the user) can later open the file in DevTools' Memory panel for a deeper retention-path walk.- A second POST while the first is still in-flight returns 409 with
error: "snapshot capture already in flight". Capture is single-flight by design — running two concurrenttakeHeapSnapshotcalls would double the transient memory pressure.
How it behaves
Cost and limits
- Time: ~2–6 seconds end-to-end on a 2 GB renderer. The capture itself is fast; reading and parsing the resulting JSON file is the slow part.
- Disk: the snapshot file is 200–500 MB for a typical renderer. It is written under
<userData>/heap-snapshots/<ISO-timestamp>.heapsnapshotand deleted unlesskeep=true. - Main-process memory: the file is streamed through the parser in 1 MiB chunks and aggregated as it goes, so nothing ever holds the whole file or its
JSON.parseobject graph. Peak extra memory is proportional to the number of distinct class names and distinct large-string values — roughly a few hundred bytes each, since a class name is kept whole and a large-string value is kept to its first 160 characters for its category and preview — not to the snapshot's size. A 520 MiB snapshot whose bulk was one long string was measured at ~1.5 MB of heap growth in ~0.6 s. The old whole-file read could not handle a snapshot larger than V8's ~512 MiB string cap at all (RangeError: Invalid string length). Capture stays single-flight because two concurrenttakeHeapSnapshotcalls would still double the capture-side pressure. - Strings-section parse cost: a
stringsentry the summary does not retain (almost all of them) is skipped by scanning forward to its closing quote and honouring escapes, so each entry costs its own length and never a lookahead to the end of the chunk. Measured in the parser's own test harness over short escape-free entries: ~40 ms of parse work per MiB ofstringsJSON, regardless of chunk size. The guard that pins this — the same payload parsed in 64 KiB and in 1 MiB chunks at comparable cost — is intests/unit/services/heap-snapshot-parser-streaming.test.ts. - Main-process target costs a freeze, not just time:
?target=mainsnapshots this process withv8.writeHeapSnapshot, which is a stop-the-world heap walk — the app cannot serve an IPC call or run a timer while it runs, so budget seconds to tens of seconds on a 1–2 GB heap. A renderer capture blocks only the renderer. Use the main target when a crash or an OOM is the question; use the default for routine bloat hunting. - Main-process disk: the file is written as
<userData>/heap-snapshots/main-<ISO-timestamp>.heapsnapshot, typically 1–3 GB on a struggling main process. Samekeep=truesemantics, same retention (newest three kept). - Main-process summary cap: above 512 MB the summary is skipped and the response says so in
summarySkipped, withsummary: null, because parsing is 5–10x the size the parser was tuned on. The file is still written, so it can be read offline in DevTools — and it is KEPT even withoutkeep=true(the response carriessnapshotPath, newest three retained), because the capture already paid the stop-the-world freeze and an unsummarised file the caller never receives would be pure cost. - Rate limit: shares the 19519 server's global mutation cap (10/min). Combined with single-flight, the effective cap is one capture every few seconds.
- Auth: the full-trust
~/.amc/cli-tokenis required. That is stricter than/projects,/sessionsand the search routes, which also answer a scoped agent-session token; a scoped token is refused here.
When to use it
- "Omniscio's RSS is climbing past 2 GB and I want to know what's pinned." Run the endpoint, look at
byNodeTypefirst, then drill intotopClassNamesorlargeStrings.samplesbased on which dominates. - "I think feature X retains image data after the user navigates away." Capture a snapshot before opening X, capture another after closing it, compare
largeStrings.categories.dataImageandtopClassNamesdeltas. - "I want to verify a memory fix actually freed memory." Capture before and after —
totals.totalSelfSizeand the per-class entry for the fixed component should both drop.
When NOT to use it
- Don't poll it on a timer. Each capture costs disk + transient RAM. Use it when you have a specific question, not as a heartbeat.
- Don't use it to inspect child processes. The endpoint snapshots the renderer (
mainWindow.webContents) or the main process (?target=main); CLI spawns andmempalace-serverare separate processes and out of scope. - Don't ship code that depends on the response shape long-term — the
summaryshape is a debug aid and may evolve as the parser learns to extract more useful signals.
Related
- Session memory paging — what Omniscio does when a session memory grows.
- Resources diagnostic panel — the panel that reads this alongside everything else.
- Logs and debugging — where the logs live when you need the raw detail.
Last verified 2026-10-20