Omniscio

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.totalSelfSize is what to compare against the OS reported renderer RSS. It's the sum of every node's self_size in bytes — close to JS-reachable memory, not counting V8 internals or native buffers.
  • byNodeType is your first triage cut. If string dominates, you're looking at retained text/base64/buffers; if object dominates, you're looking at retained DOM or app objects; if code dominates, you have many compiled functions resident (rare).
  • topClassNames (capped at 25 by totalSelfSize) names the worst object retainers. Names are pulled from the V8 strings table for non-string-type nodes — for plain objects this is the constructor name (HTMLDivElement, Map, custom classes, etc.).
  • largeStrings isolates the >1 KB string nodes and splits them into dataImage (base64-encoded data:image/...), dataOther (other data: URLs — Office docs, blobs), and generic (everything else — long JSON blobs, pasted text, agent message buffers). The 10 largest are returned as samples with truncated previews so you can sanity-check what's pinned.

Optional behavior

  • ?keep=true — the captured .heapsnapshot file is normally deleted after parsing to save disk. With keep=true, the response includes snapshotPath so 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 concurrent takeHeapSnapshot calls 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>.heapsnapshot and deleted unless keep=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.parse object 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 concurrent takeHeapSnapshot calls would still double the capture-side pressure.
  • Strings-section parse cost: a strings entry 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 of strings JSON, 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 in tests/unit/services/heap-snapshot-parser-streaming.test.ts.
  • Main-process target costs a freeze, not just time: ?target=main snapshots this process with v8.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. Same keep=true semantics, same retention (newest three kept).
  • Main-process summary cap: above 512 MB the summary is skipped and the response says so in summarySkipped, with summary: 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 without keep=true (the response carries snapshotPath, 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-token is required. That is stricter than /projects, /sessions and 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 byNodeType first, then drill into topClassNames or largeStrings.samples based 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.dataImage and topClassNames deltas.
  • "I want to verify a memory fix actually freed memory." Capture before and after — totals.totalSelfSize and 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 and mempalace-server are separate processes and out of scope.
  • Don't ship code that depends on the response shape long-term — the summary shape is a debug aid and may evolve as the parser learns to extract more useful signals.

Last verified 2026-10-20