gi

gi is a Go interpreter that creates an executable representation of a Go program from source. It offers a virtual machine that can step through such a program and allows access to the full stack and scoped variables (environment).

gi is implemented using Go reflection API so one can expect 10x slower program execution depending on the complexity.

mission

runtime

• support latest Go SDK
• support type parameterization (generics)
• support Go modules (will require pre-compilation)

debugging

• offer a DAP interface
• handle source changes during a debugging session:
  • change a function definition
  • change a struct definition
  • add package constant|variable
• debugging concurrent programs

status

This is work in progress. See examples for runnable examples using the gi cli. See status for the supported Go language features.

install

go install github.com/emicklei/gi/cmd/gi@latest

Use CLI

run

gi run .

step

gi step .

DAP server

gi dap --listen=127.0.0.1:52950 --log-dest=3 --log

For development, the following environment variables control the execution and output:

• GI_TRACE=1 : produce tracing of the virtual machine that executes the statements and expressions.
• GI_CALL=out.dot : produce a Graphviz DOT file showing the call graph.
• GI_AST=out.ast : produce the mirror AST text file.

Use as package

run a program

package main

import "github.com/emicklei/gi"

func main() {
	pkg, _ := gi.ParseSource(`package main

import "fmt"

func Hello(name string) int {
	fmt.Println("Hello,", name)
	return 42
}
`)
	answer, err := gi.Call(pkg, "Hello", "3i/Atlas")
}

use of in-process DAP (Debug Adapter Protocol)

	gopkg, _ := pkg.LoadPackage(".", nil)
	ipkg, _ := pkg.BuildPackage(gopkg)
	runner := pkg.NewDAPAccess(pkg.NewVM(ipkg))
	runner.Launch("main", nil)
	for {
		if err := runner.Next(); err != nil {
			if err == io.EOF {
				return
			}
		}
		_ = runner.Threads()
		_ = runner.StackFrames(...)
		_ = runner.Scopes(...)
		_ = runner.Variables(...)
	}

Credits

The build pipeline uses all programs of Go By Example to check whether they are executable with gi.

© 2026. https://ernestmicklei.com . MIT License