🍋 Limoni

A terminal UI engine for Go that tests can click, AI agents can drive,
and the garbage collector never sees.

English • Türkçe

▶ Try it in your browser — the same engine compiled to WebAssembly, no install.

---

Quick start

go get github.com/thebanri/limoni

package main

import "github.com/thebanri/limoni"

func main() {
	limoni.Run(func(f *limoni.Frame, ev *limoni.Event) bool {
		if ev != nil && ev.Type == limoni.EventKey && ev.Key.Type == limoni.KeyEsc {
			return false // quit
		}
		f.RenderComponent(limoni.Border(
			limoni.Center(limoni.Label("Hello from Limoni 🍋  (Esc quits)", limoni.Bold())),
			limoni.SymbolsRounded,
			limoni.Fg(limoni.Hex("#FFCC00")),
		), f.Area())
		return true
	})
}

Or generate a project that runs straight away, with a test already written:

go run github.com/thebanri/limoni/cmd/limoni@latest new myapp    # -template counter|dashboard|form|ssh
cd myapp && go mod tidy && go run .
go test ./...                                                     # a uitest test comes with every template

Next: Getting started · Widget gallery · Examples

---

Why Limoni

1. Your TUI has a semantic tree, so tests and agents address widgets by name

Most terminal automation, such as termwright or mcp-tui-test, parses the rendered character grid, so a test breaks when the layout moves by one column. A Limoni app builds a semantic tree every frame (the same tree a screen reader uses), and the tools below work on that tree instead.

uitest: Playwright-style tests. Checks wait instead of sleeping, and a failure prints the whole tree of the last frame.

page := uitest.Run(t, 80, 24, app.draw)            // in process: no terminal needed

page.GetByRole("input", "New task").Type("Tag v1.0")
page.GetByRole("button", "Add task").Click()
page.Expect(page.GetByRole("list-item", "").Within(page.GetByRole("list", "Tasks"))).ToHaveCount(3)
page.Expect(page.GetByID("status")).ToContainLabel("Added")

limoni-mcp: let an AI agent drive the app. It gives Claude Code, Cursor or any MCP client eight tools (tree, click, type_text, wait_for…) that work on the same tree. In one recorded run, Claude Code completed a release checklist in 17 tool calls. That run included typing a deploy token the agent could not read back.

go run -tags limoni_debug ./examples/agent_checklist
claude mcp add limoni -- limoni-mcp -socket "$XDG_RUNTIME_DIR/limoni-checklist.sock"

The automation socket only exists in -tags limoni_debug builds. It is closed by default, only the same user can connect, and secret fields are never exposed. → Semantic automation, MCP and uitest

2. Fast where you can feel it

• Zero heap allocations per frame for the renderer, every widget's drawing, and the click handling of the common input widgets, enforced in CI, so animations don't stutter from GC pauses. Widgets with drag or custom handlers (Table, Slider, Dialog, …) still allocate a closure each. The details.
• Few bytes per frame. Blank runs become ECH/EL and repeats become REP: a full-screen redraw is 377 bytes, and an idle app sends nothing. Bytes, not CPU, are what you feel over SSH.
• Virtual tables and lists. One million rows scroll at ~2.7 ms a frame, because only visible rows are touched.

Absolute numbers depend on the machine. The comparisons against Ratatui 0.30.2, Ultraviolet and Bubble Tea v1.3.10, including which ratios are not meaningful, are in docs/benchmarks.md and the methodology. One earlier run showed a 4,700× lead; it came from a bug in the benchmark harness, and the methodology explains how it was caught.

3. Batteries that other TUI libraries leave to you

The only dependencies are golang.org/x/sys and golang.org/x/crypto.

---

Built with Limoni: zest

zest is a log viewer and Limoni's flagship app. It follows files and pipes, colours by level, and filters a million lines without stalling. A 67 MiB, 1,000,000-line log is on screen in about half a second.

go install github.com/thebanri/limoni/cmd/zest@latest
zest -demo 1000000        # or: zest app.log, kubectl logs -f pod | zest

Or try it in the browser: the "Logs · zest" scene.

And: globe

globe is a world you can turn, search, zoom into and pin — and what a Limoni application looks like from the outside, since it is a module of its own that depends on a published Limoni and uses nothing but its public API.

go install github.com/thebanri/limoni/apps/globe@latest
globe -at Türkiye

Everything on it is in the semantic tree, so "find Turkey on the world map" is something an agent can do over MCP: type into search, click the row, read image#globe back as value="39.3°N 34.5°E · zoom 2.6×". Nothing of it reaches you when you import Limoni — a directory with its own go.mod is not part of the module around it.

---

Two ways to write an app

Both use the same renderer and widgets and are available from the root package. examples/counter is a complete declarative app in under 80 lines. Coming from Bubble Tea? See the migration guide.

---

Widgets

→ Widget gallery · Widget reference

---

Examples

Run any of them with go run ./examples/<name>, or without cloning: go run github.com/thebanri/limoni/examples/3d_viewer@latest. All examples: docs/examples.md.

---

Documentation

Turkish documentation: docs/tr.

---

Status

Limoni is pre-1.0. Patch releases don't break the API; minor releases may, and every break is listed in the changelog. The core renderer, layout and widgets are settling; the automation, uitest and session packages are new and experimental. See docs/stability.md for what has to happen before v1.0.

Community and contributing

• Questions and ideas: GitHub Discussions
• Bugs: open an issue. The template asks for your terminal emulator, since most rendering bugs depend on it.
• First contribution: issues labelled good first issue are scoped to one file and say how to verify the change. Start with CONTRIBUTING.md.
• Built something? Add it to AWESOME.md.

AI assistants (Claude, Gemini) were used during development for scaffolding, tests and documentation drafts. The architecture was designed, profiled and benchmarked by the author, and the benchmark harness exists to check claims, from people or tools.

Security policy · Code of Conduct · Apache License 2.0