let-go

command module
v1.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 2 Imported by: 0

README ΒΆ

Squishy loafer

Tests

let-go

πŸ’¬ Come talk about let-go in #let-go on The Fixpoint Discord.

Greetings loafers! (Ξ»-gophers haha, get it?)

let-go is a Clojure dialect with a bytecode compiler and stack VM, written in Go. A single ~13MB binary, ~10ms cold start, no JVM. It passes the jank-lang test suite.

I started this in 2021 as an elaborate joke: an excuse to write Clojure while pretending to write Go. It turned out useful. I use it for CLIs, scripts, and web servers, and I built a daemonless container runtime on top of it. You can compile let-go programs to standalone binaries or self-contained WASM web pages. It even runs on Plan 9, and ReMarkable 2.

It is not a drop-in replacement for Clojure JVM. It does not load JARs and does not aim to. Most idiomatic Clojure code runs unmodified, but a real project with library dependencies will need adjustments. See Known limitations below.

Goals (in no particular order)

  • Quality entertainment
  • Implement most of Clojure: persistent data structures, lazy seqs, transducers, protocols, records, multimethods, core.async, BigInts
  • Comfy two-way Go interop (functions, structs, channels)
  • AOT compilation to bytecode and standalone binaries
  • Boot the runtime inside a single requestAnimationFrame (10ms left over at 60fps)
  • Compile programs to self-contained WASM web pages with terminal emulation
  • Make it legal to write Clojure at your Go dayjob
  • nREPL in the browser (let-go VM in WASM, editor over WebSocket)
  • Stretch: let-go bytecode β†’ Go translation

Non-goals: drop-in JVM Clojure replacement; linter/formatter for Clojure-at-large.

Benchmarks

let-go (bytecode VM), let-go AOT (the same code IR-lowered to native Go), Babashka, and Clojure JVM. All benchmark files are valid Clojure that runs unmodified; the VM and AOT legs run the identical program β€” only dispatch differs. Apple M1 Pro.

let-go let-go AOT babashka clojure JVM
Binary size 13MB 18MB 68MB 304MB (JDK)
Startup 11.1ms 10.7ms 20.4ms 364ms
Idle memory 15.2MB 15.2MB 27.0MB 97.7MB

let-go stays compact and quick to launch: a small native binary, fastest startup in this run, low RSS, and no JVM dependency.

On runtime benchmarks, the VM is competitive on short-lived data work β€” map/filter (11.3ms) comes in 1.7Γ— ahead of Babashka, and persistent maps (22.2ms) run neck and neck with it β€” while AOT lowering turns the call-heavy numeric cases around entirely: fib(35) drops from 2.42s to 0.11s and tak from 2.40s to 94ms, an order of magnitude ahead of Babashka. Fully-warmed HotSpot still holds the raw-compute crown (steady-state JVM fib(35) is ~76ms to AOT's ~99ms, measured in-process) but pays ~360ms of startup first, so on one-shot runs let-go AOT delivers the result ~5Γ— sooner. Babashka still leads reduction/transducer workloads.

Full per-benchmark numbers and methodology: benchmark/results.md.

Compatibility

Tested against jank-lang/clojure-test-suite: 5621 / 5621 assertions pass across 232 files through the :clj reader lens, with no known failures, compile skips, panic skips, or runtime skips.

Core namespaces cover clojure.core (macros, lazy seqs, transducers, protocols, records, multimethods, BigInt/BigDecimal) plus string, set, walk, edn, pprint, test, and core.async, alongside let-go's own io, http, json, transit, os, System, syscall, and pods. See docs/guide/clojure-compatibility.md for the full per-namespace status table and docs/known-divergences.md for intentional differences, temporary mismatches, and the rationale behind shared-suite :lg overrides.

Babashka pods

let-go can load Babashka pods, opening up the whole pod ecosystem (SQLite, AWS, Docker, file watching, …) and sharing ~/.babashka/pods/ with bb.

(pods/load-pod 'org.babashka/go-sqlite3 "0.3.13")
(pod.babashka.go-sqlite3/query "app.db" ["select * from users"])

See docs/guide/pods.md for a full example and the shared pod cache.

Portable code (:lg reader conditionals)

let-go ships namespaces of its own (e.g. let-go.semver) that JVM Clojure can't load. To keep shared code loadable on both, guard the let-go-only parts behind :lg reader conditionals in a .cljc file β€” JVM Clojure skips :lg branches the same way it skips :cljs:

(ns my.app
  #?(:lg (:require [let-go.semver :as semver])))   ; only let-go loads this

The guard is at read time, so a missing namespace never reaches compilation. See docs/guide/portability.md for the .cljc resolution rule and :lg/:clj ordering gotcha.

Version requirements (let-go.semver)

let-go.semver provides SemVer values that sort correctly, npm/cargo-style range matching (satisfies-range? β€” comparators, x-ranges, ^/~, ||), and require-letgo, which asserts at load time that the running lg build is new enough and fails with one clear line instead of a "can't resolve" cascade:

(ns my.app
  #?(:lg (:require [let-go.semver :refer [require-letgo]])))

#?(:lg (require-letgo ">=1.9.0"))   ; one clear failure line on too-old lg

Guard it behind :lg reader conditionals so shared .cljc stays JVM-loadable. See docs/guide/semver.md for the range grammar and require-letgo's detection/failure semantics.

Known limitations

Not a drop-in JVM Clojure. The main gaps: no coordinated STM or async agents (ref/agent are atom-backed aliases), no clojure.spec, unchunked lazy seqs, no custom *data-readers*, limited JVM host interop on deftype/reify, and no subseq/rsubseq range queries. Behavior also differs in places β€” pragmatic numeric tower, always-blocking channels, real-goroutine go blocks, and re2 (not Java) regex.

Full list with rationale: docs/guide/clojure-compatibility.md.

Examples

Things written in let-go:

  • xsofy: a roguelike that runs in the browser and the terminal from the same source
  • lgcr: a daemonless container runtime, built on the syscall namespace

In this repo:

Try it online

Bare-bones browser REPL, running a WASM build of let-go.

Install

Homebrew (macOS / Linux)

Primary install command:

brew install nooga/tap/let-go
Download

Prebuilt binaries for Linux, macOS, and Plan 9 in Releases.

From source (Go 1.26+)
go install github.com/nooga/let-go@latest
Usage
lg                                # REPL
lg -e '(+ 1 1)'                   # eval expression
lg myfile.lg                      # run file
lg myfile.lg a b                  # run file with arguments
lg -r myfile.lg                   # run file, then REPL

*command-line-args* holds the program's arguments β€” the positionals after the script β€” as a seq of strings, or nil when there are none. It reads the same whether you run a script or a bundled binary, so you never slice argv by hand:

;; greet.lg β€” run as `lg greet.lg Alice Bob` or `./greet Alice Bob`
(doseq [name *command-line-args*]
  (println "Hello," name))

Compile and distribute

let-go can compile programs to bytecode (.lgb files) and bundle them as standalone executables.

lg -c app.lgb app.lg              # compile to bytecode
lg app.lgb                        # run bytecode

lg -b myapp app.lg                # bundle into a self-contained binary
./myapp                           # runs anywhere, no lg needed

The standalone binary is a copy of lg with your bytecode appended. Copy it to another machine and it runs.

Release artifacts can split source maps and local-variable tables into a digest-bound debug companion:

lg -strip -c app.lgb app.lg       # writes app.lgb + app.lgb.debug
lg -strip -b myapp app.lg         # writes myapp + myapp.debug

Archive the .debug file while distributing only the smaller runtime artifact. Putting it back beside the artifact restores source-located stack traces automatically; LG_DEBUG_FILE=/path/to/app.debug selects a companion stored elsewhere. A companion for a different build is rejected.

lg -w site app.lg                 # compile to a WASM web app
open site/index.html

The WASM output is a self-contained index.html (~6MB, inlined and gzipped) with a service worker for the COOP/COEP headers SharedArrayBuffer needs; term-using programs get full xterm.js terminal emulation.

See docs/guide/usage.md for the *compiling-aot* / *in-wasm* compile-time vars, more on each output format, and project/dependency management with lgx.

Resources and source paths

Programs read non-source files (templates, web assets, data) via io/resource, with roots set by -resource-paths / LG_RESOURCE_PATHS. Bundling with -b embeds every file under those roots, so a bundled binary is self-contained.

(when-let [r (io/resource "templates/index.html")]
  (io/slurp r))

required namespaces resolve against -source-paths / LG_SOURCE_PATHS (default .). When you set the search path it's taken as the complete list β€” the current directory isn't added implicitly.

See docs/guide/resources-and-source-paths.md for path-list syntax, multi-root precedence, embedding behavior, and the empty-value/explicit-only rules.

nREPL

let-go ships an nREPL server that works with CIDER (Emacs), Calva (VS Code), and Conjure (Neovim). It writes .nrepl-port to the working directory so editors auto-discover it.

lg -n                             # default port 2137
lg -n -p 7888

See docs/guide/nrepl.md for supported ops and per-editor connect steps.

Embedding in Go

let-go embeds cleanly as a scripting layer for Go programs: define Go values and functions, hand them to the VM, run user-supplied Clojure against your data. Go structs roundtrip as records, Go channels are first-class let-go channels, and Go functions are callable from let-go.

c, _ := api.NewLetGo("myapp")
c.Def("greet", func(name string) string { return "Hello, " + name })
v, _ := c.Run(`(greet "world")`)   // "Hello, world"

See docs/guide/embedding-in-go.md for struct roundtripping, Go-channel interop, and a pointer to the full example set.

Testing

go test ./... -count=1 -timeout 30s

Contributing

After cloning, run make install-hooks once to register the core_compiled.lgb and generated.sums merge drivers (each clone needs this β€” the config lives in .git/config, which isn't shared). See docs/regenerating-generated-artifacts.md for how generated artifacts are regenerated and kept in sync.


Ever wanted a 20MB pure-Go JS runtime that typechecks and runs TypeScript? Check my other project: https://github.com/nooga/paserati

πŸ€“ Follow me on X 🐬 Check out monk.io

Documentation ΒΆ

Overview ΒΆ

Command lg is the let-go command line. Everything it does lives in github.com/nooga/let-go/pkg/cli so a third-party module can build a binary with the same full feature set β€” repl, resolver, -c, -b, -w β€” around its own generated interop packages. See docs/guide/custom-lg.md.

Only the ldflags contract stays here: goreleaser and the Makefile both set -X main.version / -X main.commit, and ldflags can only reach the package that declares the variable.

Directories ΒΆ

Path Synopsis
cmd
bench-baton command
Command bench-baton is a machine-quiescence lease for benchmarks, with a concurrent lane for builds and tests.
Command bench-baton is a machine-quiescence lease for benchmarks, with a concurrent lane for builds and tests.
bench-ratchet command
Command bench-ratchet runs Go benchmarks, normalizes results against a calibration anchor benchmark, and compares them to a stored baseline.
Command bench-ratchet runs Go benchmarks, normalizes results against a calibration anchor benchmark, and compares them to a stored baseline.
bootprobe command
bootprobe reports where core boot time goes: bundle decode vs definition replay vs everything else, using LoadCoreBundle's OnPhase hooks.
bootprobe reports where core boot time goes: bundle decode vs definition replay vs everything else, using LoadCoreBundle's OnPhase hooks.
check-generated command
check-generated's default mode exits non-zero when committed generator-input provenance is stale.
check-generated's default mode exits non-zero when committed generator-input provenance is stale.
go-callables command
Command go-callables measures Go callables for the code-quality report.
Command go-callables measures Go callables for the code-quality report.
hoist-natives command
Command hoist-natives is a codemod that lifts the inline anonymous closures registered as clojure.core primitives in pkg/rt/lang.go into named, //lg:native-annotated top-level functions.
Command hoist-natives is a codemod that lifts the inline anonymous closures registered as clojure.core primitives in pkg/rt/lang.go into named, //lg:native-annotated top-level functions.
lg-runtime command
lgbgen command
This file carries the go:generate directives that regenerate the core bundle and the lowered Go tree from the .lg sources.
This file carries the go:generate directives that regenerate the core bundle and the lowered Go tree from the .lg sources.
lgbstat command
lgbstat reports where a .lgb's bytes go.
lgbstat reports where a .lgb's bytes go.
lginterop command
lgprimgen command
Command lgprimgen generates pkg/rt/zz_primitives_generated.go from the //lg:native directives in the runtime's Go sources.
Command lgprimgen generates pkg/rt/zz_primitives_generated.go from the //lg:native directives in the runtime's Go sources.
perf-page command
examples
go_interop_lazy command
Worked example: a Go program embeds let-go, then consumes potentially-infinite let-go sequences from Go using the new vm.Iter (Go 1.23+ iter.Seq[Value]) and vm.SeqToSlice helpers.
Worked example: a Go program embeds let-go, then consumes potentially-infinite let-go sequences from Go using the new vm.Iter (Go 1.23+ iter.Seq[Value]) and vm.SeqToSlice helpers.
internal
gofragment
Package gofragment is the Go AST fragment oracle used by the native-entry gate and the jank direct-ABI test.
Package gofragment is the Go AST fragment oracle used by the native-entry gate and the jank direct-ABI test.
lginteroptest/empty
Package empty deliberately exports nothing.
Package empty deliberately exports nothing.
primgen
Package primgen scans //lg:-annotated Go sources and emits the zz_primitives_generated.go registrar.
Package primgen scans //lg:-annotated Go sources and emits the zz_primitives_generated.go registrar.
pkg
api
bundle
Package bundle implements the standalone-binary trailer format and resource collection used by `lg -b`.
Package bundle implements the standalone-binary trailer format and resource collection used by `lg -b`.
cli
complete
Package complete supplies REPL symbol completion.
Package complete supplies REPL symbol completion.
genmanifest
Provenance dependency manifest: which generator INPUTS feed each generated OUTPUT, plus exact readiness hashes for declared file outputs.
Provenance dependency manifest: which generator INPUTS feed each generated OUTPUT, plus exact readiness hashes for declared file outputs.
gomod
Package gomod scaffolds the throwaway Go module that `lg` generates around emitted Go sources before handing them to `go build`.
Package gomod scaffolds the throwaway Go module that `lg` generates around emitted Go sources before handing them to `go build`.
ir
perfdata
Package perfdata defines the JSON schema shared by the perf tools.
Package perfdata defines the JSON schema shared by the perf tools.
rt
This file carries no bootstrap build constraint on purpose: BootCore must exist in every build so a downstream caller compiles, and under -tags bootstrap the embedded core (CoreCompiledLGB) is empty, making LoadCoreBundle return the documented error instead of an undefined-symbol failure.
This file carries no bootstrap build constraint on purpose: BootCore must exist in every build so a downstream caller compiles, and under -tags bootstrap the embedded core (CoreCompiledLGB) is empty, making LoadCoreBundle return the documented error instead of an undefined-symbol failure.
rt/builtins
Package builtins is the single-source home for direct-call-eligible clojure.core builtins: context-free functions with uniform vm.Value signatures.
Package builtins is the single-source home for direct-call-eligible clojure.core builtins: context-free functions with uniform vm.Value signatures.
rt/corefns
Package corefns is a placeholder while the lginterop-driven direct-call path is being wired up.
Package corefns is a placeholder while the lginterop-driven direct-call path is being wired up.
rt/wasm
Package wasm holds build-time JS and HTML assets for the `lg -w` WASM bundler.
Package wasm holds build-time JS and HTML assets for the `lg -w` WASM bundler.
vm

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL