Algokit AVM VSCode Debugger is a free, open source extension for Visual Studio Code that lets developers step through Algorand smart contracts one line at a time. It is aimed at developers writing contracts on the Algorand Virtual Machine (AVM), whether they work in raw TEAL, Algorand Python, TypeScript or TealScript.
Instead of guessing why a contract failed or stepping through logs by hand, you can run a simulated application call, load the resulting trace and move through the execution in your editor. The extension uses AVM simulate traces and source maps to match each executed instruction back to the source code you wrote, which makes it much easier to find logic errors before deployment.
What Is the AVM and Why Does Debugging It Matter?
The Algorand Virtual Machine executes smart contracts, called applications, on the Algorand blockchain. Contracts run in a constrained environment with limited opcodes, strict cost budgets and a stack-based model, so small logic mistakes can be hard to see in the code alone.
A debugger that follows the actual execution path shows what the contract really did, not what the developer intended it to do. That difference is where most subtle bugs live, such as an unexpected branch taken on a particular state value or a stack value left in the wrong order.
Who Is This Extension For?
The extension is most useful for developers who already write Algorand smart contracts and want better visibility into execution. It fits teams that build contracts in TEAL directly as well as teams that write in Algorand Python or TypeScript and compile through Puya or a similar pipeline.
The documentation recommends using it inside an AlgoKit based project, which gives you a consistent layout, test tooling and the algokit-utils library the simulation step relies on.
How Source Maps Connect Traces to Your Code
When a higher-level language compiles to TEAL, the generated bytecode no longer resembles the original source. Source maps record which source lines correspond to which compiled instructions. The extension combines these maps with the AVM simulate trace to show you the matching lines as execution proceeds.
This is what makes debugging compiled code practical. Without the mapping, you would be reading raw opcodes and trying to reconstruct the original logic by hand.
Typical Debugging Scenarios
A common case is a contract that rejects a transaction with no obvious reason. You run the application call, save the simulate trace, and step through to see which assertion or comparison fails. Another case is verifying that a global state update happens only under the intended conditions.
Developers also use traces to compare expected and actual behavior after refactoring. Re-running the same call on the new code and stepping through both traces can show exactly where behavior diverged.
Key features
Application call simulation
Line-by-line stepping
Trace file support
Guided session setup
Multiple entry points
Supported coins
The documentation mentions Algorand as the network this debugger works with. It is designed for contracts that run on the AVM, so its scope is Algorand smart contracts.
How to install Algokit AVM Vscode Debugger on Windows
- 1
Set up an AlgoKit project
The extension is recommended for AlgoKit based projects. Install the AlgoKit CLI and create or open a project so that the test tooling and algokit-utils are available.
- 2
Install the extension in VS Code
Open Visual Studio Code, go to the Extensions view and search for the AlgoKit AVM VS Code Debugger. Install it, or download the package from the official source repository and install it from a VSIX file.
- 3
Verify the download
Download only from the official website or the GitHub repository at github.com/algorandfoundation/algokit-avm-vscode-debugger. Compare the file's SHA-256 checksum or signature against the value published with the release before installing.
-
Confirm the installation
Restart VS Code and open a trace file ending in .trace.avm.json. If the debug icon appears in the top-right corner of the editor, the extension is active.
System requirements
- Visual Studio Code
- An AlgoKit based project is recommended
How to use Algokit AVM Vscode Debugger
The workflow has two parts: generate a simulated application call that produces a trace, then open that trace in the debugger. The extension guides you through the selection, so you mainly need a project with a contract and an application call to run.
- Open your AlgoKit project in Visual Studio Code.
- Run an application call against your contract using algokit-utils so that an AVM simulate trace is produced.
- Locate the saved trace file, which ends in .trace.avm.json.
- Open the trace file, then click the debug icon in the top-right corner of the editor, or run the Debug AVM Trace File command from the Command Palette.
- Follow the prompts to select the matching source files and trace.
- Step through the execution line by line and watch how the stack and each instruction change.
- Compare the path taken against what you expected, adjust the contract, and generate a new trace to verify the fix.
Pros & cons
- Free and open source under a public repository
- Debugs both raw TEAL and higher-level languages compiled to TEAL
- Uses source maps to link execution back to your own code
- Guided setup reduces mistakes when pairing traces and sources
- Integrates directly into the Visual Studio Code workflow
- Trace files can be saved and reopened later
- Focused on Algorand only, so it does not help with other blockchains
- Requires generating a simulate trace first, which adds a step to each debugging run
- Recommended setup assumes an AlgoKit based project
- Labeled as a beta release, so behavior may still change
- Windows support is listed as likely rather than explicitly confirmed, so check the releases page
Is Algokit AVM Vscode Debugger safe?
The extension itself does not ask for seed phrases or private keys, but a developer tool still runs code on your machine, so install it carefully. Download only from the official GitHub repository or the official Algorand channels, and verify the SHA-256 checksum or signature published with the release. Never enter a seed phrase or wallet secret into a third-party website or unofficial installer.
The project is actively maintained, with its most recent code update dated May 22, 2026, and the release shown is a beta version. Use beta builds with care in production workflows, and check the GitHub Releases page for the latest stable package before relying on it.
- Official source only. Download from github.com/algorandfoundation/algokit-avm-vscode-debugger. Ignore ads and lookalike domains.
- Check the SHA-256. Compare the installer hash with the value the developer publishes before running it.
- Never share your seed phrase. No developer, support agent or website — including CryptApps — will ever ask for it.
Alternatives
Algokit AVM VSCode Debugger is narrower than the AlgoKit CLI, which covers project creation, deployment and many other tasks. The debugger focuses on a single job: showing what a contract does step by step inside the editor. Tools such as Graviton and Algojig approach testing from a different angle, through blackbox tests and test harnesses, so they answer the question of whether a contract behaves correctly rather than why a specific run took a particular path.
If you write contracts in C#, the Algorand Visual Studio Extension covers a different language and workflow. Algoml, which compiles a domain-specific language into TEAL, produces the code this debugger can later inspect. Most Algorand developers will use several of these tools together rather than choosing one.
Specifications
- Price
- Free
- Type
- Open source
- License
- —
- Latest version
- v1.1.8-beta.2
- Last update
- 22 May 2026
- Windows support
- Likely (builds for Windows; check releases)
- Source code
- github.com/algorandfoundation/algokit-avm-vscode-debugger
Frequently asked questions
Yes. Algokit AVM VSCode Debugger is free and open source. Its source code is publicly available on GitHub, so you can review it, use it and contribute to it without paying for a license. Check the repository for the license terms that apply to the current release.
Windows support is listed as likely, since the project builds for Windows, but you should check the releases page for the package you need. Install it into Visual Studio Code on Windows and confirm that the debug icon appears when you open a trace file. If it does not, look for a Windows-specific note in the repository.
The debugger works with contracts written directly in TEAL and with contracts written in Algorand Python, TypeScript and TealScript that compile to TEAL. It relies on source maps to match compiled instructions to the code you wrote, so the compiled output needs to include that mapping.
An AVM simulate trace is a record of how the Algorand Virtual Machine executed an application call during a simulated run. It lists the instructions executed and the state at each step. The debugger reads this file, which ends in .trace.avm.json, and lets you step through the execution in your editor.
You do not strictly need one, but the documentation recommends an AlgoKit based project. The project provides consistent structure, test tooling and the algokit-utils library that the application call step uses to generate traces.
No. The debugger is built for the Algorand Virtual Machine and works with Algorand smart contracts only. For Solidity and Ethereum-based development, you would need a different tool, such as the Remix Desktop IDE.
Download it only from the official GitHub repository or official Algorand channels, and verify the SHA-256 checksum or signature against the published release. The extension does not handle wallet keys itself, but you should still never enter a seed phrase into a third-party site.
The current release is a beta, so treat it as a development aid rather than a guaranteed production component. Test it on your own contracts, keep an eye on the releases page for stable builds, and use it alongside your normal testing process.
Verdict
Algokit AVM VSCode Debugger is a practical choice for Algorand developers who need to see exactly how a smart contract executes. It is free, open source and fits naturally into an AlgoKit workflow in Visual Studio Code. It is best suited to developers who already write TEAL or compile from Puya-supported languages and want to find logic errors through traces rather than guesswork. Since the release is a beta, confirm the latest version on the official website before adopting it for serious projects.