Kopytko VS Code Extension

Navigate your codebase with precision — from go-to-definition on @import paths to workspace-wide call hierarchy and SceneGraph type hierarchy. All navigation respects the @import graph and XML sibling relationships.

Real-time diagnostics powered by the kopytko-linter engine. 32 rules reported as you type, with code actions for auto-fixable issues.

One of them is project-wide rather than per-file: component/duplicate-name warns on both XML files when two of them declare the same SceneGraph component. Component names are global to the channel, so the second declaration silently overrides the first. The editor reports it as you save; kopytko-lint reports it in CI.

The extension embeds the kopytko-formatter engine. Format a file with Shift+Alt+F, or enable format-on-save. All 49 formatting options and casing settings are configurable from .vscode/settings.json.

Automatic SSDP-based discovery keeps your sidebar populated with every Roku device on the network. Device health is verified via ECP on each scan, and the list updates on network change or sleep/wake.

Implements the Roku Socket Debug Protocol 3.3.0 over TCP port 8081. Deploy your channel with Ctrl+Shift+F5, then debug with F5.

• ✓ Static, conditional, and hit-count breakpoints
• ✓ Exception breakpoints (caught and uncaught)
• ✓ Multi-thread inspection: main, render, and task threads
• ✓ Step over / into / out, and pause
• ✓ Typed variable inspection with expandable containers
• ✓ Virtual variables: $children, $parent, $count on roSGNodes
• ✓ Hover-to-evaluate expressions
• ✓ Debug console REPL with EXECUTE command
• ✓ Compile errors surfaced as VS Code diagnostics
• ✓ Program output via IO channel
• ✓ Protocol-state aware: breakpoints toggled while the channel runs are replayed on the next stop, so the device is never sent a command it would answer with a connection reset
• ✓ Wire-level protocol tracing via kopytko.debug.trace for diagnosing dropped sessions

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "brightscript",
      "request": "launch",
      "name": "Debug on Roku",

      // host and password are OPTIONAL.
      // When omitted they are taken from the active device in the sidebar.
      // "host": "192.168.1.100",
      // "password": "rokudev",

      "rootDir": "${workspaceFolder}",

      // env selects a .kopytkorc environment key ("dev", "staging", ...).
      // Optional — taken from the active device's environment selection if omitted.
      // "env": "dev",

      "stopOnEntry": false
    }
  ]
}

A dedicated sidebar container — drag it to the right-hand Secondary Side Bar to keep it next to your code — with two views: Remote Control (the on-screen remote, then three expanded-by-default disclosures: Saved Text entries, Device actions, then a Secret screens reference) and a RASP automation-script library compatible with Roku's official Remote Tool.

• ✓ Remote laid out like a physical Roku remote — click for keypress, hold ≥1 s for keydown/keyup (scrubbing works)
• ✓ Text field types on the device keyboard — ordered, sequential Lit_ keypresses, UTF-8 safe
• ✓ Keyboard remote mode — arrows/Enter/Escape drive the device from anywhere; status-bar indicator, Ctrl+K exits
• ✓ Device actions — expanded by default, labeled rows for web-admin actions: screenshot, upload, package, rekey, software update, restart, delete channel
• ✓ Secret screens — expanded-by-default reference list (not buttons) for 5 Roku key sequences: enable dev mode, channel info, screenshots & ads, reset & update, clear cache; typed on your physical remote
• ✓ Saved Text entries: text and credentials types with a Send button per field; passwords in the OS keychain, never in settings or the webview
• ✓ Custom labels on Saved Text (type doubles as an implicit label) and Scripts, with Filter and Sort-by-label dropdowns
• ✓ RASP script editor tab — live validation, snippet toolbar, per-step run progress with cancel
• ✓ Record remote — button presses and sent text write themselves into the open script editor, like Roku’s own tool
• ✓ Full RASP runner: press, text, pause, launch, loops, reusable blocks, wait_for_player_state, validate_streaming
• ✓ Import/export .rasp files — scripts round-trip with the Roku Remote Tool

A bottom-panel recorder that captures live runtime telemetry from the running channel into replayable per-session NDJSON files, charted live with D3. Every chart and table is individually toggleable — data is only polled while something visible needs it.

• ✓ Memory chart — total/anon/file/shared/swap MB with FG/BG limit lines (chanperf)
• ✓ CPU chart — total/user/sys % (chanperf)
• ✓ SceneGraph Nodes chart — stacked by node type, top 8 + Other (sgnodes counts)
• ✓ Objects chart — BrightScript object counts stacked by type via ECP app-object-counts (hidden by default)
• ✓ Texture memory chart with max reference line (r2d2_bitmaps)
• ✓ Node / Object / Rendezvous / Texture tables — the Objects table splits roSGNode rows per component subtype
• ✓ Rendezvous + framework-beacon markers overlaid on every chart
• ✓ App foreground/background shading + live state badge
• ✓ Record any channel sharing the sideloaded dev key, with past-session replay

A Charles-style HTTP inspector for a running channel — an intercepting proxy the device's traffic is redirected through, showing every request and response grouped by origin and path with per-request metrics. The clever part: it sees HTTPS backends decrypted without installing any CA on the Roku. The device stays on plaintext HTTP, the proxy bridges to HTTPS upstream, and response bodies are rewritten https:// → http:// so the app keeps talking HTTP.

• ✓ Pure-Node proxy — no external tools, no mitmproxy, no certificates
• ✓ One master toggle (off by default): flip on to start the proxy and apply the OS traffic redirect; flip off to fully revert
• ✓ Fully automatic transparent redirect on all three platforms out of the box — a scoped iptables chain (Linux), pf anchor (macOS), or a bundled WinDivert companion (Windows, zero setup) redirecting all of the device's traffic by source IP under one elevated prompt; teardown never touches your other firewall rules and reverts on close/crash, and the Windows companion also self-terminates if VS Code disappears without saying goodbye
• ✓ Live-editable rewrite rules — built-in https→http and wss→ws plus your own find/replace, scoped by host and path, applied without restart
• ✓ Rewrite excludes — opt specific host+path combinations out of ALL rewriting, even the built-ins, for a response that must reach the device byte-for-byte
• ✓ Per-host upstream scheme (https / http / auto); gzip/deflate/br decoded, Set-Cookie Secure stripped, redirects downgraded
• ✓ Requests grouped by origin, detail pane with headers, bodies and original-vs-rewritten view, filter, and Export HAR
• ✓ A detail pane that remembers your place — only Overview opens by default, the sections you expand stay expanded as you step between requests, and the pane scrolls back to the section you were focused on; right-click any key/value row (headers, query params, cookies, JSON-tree nodes) to copy the key, the value, or both — tree nodes copy their whole subtree as JSON
• ✓ Every capture session is saved to a timestamped folder on disk (manifest + flows.ndjson + full body files), so oversized bodies are never shown cut off — a warning links to the complete, formatted body in a new editor tab, and replays of truncated requests send the full on-disk bytes
• ✓ Per-request timing waterfall — blocked / DNS / connect / TLS / send / wait / receive as a stacked bar and table, keep-alive-aware, with the same real phases written to HAR
• ✓ Workflow tools — copy URL / copy as cURL / copy body, one-click replay through the proxy (with confirmation for state-changing methods), pause recording without dropping the redirect, timestamps, and status/method filter chips
• ✓ Map-local, latency-injection, header and block rules (block aborts a matched request so you can test error handling); image response preview + hex; parsed query-param and cookie views; and a search across every captured request that jumps straight to the flow
• ✓ Streaming pass-through — Server-Sent Events and chunked no-length responses forward chunk-by-chunk instead of buffering, so a live stream never hangs the device
• ✓ In-flight rows — a request appears the instant it arrives with a live elapsed-time counter and inspectable request headers, then updates in place when it completes, so long-polls, streams, slow endpoints and breakpoint-paused requests are visible while they run
• ✓ Compare any two captured requests — a line-level diff of summary, headers and bodies to spot exactly what changed between them
• ✓ Breakpoints — pause a matched request or response mid-flight, edit its method/status/headers/body live, then continue or abort (with an auto-continue timeout so nothing hangs)
• ✓ Built to stay fast under load — frame-batched incremental list updates, a dual entry-count + byte-budget memory cap, and pooled upstream connections (no per-request TLS handshake to origins)

The dev machine must be the device's gateway (macOS Internet Sharing, a Linux gateway, or Windows ICS). On 64-bit Windows there's nothing to install — the extension bundles a working WinDivert driver and drives it via an elevated companion process (window hidden, everything logged for auditability). kopytko.network.winDivertDir exists only to override that with a different build, or on architectures the bundled driver doesn't cover — it's machine-scoped, so it can't be pushed onto a team via a shared workspace settings.json.

An interactive terminal for the Roku debug consoles, in its own bottom-panel tab beside Terminal and Problems. It replaces reaching for an external telnet client — which Windows doesn't ship at all — with a real terminal that knows which commands each port accepts and colours the output by severity, so the crash stands out from the wall of log lines. Works identically on Windows, macOS and Linux.

• ✓ Both interactive ports, connected at once — 8085 (BrightScript runtime: live print output, beacons, and the BrightScript Debugger> prompt when execution stops) and 8080 (SceneGraph debug server: chanperf, sgnodes, sgperf, r2d2_bitmaps, free); the dropdown switches the view, not the connection
• ✓ Follows the device you picked in the Roku Devices sidebar — no second device selector to fall out of sync, just the active device and a dot showing the console connection
• ✓ Completion for every documented command with descriptions, argument hints and subcommands — an empty line lists the whole port catalog, so you never have to guess a first letter, and Tab walks sgnodes all|roots|counts, sgperf start|clear|report|stop and the rest with no round-trip to the device
• ✓ Commands seen only in the device's own help output are labelled undocumented, and destructive ones (genkey, remove_plugin) need an explicit confirmation before they are sent
• ✓ Severity colouring drawn from the theme's own terminal palette — errors, warnings, framework beacons, debugger frames and XML replies each read differently, in light, dark and high-contrast alike
• ✓ Clickable pkg:/components/Foo.brs(40) references that open the file at the line, resolving through Kopytko packages in node_modules too
• ✓ Live filter — plain text or /regex/ — plus severity chips, narrowing what you see without touching what is captured
• ✓ Per-port command history, save-buffer-to-file, and optional append-as-it-arrives logging so a crash still leaves a complete record on disk
• ✓ Device output is sanitised before display, so an escape sequence in a print statement can't repaint your terminal

Only the two ports that carry an interactive command surface on current Roku OS are offered — 8089–8093 were retired in Roku OS 7.5+. Port 8085 accepts a single consumer at a time, so the console tells you when another telnet or debug session is holding it rather than retrying in silence; it also replays the channel's log from launch when you connect, and (verified on firmware 15.2.4) only accepts typed commands once execution has stopped at a debugger prompt.

Exercise your channel's deep links without hand-crafting curl commands. An editor-tab panel lists every channel installed on the active device — icons included — and lets you fire a contentId plus any key-value parameters at it via ECP Launch (POST /launch, starts or relaunches the channel) or Input (POST /input, delivered to the running channel as an roInput event — no relaunch).

• ✓ Channel grid with icons from the device (ECP /query/apps + /query/icon)
• ✓ contentId field + free-form key-value parameters, with mediaType value suggestions
• ✓ Launch and Input send modes with clear semantics for each
• ✓ Named parameter sets — save, reuse, edit, and delete; persisted per workspace
• ✓ Custom labels on saved sets, plus Filter (multi-select) and Sort-by-label dropdowns
• ✓ Follows the active device; warns when a preset’s channel is not installed

An editor-tab panel that fetches a live SceneGraph node collection from the active Roku device — All (/query/sgnodes/all), Roots (/query/sgnodes/roots), or UI (/query/app-ui, the rendered tree of the foreground app) — and shows it as a formatted, syntax-colored XML document (default) or a D3 icicle chart.

• ✓ Three node collections: every created node, only un-parented roots, or exactly what the screen is rendering
• ✓ XML view: formatted and colorized, with a right-click Copy XML / Copy Selection menu and a Ctrl/Cmd+F find widget
• ✓ Chart view: click a node to focus its subtree, double-click to go back up, hover for an attribute tooltip
• ✓ The chosen view sticks while you switch collections; Refresh re-queries the device without reopening the tab
• ✓ Edit mode (UI + XML): edit the document in place and push field changes to the running app through an injected RALE TrackerTask — validated as you type, applied with Ctrl+Enter, every target verified before writing

Call Roku Pay's cloud API (apipub.roku.com) from an editor tab — no device needed. Every transaction-service endpoint (validate, cancel, refund, billing cycle, service credit) plus the four subscription-recovery test transitions (in-grace, on-hold, passively cancel, recover), each rendered as a typed form with a live URL preview and a full response viewer.

• ✓ Named credential profiles — the partner API key lives in the OS keychain, never in settings, logs, or the webview
• ✓ Endpoint-driven forms: typed fields (text, number, checkbox, date), required markers, endpoint descriptions and rate-limit warnings
• ✓ Accept header switch — pretty-printed JSON or raw XML responses, with embedded /Date(ms)/ tokens humanized to readable timestamps
• ✓ Full response viewer: status, duration, headers, request and response bodies
• ✓ Persistent request/response history (last 200) with per-entry delete and clear-all — the API key is always masked as ****
• ✓ Subscription-recovery testing per Roku’s guide: walk a test subscription through in-grace → on-hold → cancel → recover