From 458757b6a4d04cfb7f01f3213e8d4da48d979185 Mon Sep 17 00:00:00 2001
From: "kiloconnect[bot]" <240665456+kiloconnect[bot]@users.noreply.github.com>
Date: Thu, 16 Apr 2026 13:03:59 +0000
Subject: [PATCH] docs(kilo-docs): add Take Heap Snapshot command documentation

Document the "Kilo Code: Take Heap Snapshot" VS Code command in the
troubleshooting section, covering usage, snapshot analysis, and
memory issue reporting.
---
 packages/kilo-docs/lib/nav/getting-started.ts |  5 ++
 .../troubleshooting/heap-snapshot.md          | 47 +++++++++++++++++++
 .../getting-started/troubleshooting/index.md  |  1 +
 3 files changed, 53 insertions(+)
 create mode 100644 packages/kilo-docs/pages/getting-started/troubleshooting/heap-snapshot.md

diff --git a/packages/kilo-docs/lib/nav/getting-started.ts b/packages/kilo-docs/lib/nav/getting-started.ts
index 45d16d25fcc..5052539d9e7 100644
--- a/packages/kilo-docs/lib/nav/getting-started.ts
+++ b/packages/kilo-docs/lib/nav/getting-started.ts
@@ -68,6 +68,11 @@ export const GettingStartedNav: NavSection[] = [
             href: "/getting-started/troubleshooting/troubleshooting-extension",
             children: "Extension Troubleshooting",
           },
+          {
+            href: "/getting-started/troubleshooting/heap-snapshot",
+            children: "Heap Snapshot",
+            platform: "new",
+          },
         ],
       },
       {
diff --git a/packages/kilo-docs/pages/getting-started/troubleshooting/heap-snapshot.md b/packages/kilo-docs/pages/getting-started/troubleshooting/heap-snapshot.md
new file mode 100644
index 00000000000..a5716b7b515
--- /dev/null
+++ b/packages/kilo-docs/pages/getting-started/troubleshooting/heap-snapshot.md
@@ -0,0 +1,47 @@
+---
+title: "Heap Snapshot"
+description: "How to capture a heap snapshot for diagnosing memory issues in Kilo Code"
+platform: new
+---
+
+# Heap Snapshot
+
+If Kilo Code is consuming excessive memory or becoming unresponsive, capturing a heap snapshot helps the team diagnose the issue. A heap snapshot records every object in memory at a single point in time and can be loaded in Chrome DevTools for analysis.
+
+## Taking a Heap Snapshot in VS Code
+
+1. **Open the Command Palette**: Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS)
+2. **Run the command**: Type `Kilo Code: Take Heap Snapshot` and select it
+3. **Wait for confirmation**: A notification will appear with the file path where the snapshot was saved
+
+The snapshot is written to the Kilo log directory as a `.heapsnapshot` file. The filename includes the process ID and timestamp, for example:
+
+```
+heap-12345-20260416T125800000Z.heapsnapshot
+```
+
+{% callout type="info" %}
+The command captures a snapshot of the **CLI backend process** (`kilo serve`), not the VS Code extension host. This is where the AI agent runtime, session management, and tool execution happen — and where memory issues most commonly occur.
+{% /callout %}
+
+## Analyzing a Heap Snapshot
+
+You can open the `.heapsnapshot` file in Chrome DevTools:
+
+1. Open Chrome and navigate to `chrome://inspect`
+2. Click **Open dedicated DevTools for Node**
+3. Go to the **Memory** tab
+4. Click **Load** and select the `.heapsnapshot` file
+
+From there you can inspect object allocations, retained sizes, and reference chains to identify memory leaks.
+
+## Reporting a Memory Issue
+
+When reporting a memory issue, include the following with your report:
+
+1. The `.heapsnapshot` file (or a summary of what you found)
+2. Steps to reproduce the high memory usage
+3. Your Kilo Code and VS Code versions
+4. The approximate time the issue started and what you were doing
+
+Send reports to **[hi@kilocode.ai](mailto:hi@kilocode.ai)** or file an issue on [GitHub](https://github.com/Kilo-Org/kilocode).
diff --git a/packages/kilo-docs/pages/getting-started/troubleshooting/index.md b/packages/kilo-docs/pages/getting-started/troubleshooting/index.md
index 2f88f41c9a8..ffc0cd576fd 100644
--- a/packages/kilo-docs/pages/getting-started/troubleshooting/index.md
+++ b/packages/kilo-docs/pages/getting-started/troubleshooting/index.md
@@ -10,3 +10,4 @@ This section contains guides for diagnosing and resolving common issues with Kil
 ## Guides
 
 - [**Extension Troubleshooting**](/docs/getting-started/troubleshooting/troubleshooting-extension) - How to capture console logs and report issues with the Kilo Code extension
+- [**Heap Snapshot**](/docs/getting-started/troubleshooting/heap-snapshot) - How to capture a heap snapshot for diagnosing memory issues