Peek-A-Go

Peek-A-Go traces a Go program step by step with headless Delve and prints a JSON execution trace.

The goal is to make Go execution easier to inspect and eventually support visualizations similar to Python Tutor.

What It Does

• Accepts a single Go source file containing a runnable package main
• Writes the source into a temporary module
• Starts dlv debug in headless mode
• Steps through execution and captures:
  • source line
  • local variables
  • package-level variables
• Prints the collected trace as formatted JSON

Requirements

• Go
• Delve (dlv) available on PATH

Usage

Run directly:

go run . path/to/program.go

Show help:

go run . -h

Build a binary:

go build -o peek-a-go .
./peek-a-go path/to/program.go

Output

The CLI prints a JSON array of steps like:

[
  {
    "File": "main.go",
    "Line": 5,
    "Function": "",
    "Locals": {
      "x": "2"
    },
    "Globals": {
      "total": "3"
    }
  }
]

Testing

The test suite uses fixture programs under testdata/progs.

Run tests with:

go test ./...

Notes

• The current implementation traces a single linear execution timeline.
• It is intended for small runnable programs.
• The trace format is designed for downstream visualization tools.