What is AlgoViz?

AlgoViz is a terminal UI that lets you step through any algorithm line-by-line and watch variables change in real time — directly in your terminal. No browser, no IDE plugins, no setup hassle.

It hooks into native debuggers to execute your code exactly as your compiler/interpreter would, while extracting live variable snapshots at every step.

╭──────────────────────────────────────╮╭──────────────────────────╮
│ 📄 bubble_sort.cpp → bubbleSort()    ││ 🔍 Variables (step #12)  │
│  10 │     for (int j = 0; ...        ││   Name     │ Value       │
│  11 │         if (arr[j] > arr[j+1]) ││   ─────────┼──────────── │
│  12 │             swap(arr[j], ...   ││ ▶ arr      │ size=7      │
│  13 │             swapped = true;    ││ ▶ i        │ 1           │
│  14 │         }                      ││ ▶ j        │ 3           │
│  15 │     }                          ││   swapped  │ true        │
│  ───── 10–15 of 44 lines ──────────  ││   n        │ 7           │
╰──────────────────────────────────────╯╰──────────────────────────╯
╭────────────────────────────────────────────────────────────────────╮
│ Space:Step  A:Auto  R:Restart  Q:Quit     C++  ● ready  L:12 #12 │
╰────────────────────────────────────────────────────────────────────╯

Installation

# Clone the repository
git clone https://github.com/yourusername/algoviz-tui.git
cd algoviz-tui

# Install dependencies
npm install

# Link the global command
npm link

That's it. You now have the algoviz command available anywhere in your terminal.

Usage

algoviz <file>

Examples

# Step through a C++ sorting algorithm
algoviz bubble_sort.cpp

# Visualize a Python script
algoviz fibonacci.py

# Step through JavaScript
algoviz two_sum.js

# Auto-step mode (animates at 300ms intervals)
algoviz bubble_sort.cpp --auto --speed 300

# Force a language for files without standard extensions
algoviz myfile.txt --lang python

Try the included examples

algoviz examples/bubble_sort.cpp
algoviz examples/bubble_sort.py
algoviz examples/fibonacci.js

Controls

| Key | Action | |-----|--------| | Space / N / Enter | Step to next line | | A | Toggle auto-step mode | | R | Restart execution (when finished) | | Q / Ctrl+C | Quit |

How It Works

AlgoViz doesn't transpile or simulate your code. It executes it natively using the real compilers and interpreters on your system, then hooks into each language's debugger infrastructure to control execution:

C++ → LLDB

Your .cpp file
     │
     ▼
clang++ -g -O0 ──→ Debug binary
     │
     ▼
LLDB SB API (via Python bridge)
     │
     ├─ BreakpointCreateByName("main")
     ├─ StepOver() on each keypress
     └─ GetVariables() → JSON → TUI

Compiles your code with debug symbols, then drives LLDB's Python API to step through execution and extract variable values from stack frames.

Python → sys.settrace

Your .py file
     │
     ▼
compile() + exec() with sys.settrace hook
     │
     ├─ Intercepts every 'line' event
     ├─ Captures frame.f_locals
     └─ Streams JSON payloads → TUI

Uses Python's built-in tracing mechanism to intercept every line of execution. print() output is captured separately and forwarded to the console panel.

JavaScript → Node Inspector

Your .js file
     │
     ▼
node --inspect-brk (Chrome DevTools Protocol)
     │
     ├─ Debugger.stepOver on each keypress
     ├─ Runtime.getProperties for scope variables
     └─ WebSocket JSON messages → TUI

Launches Node.js with the inspector protocol, connects over WebSocket, and drives execution via CDP commands.

Requirements

| Language | Requirement | |----------|-------------| | C++ | clang++ (Xcode Command Line Tools) + LLDB | | Python | python3 (3.8+) | | JavaScript | node (18+) | | Runtime | Node.js 18+ for the TUI itself |

macOS

# Install Xcode Command Line Tools (provides clang++ and LLDB)
xcode-select --install

Linux

# Install LLDB and Clang
sudo apt install clang lldb python3-lldb

TUI Layout

┌─────────────────────┬──────────────────┐
│                     │                  │
│   📄 Source View    │  🔍 Variables    │
│                     │                  │
│   Line-by-line      │  Live scope      │
│   with syntax       │  with change     │
│   highlighting      │  detection       │
│                     │                  │
│                     ├──────────────────┤
│                     │                  │
│                     │  💻 Console      │
│                     │                  │
│                     │  stdout/stderr   │
│                     │                  │
├─────────────────────┴──────────────────┤
│  Status Bar: Controls + Language + Line │
└────────────────────────────────────────┘

• Source View — Your code with syntax highlighting. Current line is marked with a cyan highlight. Auto-scrolls to follow execution.
• Variable Table — All in-scope variables. ▶ marks changed values (yellow), + marks new variables (green).
• Console — Real-time stdout/stderr from your program.
• Status Bar — Keyboard shortcuts, language badge, line number, step count.

CLI Options

Usage: algoviz [options] <file>

Arguments:
  file                   Source file to visualize (.py, .js, .cpp, .c)

Options:
  -V, --version          Output the version number
  -s, --speed <ms>       Auto-step interval in milliseconds (default: 500)
  -a, --auto             Start in auto-step mode
  -l, --lang <language>  Force language (python, cpp, javascript)
  -h, --help             Display help

Supported File Extensions

| Extension | Language | |-----------|----------| | .cpp, .cc, .cxx, .c, .hpp | C++ | | .py | Python | | .js, .mjs | JavaScript |

License

MIT