Vscode Self Test

Use this skill when you need to verify a VS Code extension feature in packages/kilo-vscode/ from the real UI.

All interactions use one CLI command. Do NOT call mcp.mjs, daemon.mjs, or engine-mcp.mjs directly — those are internal. Do NOT call the daemon HTTP API with curl — the CLI handles auth and routing internally.

Every command below is shorthand for:

node ~/.config/kilo/scripts/vscode-self-test/cli.mjs <command> [options]

Run from any directory inside the kilocode repo or worktree. The scripts auto-detect the repo root. Before first use, copy recipes/kilo/vscode-self-test.config.json from the shared harness repository into the kilocode repo root as vscode-self-test.config.json.

Every command outputs JSON to stdout.

Session isolation

Every operational command requires a session selector. The optional Kilo plugin at ~/.config/kilo/plugins/vscode-self-test.ts supplies KILO_SELF_TEST_SESSION from the current shell tool session, including a separate ID for each Task child. Restart the calling Kilo backend after installing the plugin. An existing agent can use an explicit selector until then.

For a manual run or an agent without the plugin, choose one unique ID for the complete test and pass it on every command:

node ~/.config/kilo/scripts/vscode-self-test/cli.mjs start --session my-unique-test
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs launch-vscode --session my-unique-test --mode dev --build false
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs status --session my-unique-test

Selection order is --session, then KILO_SELF_TEST_SESSION, then SELF_TEST_SESSION. Reuse the selector for all interactions and cleanup. Do not generate a new ID for each command, use another agent's selector, or rely on a shell export from a previous tool call. Missing selectors fail instead of reconnecting to a worktree-wide daemon. For text beginning with --, use an attached value, for example type --value=--session=example.

Each worktree/session pair owns a daemon, VS Code profile, backend storage, and active profile capture. Source files and build outputs remain shared. Build once before parallel tests and use --build false for all agents; do not rebuild during those runs. Give tests that modify .kilo/agent-manager.json, Git state, or workspace files separate disposable fixture workspaces via --workspace. Run performance comparisons one at a time.

Keep generated user directories, or give each agent a different --user-dir. Explicit user directories are retained during cleanup. Explicit screenshot and profile output paths must also differ between sessions.

For persistence tests, create a unique disposable --user-dir before the first launch and pass the same directory and session selector on every relaunch. Default generated profiles are fresh on each launch. Remove the explicit test directory only after the owning instance has stopped; the harness retains it even with --cleanup true.

Build first

Build the extension before testing when your changes affect the packaged extension, webview code, commands, or startup behavior.

Use the repo's normal build flow for packages/kilo-vscode/, then start or restart the self-test stack if needed.

Start the stack

node ~/.config/kilo/scripts/vscode-self-test/cli.mjs start
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs launch-vscode --mode dev --build true
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs status

To stop:

node ~/.config/kilo/scripts/vscode-self-test/cli.mjs stop-vscode
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs stop

If VS Code is not in a standard macOS install location, pass --app-path /path/to/Code or set VSCODE_EXEC_PATH. The code shell command is only required for vsix mode.

Test an arbitrary extension feature

Use this loop for sidebar chat, settings, editor webviews, commands, and Agent Manager:

1. Build when source changed, then launch isolated VS Code.
2. Open the relevant surface and capture its returned frame.match when available.
3. Run observe --frame "$FRAME", read the screenshot, and inspect the text snapshot.
4. Interact through stable --selector or --text locators. Use hover for tooltip or hover-only UI and click --button right for context menus.
5. Verify the result with wait, snapshot, observe, or a focused evaluate DOM query.
6. Check console --type error and logs when behavior is unclear.
7. For persistence behavior, restart isolated VS Code and verify again.
8. Finish with stop-vscode --cleanup true, then stop.

If a feature has no opener, run the command or click the UI that opens it, then use frames, snapshot, and structural DOM queries to identify the correct webview.

Command reference

Lifecycle

start                                          # Start this agent session's daemon
stop                                           # Stop daemon and VS Code
status                                         # Check daemon and session status
launch-vscode [--mode dev|vsix] [--build true|false] [--headless true|false] [--workspace PATH]
stop-vscode [--cleanup true|false]

Pass --headless true to launch VS Code with its windows hidden while keeping the renderer available to Playwright. This is useful for automated runs. Electron still needs a display server on Linux, so use Xvfb in displayless CI environments.

Observe (screenshots saved to disk, path in JSON output at structuredContent.path)

screenshot [--path FILE] [--selector CSS] [--text TEXT] [--frame MATCH]
observe [--path FILE] [--selector CSS] [--text TEXT] [--frame MATCH]  # screenshot + text
snapshot [--frame MATCH]                       # text only
state                                          # session metadata + text
frames                                         # list Playwright frames

Interact

ALWAYS use --selector or --text for clicking. These use Playwright's element matching, which is accurate regardless of window size or layout. NEVER guess pixel coordinates (--x/--y) — they break across machines and screen sizes. Coordinates are a last resort when no selector or text match exists.

click --text "Models"                          # Good: Playwright finds the element
click --selector '[aria-label="Send"]'         # Good: CSS selector
click --selector '.item' --button right        # Context menu
click --x 448 --y 145                          # BAD: fragile pixel guessing
hover --selector '[aria-label="Help"]'         # Tooltip or hover-only control

type --value TEXT [--selector CSS | --text TEXT] [--clear] [--submit]
press --keys SHORTCUT                          # e.g. Enter, Meta+Shift+P
wait [--selector CSS | --text TEXT] [--state visible|hidden|attached|detached]
scroll [--delta-x N] [--delta-y N]
move --x N --y N

When --text doesn't match (e.g. webview content in iframes), use --frame MATCH to target the right frame. Run frames first to discover available frames.

Webview frame targeting (critical)

VS Code extension UI lives inside nested iframes. Clicks, text lookups, selectors, DOM queries, and CPU profiling on the outer VS Code page will NOT reliably reach webview content. You MUST target the correct frame.

The CLI resolves --frame MATCH with a first-match substring search over frame names and URLs. A broad match can silently select the wrong frame when multiple Kilo surfaces are open.

Frame taxonomy

Agent Manager is the important exception. When the sidebar and Agent Manager are both open, --frame "kilocode.kilo-code" often reaches the sidebar instead of Agent Manager. For Agent Manager interaction and profiling, use the exact fake.html?id=<uuid> match returned by open-agent-manager.

The fake.html frame is VS Code's generated inner webview frame, not a page you inject manually. open-agent-manager already disambiguates it structurally by finding a frame that contains .am-layout [data-sidebar-id="local"]. It returns frame.match, frame.name, and frame.url in JSON without depending on translated UI text. Use frame.match: multiple inner frames may share a non-unique name such as pending-frame.

Recommended Agent Manager opener

st() { node ~/.config/kilo/scripts/vscode-self-test/cli.mjs "$@"; }

OPEN="$(st open-agent-manager --wait-ms 5000)"
printf '%s\n' "$OPEN"
AM="$(printf '%s' "$OPEN" | jq -r '.structuredContent.frame.match')"

# Confirm that this is Agent Manager, not the sidebar.
st observe --frame "$AM" --max-chars 3000

If jq is unavailable, run st open-agent-manager, copy structuredContent.frame.match, and pass it manually. Do not use frame.name when it is pending-frame.

Manual frame discovery and debugging

# List every frame after opening Kilo or Agent Manager.
st frames

# Observe a candidate Agent Manager inner frame.
st observe --frame "fake.html?id=<unique-prefix>" --max-chars 3000

# Inspect candidate body text without a screenshot.
st snapshot --frame "fake.html?id=<unique-prefix>" --max-chars 3000

Use a short unique fake.html?id=<prefix> match only after checking frames. If multiple fake.html frames exist, do not use plain --frame "fake.html"; inspect candidates and select the one where evaluate --script 'return !!document.querySelector(".am-layout [data-sidebar-id=local]")' returns true.

Rules:

• After any quick opener (open-kilo, open-agent-manager, open-kilo-settings), run frames or use the exact frame.match returned by open-agent-manager
• Use --frame "kilocode.kilo-code" for sidebar/settings UI only when it cannot be confused with Agent Manager
• Use the exact Agent Manager fake.html?id=<uuid> match for all Agent Manager click, type, wait, observe, snapshot, evaluate, and profile-start commands
• Use snapshot instead of observe for lightweight polling when you do not need a screenshot
• NEVER use --x/--y coordinates to click webview elements; iframe offsets and window layout make them unreliable

Quick openers

open-kilo                                      # Focus Kilo sidebar
open-agent-manager                             # Open Agent Manager tab
open-kilo-settings                             # Open Kilo settings panel

Debug

console [--type error|warning|log]             # Browser/webview console messages
logs [--filter TEXT]                            # VS Code log files
evaluate --script JS [--frame MATCH]           # Run JS in VS Code page
run-command --command TEXT                      # Command palette command

Performance profiling

Use profiling only after the relevant webview has loaded, so initialization noise does not dominate the capture. profile-start records a global Chrome trace from VS Code's top-level CDP session, plus JavaScript CPU and metrics data from the selected frame's nearest attachable Chromium renderer target. For VS Code webviews this is usually the frame's enclosing webview target; the requested inner frame is retained for semantic marks.

profile-start [--frame MATCH] [--trace true|false] [--cpu true|false] [--interval MICROSECONDS]
profile-stop [--dir DIR] [--trace-path FILE] [--cpu-path FILE] [--metadata-path FILE]
profile-analyze [--dir DIR | --metadata FILE | --trace FILE] [--cpu FILE] [--path REPORT] [--limit N]

Artifacts created by profile-stop --dir DIR:

• DIR/trace.json - Chrome performance trace importable into DevTools or Perfetto
• DIR/profile.cpuprofile - JavaScript CPU profile importable into DevTools
• DIR/metadata.json - target frame, trace-loss status, and Chromium metric deltas

profile-analyze reads metadata.json as the artifact manifest when --dir is used, or accepts a custom manifest with --metadata FILE. It prints a compact JSON report containing capture metadata, trace-loss warnings, long tasks, dominant trace event slices, Kilo performance marks, and the top JavaScript self-time locations. Incomplete or missing declared artifacts fail analysis instead of mixing prior output. Custom --trace-path, --cpu-path, and --metadata-path output files must be distinct; analyze custom metadata captures with --metadata FILE. Add semantic marks during a scenario with evaluate --frame MATCH --script 'performance.mark("kilo.<name>")'; marks beginning with kilo. are included in the report.

Follow the loop

Use a tight observe -> act -> verify loop.

1. Open the right surface with a quick opener
2. For sidebar/settings, use frames and a kilocode.kilo-code match; for Agent Manager, capture the exact fake.html?id=<uuid> frame.match returned by open-agent-manager
3. Run observe --frame "$FRAME" to capture a screenshot path and text snapshot
4. Read the screenshot file with your Read tool to visually see what's on screen
5. Use the text snapshot and screenshot to identify the right --text or --selector for your click
6. Run click --text "Label" --frame "$FRAME"; always use text/selector, never coordinates
7. Take a screenshot after the change and read it to verify
8. Use console or logs if behavior is unclear

The screenshot path is in the JSON output at structuredContent.path. You MUST read the PNG file to see it — just having the path is not enough.

If a click doesn't work, check:

• Did you pass --frame? Without it, Playwright searches the outer VS Code chrome, not the webview.
• For sidebar/settings, run observe --frame "kilocode.kilo-code"; for Agent Manager, use its exact returned frame.match.
• If multiple Kilo frames exist, try observe --frame <name> on each one and use structural DOM checks to identify Agent Manager.

Reuse proven selectors

Shared surfaces

• Kilo activity bar icon: a[aria-label="Kilo Code (NEW)"]
• Agent Manager opener: a[aria-label*="Agent Manager"]
• Agent Manager textarea: textarea[placeholder*="Type a message"]
• Send button: [aria-label="Send"]

Settings

Prefer locale-independent data-value selectors for settings navigation. Other tab keys include agentBehaviour, autoApprove, browser, checkpoints, display, autocomplete, notifications, context, indexing, experimental, language, and aboutKiloCode.

Agent Manager

The local workspace ID is always the literal string local. Managed worktree IDs usually start with wt-. Discover actual IDs from the live DOM rather than guessing:

st evaluate --frame "$AM" --max-chars 30000 --script '
  return [...document.querySelectorAll("[data-sidebar-id]")].map((el) => ({
    id: el.getAttribute("data-sidebar-id"),
    text: (el.innerText || el.textContent || "").trim().replace(/\\s+/g, " ").slice(0, 260),
  }))
'

Use selectors and discovered IDs rather than title text when replaying a performance scenario. Titles can change; data-sidebar-id is stable for the current Agent Manager state.

Worktree switching and transcript-tab switching are different scenarios:

• Use [data-sidebar-id="wt-..."] to select a managed worktree card.
• Use [data-tab-id="ses_..."] to switch transcript tabs inside the already selected worktree.
• Use [data-sidebar-id="ses_..."] only for unassigned session cards shown directly in the sidebar.

VS Code dialogs and notifications

VS Code workspace-trust dialogs, onboarding, command palette, and notification toasts live in the outer workbench, not inside a Kilo webview. Omit --frame for these controls.

# Inspect outer workbench text and screenshot.
st observe --max-chars 3000

# Examples: use visible text or inspect DOM before clicking.
st click --text "Trust" --exact
st click --selector '.notification-toast button' --nth 0

open-kilo, open-kilo-settings, and open-agent-manager automatically close the VS Code welcome overlay. For unfamiliar dialogs, observe first; do not guess coordinates.

Debug deliberately

If the UI does not react as expected, do not guess.

node ~/.config/kilo/scripts/vscode-self-test/cli.mjs console
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs logs
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs evaluate --script "document.title"
node ~/.config/kilo/scripts/vscode-self-test/cli.mjs frames

When behavior is flaky, take screenshots before and after each step.

Exercise Kilo sidebar chat

st() { node ~/.config/kilo/scripts/vscode-self-test/cli.mjs "$@"; }
OPEN="$(st open-kilo --wait-ms 3000)"
SIDEBAR="$(printf '%s' "$OPEN" | jq -r '.structuredContent.frame.match')"

st observe --frame "$SIDEBAR" --max-chars 3000
st type --frame "$SIDEBAR" --selector 'textarea[placeholder*="Type a message"]' --value "hello world"
st click --frame "$SIDEBAR" --selector '[aria-label="Send"]'
st wait --frame "$SIDEBAR" --text "response" --state visible --timeout-ms 30000
st observe --frame "$SIDEBAR" --max-chars 5000
st console --type error

Use a deterministic prompt only when explicitly testing message submission. For non-mutating UI checks, stop after observe and inspect existing UI.

Exercise Agent Manager

Proven recipe:

st() { node ~/.config/kilo/scripts/vscode-self-test/cli.mjs "$@"; }
OPEN="$(st open-agent-manager --wait-ms 5000)"
AM="$(printf '%s' "$OPEN" | jq -r '.structuredContent.frame.match')"

st observe --frame "$AM" --max-chars 3000
st click --frame "$AM" --selector 'textarea[placeholder*="Type a message"]'
st type --frame "$AM" --selector 'textarea[placeholder*="Type a message"]' --value "hello world"
st click --frame "$AM" --selector '[aria-label="Send"]'
st wait --frame "$AM" --text "response" --state visible
st screenshot --frame "$AM"

Do not send prompts during read-only profiling runs. This recipe is for explicit interactive E2E tests only.

Agent Manager performance profiling playbook

Use this workflow when profiling Agent Manager switching, transcript rendering, inline review, full-screen review, or tool-card rendering. Do not automate the visible Webview Developer Tools UI. The CLI records the same Chromium profiling data directly through CDP and preserves the raw artifacts for later DevTools or Perfetto inspection.

Profiling architecture

profile-start --frame "$AM" records two complementary sources:

The requested Agent Manager fake.html?id=<uuid> inner frame is often not directly attachable. The profiler automatically climbs to its nearest attachable ancestor renderer. metadata.json records this as target.scope: "ancestor-frame", which is expected for Agent Manager.

Every profile automatically includes:

• kilo.profile.start
• kilo.profile.stop

Add scenario-specific marks between them:

Standard setup

st() { node ~/.config/kilo/scripts/vscode-self-test/cli.mjs "$@"; }
WORKSPACE="/path/to/workspace"
OUT="$(mktemp -d "${TMPDIR:-/tmp}/kilo-agent-manager-profile.XXXXXX")"

st start
st launch-vscode --mode dev --build false --workspace "$WORKSPACE" --wait-ms 5000
OPEN="$(st open-agent-manager --wait-ms 5000)"
AM="$(printf '%s' "$OPEN" | jq -r '.structuredContent.frame.match')"
st observe --frame "$AM" --max-chars 3000

Build first with bun run compile from packages/kilo-vscode/ if source changed. Use --build false only when the current dist/ bundle is already correct.

Discover stable worktree/session IDs

Do not guess selectors or use card title text for replay. Query the live Agent Manager DOM:

st evaluate --frame "$AM" --max-chars 30000 --script '
  return [...document.querySelectorAll("[data-sidebar-id]")].map((el) => ({
    id: el.getAttribute("data-sidebar-id"),
    text: (el.innerText || el.textContent || "").trim().replace(/\\s+/g, " ").slice(0, 260),
  }))
'

If historical sidebar groups are collapsed, expand them in the current test state:

st evaluate --frame "$AM" --script '
  for (const el of document.querySelectorAll(".am-section-group-header")) {
    if (el.querySelector(".am-section-group-chevron-collapsed")) el.click()
  }
  return true
'

Use a light source ID and one or more heavy target IDs. Always replay the same source-target pair for before/after comparisons.

Warm-up before measuring

Separate cold and warm scenarios:

• Cold activation includes extension/webview initialization, first message hydration, initial postMessage handling, and first DOM creation.
• Warm activation measures repeated session switching after the panel and target session have loaded once. This is usually the best regression benchmark for user-visible switching.

Warm-up sequence:

SOURCE='wt-<light-source-id>'
TARGET='wt-<heavy-target-id>'

st click --frame "$AM" --selector "[data-sidebar-id=\"$TARGET\"]" --wait-ms 1000
sleep 2
st click --frame "$AM" --selector "[data-sidebar-id=\"$SOURCE\"]" --wait-ms 1000
sleep 2

Discard warm-up output. Start profiling only after the target was visited once.

Capture transcript-only session switching

Keep inline diff closed unless diff opening is explicitly part of the scenario:

SOURCE='wt-<light-source-id>'
TARGET='wt-<heavy-target-id>'
OUT="$(mktemp -d "${TMPDIR%/}/kilo-switch-heavy-warm.XXXXXX")"

# Require the visible chat transcript surface and close inline diff if it is open.
st evaluate --frame "$AM" --script '
  if (document.querySelector(".am-review-layout")) throw new Error("Full-screen review is active; return to a transcript tab before profiling")
  if (document.querySelector(".am-terminal-layer-active")) throw new Error("Terminal tab is active; return to a transcript tab before profiling")
  if (!document.querySelector(".message-list")) throw new Error("Transcript pane not found")
  const btn = document.querySelector(".am-diff-toggle-btn.am-tab-diff-btn-active")
  if (btn) btn.click()
  return true
'

st click --frame "$AM" --selector "[data-sidebar-id=\"$SOURCE\"]" --wait-ms 1000
sleep 2
st evaluate --frame "$AM" --script "
  if (document.querySelector('.am-review-layout')) throw new Error('Full-screen review restored for source; return to a transcript tab')
  if (document.querySelector('.am-terminal-layer-active')) throw new Error('Terminal restored for source; return to a transcript tab')
  if (!document.querySelector('[data-sidebar-id=\"$SOURCE\"].am-worktree-item-active')) throw new Error('Expected source worktree is not active')
  const btn = document.querySelector('.am-diff-toggle-btn.am-tab-diff-btn-active')
  if (btn) btn.click()
  return true
"
st profile-start --frame "$AM" --interval 100
st evaluate --frame "$AM" --script "
  performance.clearMarks()
  performance.mark('kilo.switch.begin')
  const target = document.querySelector('[data-sidebar-id=\"$TARGET\"]')
  if (!target) throw new Error('Target worktree card not found')
  target.click()
  return performance.now()
"
sleep 3
st evaluate --frame "$AM" --script "
  if (document.querySelector('.am-review-layout')) throw new Error('Full-screen review restored for target; transcript-only capture is invalid')
  if (document.querySelector('.am-terminal-layer-active')) throw new Error('Terminal restored for target; transcript-only capture is invalid')
  if (document.querySelector('.am-diff-panel-wrapper')) throw new Error('Inline diff panel opened during transcript-only capture')
  if (!document.querySelector('[data-sidebar-id=\"$TARGET\"].am-worktree-item-active')) throw new Error('Expected target worktree is not active')
  performance.mark('kilo.switch.settled')
  return performance.now()
"
st profile-stop --dir "$OUT"
st profile-analyze --dir "$OUT" --path "$OUT/report.json" --limit 20

Use shell sleep between CLI calls for deterministic waits. Do not return a Promise from evaluate: scripts execute in a synchronous function wrapper, so asynchronous return values are not awaited.

Capture inline diff opening separately

Do not mix transcript activation and inline diff rendering unless you add distinct marks and intentionally analyze both segments.

OUT="$(mktemp -d "${TMPDIR%/}/kilo-inline-diff-heavy.XXXXXX")"

st evaluate --frame "$AM" --script '
  const btn = document.querySelector(".am-diff-toggle-btn.am-tab-diff-btn-active")
  if (btn) btn.click()
  return true
'
st click --frame "$AM" --selector "[data-sidebar-id=\"$TARGET\"]" --wait-ms 1000
sleep 2
st evaluate --frame "$AM" --script "
  if (document.querySelector('.am-review-layout')) throw new Error('Full-screen review restored for target; inline-diff capture is invalid')
  if (document.querySelector('.am-terminal-layer-active')) throw new Error('Terminal restored for target; return to a transcript tab')
  if (!document.querySelector('[data-sidebar-id=\"$TARGET\"].am-worktree-item-active')) throw new Error('Expected target worktree is not active')
  return true
"
st profile-start --frame "$AM" --interval 100
st evaluate --frame "$AM" --script '
  performance.clearMarks()
  performance.mark("kilo.diff.open")
  const btn = document.querySelector(".am-diff-toggle-btn:not(.am-tab-diff-btn-active)")
  if (!btn) throw new Error("Closed inline diff toggle not found")
  btn.click()
  return performance.now()
'
sleep 4
st evaluate --frame "$AM" --script '
  performance.mark("kilo.diff.settled")
  const open = document.querySelectorAll(".am-diff-panel-wrapper").length
  if (open !== 1) throw new Error(`Expected one inline diff panel, found ${open}`)
  return {
    open,
    elements: document.querySelectorAll("*").length,
  }
'
st profile-stop --dir "$OUT"
st profile-analyze --dir "$OUT" --path "$OUT/report.json" --limit 20

Inline diff state selectors:

• Closed: .am-diff-toggle-btn:not(.am-tab-diff-btn-active)
• Open toggle: .am-diff-toggle-btn.am-tab-diff-btn-active
• Open panel wrapper: .am-diff-panel-wrapper
• Open panel body: .am-diff-panel

Inventory settled transcript DOM

CPU traces explain where time is spent. DOM inventory explains why. Run this after selecting a target session:

st evaluate --frame "$AM" --max-chars 12000 --script '
  return {
    elements: document.querySelectorAll("*").length,
    wrappers: document.querySelectorAll("[data-component=tool-part-wrapper]").length,
    collapsibles: document.querySelectorAll(".tool-collapsible").length,
    bashBodies: document.querySelectorAll("[data-component=bash-output]").length,
    collapsedBashBodies: [...document.querySelectorAll("[data-component=bash-output]")].filter((body) =>
      body.closest(".tool-collapsible")?.querySelector("[data-slot=collapsible-trigger]")?.getAttribute("aria-expanded") === "false"
    ).length,
    openTools: document.querySelectorAll("[data-slot=collapsible-trigger][aria-expanded=true]").length,
    closedTools: document.querySelectorAll("[data-slot=collapsible-trigger][aria-expanded=false]").length,
    editTools: document.querySelectorAll("[data-component=edit-tool]").length,
    writeTools: document.querySelectorAll("[data-component=write-tool]").length,
    patchTools: document.querySelectorAll("[data-component=apply-patch-tool]").length,
    timelineBars: document.querySelectorAll(".task-timeline-bar").length,
    inlineEditBodies: document.querySelectorAll("[data-component=edit-content]").length,
  }
'

Interpret transient capture.metricsDelta.Nodes separately from settled elements:

• High Nodes with modest settled elements means mount-then-discard work.
• High settled elements means retained DOM remains expensive after the interaction.
• High .task-timeline-bar counts point to timeline overhead.
• High collapsedBashBodies counts point to retained hidden bash-output DOM.
• Pierre/Shiki hot paths such as applyHunksToDOM or findNextMatchSync point to inline diff rendering.

Metadata-guarded profiling of a real checkout

Opening Agent Manager can normalize its ignored .kilo/agent-manager.json. Initialization can also touch .git/info/exclude and legacy .git/worktrees/*/gitdir refs. When the main checkout metadata must remain byte-identical, launch against a disposable shadow workspace and compare an automatic before/after snapshot.

st() { node ~/.config/kilo/scripts/vscode-self-test/cli.mjs "$@"; }
REAL="${KILO_REPO_PATH:-$HOME/Documents/git/kilocode}"
TMP="${TMPDIR%/}/kilo"
mkdir -p "$TMP"
SHADOW="$(mktemp -d "$TMP/kilocode-main-profile-shadow.XXXXXX")"
BEFORE="$(mktemp "$TMP/kilocode-real-state.before.XXXXXX")"
AFTER="$(mktemp "$TMP/kilocode-real-state.after.XXXXXX")"

snapshot_real() {
  shasum -a 256 "$REAL/.kilo/agent-manager.json" "$REAL/.git/info/exclude"
  if test -d "$REAL/.git/worktrees"; then
    for file in "$REAL"/.git/worktrees/*/gitdir; do
      test -f "$file" && shasum -a 256 "$file"
    done
  fi
  git -C "$REAL" status --short --branch
  git -C "$REAL" worktree list --porcelain
  while IFS= read -r dir; do
    test -n "$dir" || continue
    printf '### worktree %s\n' "$dir"
    git -C "$dir" status --porcelain=v1 --untracked-files=all
  done <<EOF
$(git -C "$REAL" worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print }')
EOF
}

# Snapshot real metadata and worktree status before launch.
snapshot_real > "$BEFORE"

# Copy metadata instead of symlinking it. Agent Manager initialization may call
# ensureGitExclude() and legacy worktree-ref migration; these writes stay in temp.
mkdir "$SHADOW/.kilo"
cp -R "$REAL/.git" "$SHADOW/.git"
cp "$REAL/.kilo/agent-manager.json" "$SHADOW/.kilo/agent-manager.json"

# Disable GitHub auth noise for the isolated daemon, then launch against shadow state.
st stop || true
GH_TOKEN=invalid GITHUB_TOKEN=invalid st start
st launch-vscode --mode dev --build false --workspace "$SHADOW" --wait-ms 6000
OPEN="$(st open-agent-manager --wait-ms 6000)"
AM="$(printf '%s' "$OPEN" | jq -r '.structuredContent.frame.match')"

Important protection boundary:

• The shadow copy protects main-checkout Agent Manager metadata and Git metadata from initialization writes.
• The shadow recipe is for profiling existing managed worktree cards. The copied Agent Manager state still references their real absolute directories, so this is not a sandbox for managed worktree content.
• The shadow local card is not a faithful rendering of the real checkout because the shadow directory does not contain source files.
• Copy .git; do not symlink it when byte-identical main-checkout metadata is required. Agent Manager initialization can update info/exclude, and legacy migration can rewrite .git/worktrees/*/gitdir refs.
• During a metadata-guarded run, only select existing cards, inspect DOM, and record profiles. Do not send prompts, edit files, create worktrees, apply changes, run commands, or open mutating actions.
• For a fully sandboxed benchmark where worktree contents may be exercised freely, use a disposable fixture repository instead of a real checkout.

Cleanup and automatic verification:

st stop-vscode --cleanup true
st stop
case "$SHADOW" in
  "$TMP"/kilocode-main-profile-shadow.*) rm -rf -- "$SHADOW" ;;
  *) printf 'Refusing to remove unexpected shadow path: %s\n' "$SHADOW" >&2; exit 1 ;;
esac
snapshot_real > "$AFTER"
if ! cmp -s "$BEFORE" "$AFTER"; then
  diff -u "$BEFORE" "$AFTER" || true
  printf 'Real checkout changed during profiling; investigate before continuing.\n' >&2
  exit 1
fi
rm -f -- "$BEFORE" "$AFTER"

Analyze artifacts

Each profile-stop --dir "$OUT" creates:

trace.json
profile.cpuprofile
metadata.json

Each profile-analyze --dir "$OUT" --path "$OUT/report.json" adds:

report.json

Use the report for first-pass analysis, then open raw artifacts manually only if deeper flame-chart inspection is useful.

Keep raw artifacts and record the exact scenario, source ID, target ID, waits, panel state, and DOM inventory alongside before/after numbers.

Common mistakes

Cleanup and stale daemon recovery

Always close VS Code before stopping the daemon:

st stop-vscode --cleanup true
st stop

stop-vscode --cleanup true removes the generated runtime directories owned by the selected session. Explicit user directories are retained. stop terminates only that session's daemon. Discovery and ownership state live at ~/.config/vscode-extension-self-test/state/<repo-hash>/<session-hash>/; SELF_TEST_STATE_DIR replaces the base, with both hashes appended.

After a hard crash, inspect that session's owner.json and confirm all owned processes have exited before removing its stale lock and discovery state. Do not take over a lock because a status request times out. Old worktree-wide daemons are not adopted automatically. Confirm ownership before stopping an old process; never remove all harness state or use broad process-name kills.

Before/after optimization loop

1. Build the extension if needed.
2. Launch the same workspace and identify the exact Agent Manager frame.
3. Discover stable source and target IDs.
4. Warm the target once for warm-switch benchmarking.
5. Capture a short baseline with semantic marks.
6. Save raw artifacts and settled DOM inventory.
7. Make one minimal behavior-preserving optimization.
8. Rebuild the extension.
9. Replay the identical source, target, waits, and panel state.
10. Compare longest task, script duration, style recalculation, layout, transient nodes, settled DOM, and CPU hot paths.
11. Verify user-visible behavior manually, including explicit expansion or fast scrolling when relevant.

Do not claim an improvement from code inspection alone. Re-profile the exact scenario.

Exercise Kilo settings

st() { node ~/.config/kilo/

…(truncated)