Code Scope

English | Português

A VS Code extension, also for Cursor, Windsurf, VSCodium and Antigravity, and a plugin for IntelliJ IDEA (beta, Java), that shows your code running, visually, for people learning to program. Free and open source (MIT).

Beta. Version 0.7.0 is a beta for people to try and help shape. Install it from the release page, and if something looks wrong or confusing, open an issue: that is the most useful help right now.

Everything happens inside your editor: the panel sits in the sidebar, next to your code, and uses your theme's colors. It opens no browser, needs no account and sends nothing to the internet.

While you debug, a side panel draws your program: arrays, matrices, lists, stacks, queues, dictionaries, objects, linked lists, trees and the call stack. Think of it as someone drawing your program on a whiteboard. It works with Java, JavaScript, TypeScript, Python, C# and C, and with any other language that has a debugger in VS Code (see Languages). On every F10 the panel animates what changed and explains what happened:

• the changed box flashes and stays highlighted;
• a swap shows the two boxes crossing over, even when the code uses a temp variable and takes two steps;
• i, j, inicio and fim become colored arrows that slide under the boxes;
• in a list, a new item appears and the ones after it make room; an item that leaves goes away and its neighbors close the gap;
• in a set (HashSet, Python set, JavaScript Set), boxes have no index, and adding a value that is already there says so: a set keeps no duplicates;
• in a stack, a pushed item drops onto the top of the tower and a popped one rises and fades, with the "top" label following along;
• in a queue, items enter from the right of the conveyor belt and the one in front leaves on the left;
• in a matrix, the row and column the code reads are highlighted and the cell where they cross gets an outline;
• the text says what changed and which path the program took: "numeros[0] and numeros[1] swapped places", "the condition on line 8 was false: the program skipped the if block", "end of one loop iteration";
• before an if or a loop runs, its condition is split into parts, each one marked true or false with the values in place of the names (ordenado[meio] == alvo (17 == 25)), respecting short-circuit;
• when a function calls another one, or itself, the call stack shows one card per call, each with its own variables; the call that finishes leaves saying what it returned;
• objects become cards labeled with the variables that point to them: two names on one card are two variables on the same object, not a copy. Linked lists are drawn as nodes and arrows, binary trees as trees;
• dictionaries (HashMap, dict, JavaScript objects and Map) become a key and value table;
• in searches and sorts, the positions being compared get an outline, the part of the array a search has already discarded fades out, and the panel counts comparisons and swaps;
• when the program crashes, the panel stops at the error and explains it in plain words; an index out of range shows the position that does not exist, dashed, next to the array;
• a trace table fills in step by step, one row per step and one column per variable, like the desk check done on paper;
• a variable that leaves scope stays one step, crossed out, and a block variable that hides another one with the same name is marked;
• when recursion splits in two, like fib(n - 1) + fib(n - 2), a recursion tree shows every call, the value each one returned and how many times the same work was redone;
• a list of objects shows each object inside its position (turma[1] with its name and grade); a dictionary of lists becomes a graph, with the visited nodes, the current one and the queue of a breadth-first search;
• inside a catch, the panel explains which line raised the error and that the rest of the try did not run; when a subclass method runs, it says why it was that version (polymorphism);
• text read letter by letter becomes a row of letters with the index arrow, and the classic number traps are explained when they happen: integer division, 0.1 + 0.2, overflow.
• == versus equals (and is versus == in Python): when a condition compares two objects, the text says whether it asked "same object?" or "same contents?", and explains the classic traps, like == between two equal Java strings, or equals in a class that never wrote one.
• changing in place or creating a new one: x.sort() changes the list itself (and every name for it), sorted(x), slice() or Arrays.copyOf make a new one, and s.trim(); alone on a line creates a text nobody keeps, so s stays the same.
• how much it costs: under the comparison counter, a table puts the program's count next to log n, n, n log n and n², for its own size and for 1000 positions, where a loop inside a loop already makes a million comparisons.

Three extra tools:

• Guess first: before a line runs, the panel asks what the variable will be. After F10 it says if the guess was right and keeps the score.
• Presentation mode: the panel opens large next to the code, with bigger text and slower animations, ready to project or record.
• Save image: the current step becomes a PNG, for slides, notes or to share.

The panel speaks English and Portuguese and follows the language of your VS Code: Portuguese when VS Code is in Portuguese, English otherwise.

Stack	Queue

Matrix	List

Recursion tree	Error explained

Binary search	Graph

List of objects	Binary tree

Panel captures made with data from real debugger sessions (Java, JavaScript and Python), saved with the panel's own "Save image" button.

Languages

Code Scope talks to the debugger through the Debug Adapter Protocol, the protocol VS Code uses with every debugger. Each debugger formats values its own way, so each language has an adapter that translates that text for the panel. Languages without their own adapter use the generic mode.

The flow explanations (if, loops, break) understand the C family (Java, JavaScript, C#, C, Go) and Python. If the panel does not recognize something in your language, open an issue with the log (see below): that is how a new adapter starts.

What the panel shows

Requirements

• VS Code 1.95 or newer
• The debugger for your language:
  • Java: Extension Pack for Java (code --install-extension vscjava.vscode-java-pack) and a JDK
  • JavaScript and TypeScript: Node.js 22 or newer; the debugger ships with VS Code. With Node.js 20 the VS Code debugger (js-debug 1.140) runs the program without stopping at breakpoints
  • Python: the Python extension (code --install-extension ms-python.python), which brings debugpy, and Python installed
  • C#: the C# extension (code --install-extension ms-dotnettools.csharp) and the .NET SDK
  • C: the C/C++ extension (code --install-extension ms-vscode.cpptools), a compiler and gdb (for example MinGW-w64 or w64devkit on Windows)

Install

The extension is not on the VS Code Marketplace yet. Download code-scope.vsix from the beta release and install it:

code --install-extension code-scope.vsix

Or, in VS Code, open the Extensions view, click the ... menu and choose Install from VSIX....

To try the latest commit instead, take the .vsix from the latest CI run (the repository's Actions tab, artifact code-scope-vsix) or build your own:

npm install
npm run vsix
code --install-extension code-scope.vsix

Cursor, Windsurf, VSCodium, Antigravity and other VS Code forks

The same .vsix installs in editors built on VS Code. Use the editor's own command (cursor, windsurf, codium, antigravity) in place of code, or Install from VSIX... in its Extensions view. These editors install extensions from Open VSX instead of the Microsoft Marketplace. Code Scope goes to Open VSX starting with the next release; until then, use the .vsix.

What changes by language:

• Java, JavaScript and Python work as in VS Code. The Java Extension Pack and ms-python.debugpy are on Open VSX, and the JavaScript debugger ships with the editor. CI runs these tests in VSCodium on every push.
• C# and C: Microsoft's C# and C/C++ debuggers only run inside Microsoft's VS Code. In a fork, use an open debugger: for C#, the C# extension by muhammad-sammy (netcoredbg, launch type coreclr); for C, CodeLLDB (launch type lldb). Code Scope listens to both launch types, but these two debuggers are not covered by the tests yet.

IntelliJ IDEA and Android Studio (beta)

Code Scope also runs as a JetBrains plugin, for Java. The panel opens on the right when the debugger stops; step with F8 (Step Over) or F7 (Step Into) as usual.

The plugin is not on the JetBrains Marketplace yet. Build it from the repository (needs Node.js and a JDK 21):

npm install
cd jetbrains
./gradlew buildPlugin

Then, in the IDE: Settings > Plugins > gear icon > Install Plugin from Disk... and pick the .zip in jetbrains/build/distributions. CI also builds it on every push (artifact code-scope-jetbrains).

It needs IntelliJ IDEA 2026.2 or newer (any edition), or an Android Studio built on it. The plugin reuses the code of the VS Code extension: the IDE's Java debugger answers the same questions the VS Code one does, and the panel draws the same thing. PyCharm, WebStorm and the other JetBrains IDEs without Java are not covered yet.

Run from source

git clone https://github.com/celoramos/Code-Scope.git
cd Code-Scope
npm install

Open the folder in VS Code and press F5. The "Rodar extensão" configuration builds the project and opens a second window, the Extension Development Host, with the Java, JavaScript and Python samples already open (samples/exemplos.code-workspace).

While developing, npm run watch rebuilds on every change; reload the test window with Ctrl+R.

Trying the samples

After installing, the quickest way in is Code Scope: Open a sample in the command palette (or the Get started with Code Scope walkthrough in Help > Get Started): it copies the Java, JavaScript or Python samples to a folder you pick and opens it.

In the Extension Development Host window:

1. Open one of the samples and set a breakpoint on the line its comment points to.
2. In the Run and Debug tab, pick the configuration and press F5. In Java, each sample has a configuration with the same name; in JavaScript and Python, use "Arquivo aberto". The Code Scope panel opens by itself on the first stop.
3. Step with F10 (step over) and watch the panel.

With the panel focused: left and right arrows move one step, Home and End jump to the first and last.

If the panel does not show what you expected, open Output, pick Code Scope and set the level to Debug. The channel logs which adapter was used, each snapshot and what the debugger returned.

Settings

Commands in the palette: Code Scope: Show panel, Code Scope: Clear history and Code Scope: Presentation mode.

How it works

language debugger -- "stopped" event --> trackerFactory
                                              |
       stackTrace, scopes, variables  <------ dapCollector (customRequest)
                                              |  the language adapter translates
                                              |  "int[5]@10", "(5) [5, 1, 4]", "[5, 1, 4]"...
                                              v
                   Snapshot { line, code, arrays, pointers, scalars }
                                              |
        History --> diff + explain + flow + arrows --> Frame
                                              | postMessage
                                              v
                             Webview (plain HTML, CSS and JS)

Tests

CI runs both on every push, on Windows, Linux and macOS, plus the integration test on the minimum VS Code (1.95) and on the latest VSCodium (debuggers from Open VSX), builds the JetBrains plugin, and publishes the .vsix and the plugin .zip as artifacts. Each integration job leaves a note on the run page with how many tests passed or were skipped per debugger.

The Python tests need an interpreter. Point to one with the CODE_SCOPE_PYTHON variable or, without installing anything, unzip the Windows embeddable package from python.org into .vscode-test/python and rename the python3XX._pth file that comes with it. Without an interpreter, they are skipped with a warning.

The C# and C tests need the .NET SDK, gcc and gdb on the PATH. Without installing anything, they can also live in .vscode-test/dotnet (the official dotnet-install script with -InstallDir) and .vscode-test/w64devkit (the w64devkit release unzipped there): the test runner adds both to the PATH of the test VS Code. Without them, those tests are skipped.

Known limits

• Earlier calls on the call stack show their simple variables and the first 8 items of their arrays and lists, not their objects. At most 12 calls are read.
• Only objects of classes declared in the file being debugged are drawn, at most 40 per step. Objects inside arrays show only as text.
• JavaScript does not show object identity, so the program itself is asked (a === b); across steps, an object keeps its identity by the paths that lead to it. A list rebuilt from scratch in a single step can look like new objects.
• A condition part that calls a method is only evaluated when the method just reads (len, .length, .size(), .equals, .get...); otherwise it shows "cannot tell beforehand".
• Hidden variables (one name hiding another) are detected in JavaScript blocks and in parameters with the same name as a field. Java and Python have no block scope for local variables.
• In generic mode, only collections the debugger marks as indexed, or whose size is written in the value, show up.
• Matrices with three or more dimensions show the third level as text.
• A list that gains or loses several items in one step is animated when they form one block (addAll, extend, splice); items added in different places show as resized.
• Outside matrices, an integer becomes an arrow when the code uses it as a position: inside brackets (v[i]), in get(i), insert(i, x) and the like, compared with the length, or in the math of another position (meio = (inicio + fim) / 2). Names in codeScope.valueNames never become arrows. Without the source file, any integer that fits the indexes does.
• Stacks and queues are recognized by variable name, reading the whole file: the methods used (push, poll, popleft...) are added up from every place. Two variables with the same name used in different ways in the same file can be classified wrong.
• If you use F5 (continue) between breakpoints instead of F10, the panel shows the accumulated difference between the two stops, and the "ran" line is the previous breakpoint's.
• The JetBrains plugin covers Java only (settings in Settings > Tools > Code Scope). Presentation mode is VS Code only. IntelliJ's F8 also stops on the } that closes an if, which VS Code skips, so the same program can take a few more steps there. After F7, the value a call returned does not show up in IntelliJ.

Roadmap

1. PyCharm and WebStorm: Python and JavaScript in the JetBrains plugin
2. JetBrains Marketplace and VS Code Marketplace
3. C++ containers (std::vector, std::map) and the newer concepts in C#
4. Objects in the variables of earlier calls
5. JavaScript in the browser, tested with the real debugger
6. Adapter for Go

Contributing

Code Scope is open source to help as many people as possible get into programming, and to help those already in it understand their own code better. You can help even if you are just starting:

• report what confused you in the panel by opening an issue;
• write a new sample in samples/, in any language;
• improve an explanation sentence;
• write the adapter for your favorite language;
• implement a roadmap item.

The good first issues list says what to do, where to look and how to know you are done, from tasks that need no code to new language adapters. The contributing guide explains how to set up the environment, run the tests and where each part of the code lives. All participation follows the code of conduct.

Author

Code Scope was created and is maintained by @celoramos. Everyone who helped is on the contributors page.

License

MIT. You may use, study, modify and distribute it, including in classes and courses.