goberzurg

README

goberzurg

A Go library for displaying images in terminal emulators, inspired by ueberzug. Uses terminal graphics protocols :: no X11/Wayland overlays, no CGo, no external dependencies.

Features

• Kitty protocol (kitty, wezterm, ghostty)
• Sixel (xterm, mlterm, foot)
• iTerm2 inline images (iTerm2)
• Auto-detection :: picks the right backend from $TERM, $TERM_PROGRAM, $KITTY_WINDOW_ID
• Programmatic image scaling :: resizing works identically across all backends (nearest-neighbor)
• tmux support :: auto-detects tmux and wraps escape sequences in DCS passthrough
• bubbletea compatible :: backends write directly to os.Stdout
• Zero external dependencies :: pure Go standard library

Requires Go 1.26.2 or later.

Build

CLI

go build -o goberzurg ./cmd/goberzurg/

Tests

go test -v ./...
go test -race ./...

Makefile

make lib         # build the library
make cli         # build the CLI binary
make test        # run tests with race detector
make install     # install CLI + man pages (PREFIX=/usr/local)
make clean       # remove built binary

Install to a custom prefix:

make install PREFIX=$HOME/.local

Usage (library)

package main

import (
    "github.com/bakedsnake/goberzurg"
)

func main() {
    r := goberzurg.New()
    defer r.Close()

    r.Display("image.png",
        goberzurg.WithPos(5, 2),       // column, row
        goberzurg.WithSize(40, 30),    // width, height in character cells
    )
}

Force a specific backend:

r := goberzurg.New(goberzurg.WithBackend(goberzurg.NewKittyBackend()))

bubbletea integration

import (
    tea "github.com/charmbracelet/bubbletea"
    "github.com/bakedsnake/goberzurg"
)

type model struct {
    renderer *goberzurg.Renderer
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        if msg.String() == "q" {
            return m, tea.Quit
        }
    }
    return m, nil
}

func (m model) View() string {
    m.renderer.Display("photo.png", goberzurg.WithPos(0, 0))
    return "Hello\n"
}

func main() {
    r := goberzurg.New()
    defer r.Close()
    tea.NewProgram(model{renderer: r}).Run()
}

Usage (CLI)

Display an image at position (column, row):

goberzurg image.png 5 2

With width and height (in character cells):

goberzurg image.png 5 2 40 30

List available backends:

goberzurg --list-backends

Force a backend:

goberzurg --backend kitty image.png 5 2

stdin protocol (JSON)

echo '{"action":"add","path":"image.png","x":5,"y":2,"width":40,"height":30,"z":1}' | goberzurg

Simple text format also works:

echo 'add image.png 5 2 40 30' | goberzurg

Commands: add / display, clear / remove, quit / exit. JSON fields: action, path, x, y, width, height, z.

Backends

Backend	Terminals	Protocol
Kitty	kitty, wezterm, ghostty	\e_G… escape sequences
Sixel	xterm, mlterm, foot, etc.	\ePq… sixel graphics
iTerm2	iTerm2	\e]1337;File=… OSC sequence

Detection priority: $KITTY_WINDOW_ID → $TERM_PROGRAM → $TERM (sixel/xterm keywords) → Kitty (fallback).

Sizing (width, height) is handled programmatically in Go :: images are scaled before being passed to any backend. This means WithSize(40, 30) produces the same result on every backend regardless of terminal protocol capabilities.

Summary

Source files

File	Purpose
goberzurg.go	Core types (Pos, Size, Options, Option funcs)
image.go	Image loading, format detection, PNG/JPEG encoding, ScaleToCells()
renderer.go	Backend interface, Renderer high-level API
kitty.go	Kitty terminal protocol backend
sixel.go	Sixel graphics backend
iterm2.go	iTerm2 inline images backend
detect.go	Automatic terminal detection
tmux.go	tmux DCS passthrough, ClearOnResetWriter
doc.go	Package documentation
cmd/goberzurg/main.go	CLI tool
goberzurg_test.go	Tests

Man pages

Section	File	Content
1	man/goberzurg.1	CLI usage, options, stdin protocol, backends, examples
3	man/goberzurg.3	Library API documentation (Renderer, Image, Open, ScaleToCells, etc.)

License

MIT

Documentation

Overview

Package goberzurg displays images in terminal emulators.

It provides multiple backends using terminal graphics protocols:

• Kitty protocol (kitty, wezterm, ghostty)
• Sixel (xterm, mlterm, foot)
• iTerm2 inline images (iTerm2)

The backends write directly to the terminal via os.Stdout, making them compatible with bubbletea programs.

Basic usage:

r := goberzurg.New()
defer r.Close()
r.Display("image.png", goberzurg.WithPos(5, 2))

To force a specific backend:

r := goberzurg.New(goberzurg.WithBackend(goberzurg.NewKittyBackend()))

Index

• Variables
• type Backend
  • func Detect() Backend
• type BackendType
  • func DetectType() BackendType
• type ClearOnResetWriter
  • func NewClearOnResetWriter(w io.Writer, clearFn func() error) *ClearOnResetWriter
  • func (c *ClearOnResetWriter) Write(p []byte) (int, error)
• type Image
  • func Open(path string) (*Image, error)
  • func ScaleToCells(img *Image, cellW, cellH int) (*Image, error)
  • func (img *Image) EncodeJPEG() ([]byte, error)
  • func (img *Image) EncodePNG() ([]byte, error)
• type Iterm2Backend
  • func NewIterm2Backend() *Iterm2Backend
  • func (i *Iterm2Backend) Clear() error
  • func (i *Iterm2Backend) Close() error
  • func (i *Iterm2Backend) Display(key string, img *Image, opts Options) error
  • func (i *Iterm2Backend) Name() string
• type KittyBackend
  • func NewKittyBackend() *KittyBackend
  • func (k *KittyBackend) Clear() error
  • func (k *KittyBackend) Close() error
  • func (k *KittyBackend) Display(key string, img *Image, opts Options) error
  • func (k *KittyBackend) Name() string
• type Option
  • func WithPos(x, y int) Option
  • func WithSize(w, h int) Option
  • func WithZIndex(z int) Option
• type Options
• type Pos
• type Renderer
  • func New(opts ...RendererOption) *Renderer
  • func (r *Renderer) Backend() Backend
  • func (r *Renderer) Clear() error
  • func (r *Renderer) Close() error
  • func (r *Renderer) Display(path string, opts ...Option) error
  • func (r *Renderer) Name() string
• type RendererOption
  • func WithBackend(b Backend) RendererOption
• type RendererOptions
• type SixelBackend
  • func NewSixelBackend() *SixelBackend
  • func (s *SixelBackend) Clear() error
  • func (s *SixelBackend) Close() error
  • func (s *SixelBackend) Display(key string, img *Image, opts Options) error
  • func (s *SixelBackend) Name() string
• type Size

Variables

var IsTmux bool

Types

type Backend

type Backend interface {
	Display(key string, img *Image, opts Options) error
	Clear() error
	Close() error
	Name() string
}

func Detect

func Detect() Backend

type BackendType

type BackendType int

const (
	BackendUnknown BackendType = iota
	BackendKitty
	BackendSixel
	BackendIterm2
)

func DetectType

func DetectType() BackendType

type ClearOnResetWriter

type ClearOnResetWriter struct {
	// contains filtered or unexported fields
}

ClearOnResetWriter wraps an io.Writer and calls clearFn when it detects a clear-screen escape sequence (\x1b[2J or \x1b[3J) being written. This ensures placed images are cleared when the terminal is cleared.

func NewClearOnResetWriter

func NewClearOnResetWriter(w io.Writer, clearFn func() error) *ClearOnResetWriter

NewClearOnResetWriter creates a writer that auto-clears images on terminal clear.

func (*ClearOnResetWriter) Write

func (c *ClearOnResetWriter) Write(p []byte) (int, error)

type Image

type Image struct {
	Format  string
	Width   int
	Height  int
	Data    []byte
	Decoded image.Image
}

func Open

func Open(path string) (*Image, error)

func ScaleToCells

func ScaleToCells(img *Image, cellW, cellH int) (*Image, error)

func (*Image) EncodeJPEG

func (img *Image) EncodeJPEG() ([]byte, error)

func (*Image) EncodePNG

func (img *Image) EncodePNG() ([]byte, error)

type Iterm2Backend

type Iterm2Backend struct {
	// contains filtered or unexported fields
}

func NewIterm2Backend

func NewIterm2Backend() *Iterm2Backend

func (*Iterm2Backend) Clear

func (i *Iterm2Backend) Clear() error

func (*Iterm2Backend) Close

func (i *Iterm2Backend) Close() error

func (*Iterm2Backend) Display

func (i *Iterm2Backend) Display(key string, img *Image, opts Options) error

func (*Iterm2Backend) Name

func (i *Iterm2Backend) Name() string

type KittyBackend

type KittyBackend struct {
	// contains filtered or unexported fields
}

func NewKittyBackend

func NewKittyBackend() *KittyBackend

func (*KittyBackend) Clear

func (k *KittyBackend) Clear() error

func (*KittyBackend) Close

func (k *KittyBackend) Close() error

func (*KittyBackend) Display

func (k *KittyBackend) Display(key string, img *Image, opts Options) error

func (*KittyBackend) Name

func (k *KittyBackend) Name() string

type Option

type Option func(*Options)

func WithPos

func WithPos(x, y int) Option

func WithSize

func WithSize(w, h int) Option

func WithZIndex

func WithZIndex(z int) Option

type Options

type Options struct {
	Pos
	Size
	ZIndex int
}

type Pos

type Pos struct {
	X, Y int
}

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

func New

func New(opts ...RendererOption) *Renderer

func (*Renderer) Backend

func (r *Renderer) Backend() Backend

func (*Renderer) Clear

func (r *Renderer) Clear() error

func (*Renderer) Close

func (r *Renderer) Close() error

func (*Renderer) Display

func (r *Renderer) Display(path string, opts ...Option) error

func (*Renderer) Name

func (r *Renderer) Name() string

type RendererOption

type RendererOption func(*RendererOptions)

func WithBackend

func WithBackend(b Backend) RendererOption

type RendererOptions

type RendererOptions struct {
	Backend Backend
}

type SixelBackend

type SixelBackend struct {
	// contains filtered or unexported fields
}

func NewSixelBackend

func NewSixelBackend() *SixelBackend

func (*SixelBackend) Clear

func (s *SixelBackend) Clear() error

func (*SixelBackend) Close

func (s *SixelBackend) Close() error

func (*SixelBackend) Display

func (s *SixelBackend) Display(key string, img *Image, opts Options) error

func (*SixelBackend) Name

func (s *SixelBackend) Name() string

type Size

type Size struct {
	Width, Height int
}