tmenu

Minimal X11 menu launcher - suckless, auditable, fast.

---

tmenu is a minimal X11 menu launcher written in POSIX C99. It reads a newline-delimited list of items from stdin, lets you filter by typing, and executes the selected entry via /bin/sh -c.

The entire implementation fits in two source files and under 250 lines. The only runtime dependency is Xlib.

---

Contents

• Overview
• Requirements
• Installation
• Usage
• Key Bindings
• Configuration
• Contributing
• Related Projects
• License

---

Overview

tmenu follows the suckless philosophy: small, auditable, compile-time configured. There is no config file parser, no IPC, no scripting layer, and no hidden complexity. Read the source - understand the program.

Key properties:

• Two source files, under 250 lines of C99
• Pure Xlib - no Xft, no Xinerama, no fontconfig
• All settings in tmenu.h, applied at compile time
• Keyboard focus on launch — start typing immediately
• Executes the selected item or typed text directly via /bin/sh -c

Compared to dmenu: no external launcher wrapper required, smaller codebase, no Xft dependency.

Supported platforms: Linux (Arch, Void, Debian), OpenBSD, FreeBSD, NetBSD, macOS (XQuartz), and any POSIX system with X11.

---

Requirements

Dependency	Arch Linux	Debian / Ubuntu
Xlib	libx11	libx11-dev
C compiler	gcc	build-essential

No other libraries are needed at runtime.

---

Installation

From source

git clone https://github.com/tinyopsec/tmenu
cd tmenu
make
sudo make install

Installs to /usr/local/bin/tmenu. To change the install prefix:

sudo make install PREFIX=/usr

AUR (Arch Linux)

yay -S tmenu

Uninstall

sudo make uninstall

---

Usage

Pipe a newline-delimited list of items to tmenu on stdin:

# Use the bundled launcher script
tmenu_run

# Or pipe items manually
printf "st\ndmenu_run\nfirefox\n" | tmenu

Navigate with arrow keys or filter by typing. Press Enter to execute the selected item. If the typed text does not match any item, Enter executes it directly as a shell command.

Command-line options

Option	Description
-b	Show menu at the bottom of the screen (default: top)
-l N	Show a vertical list with N visible lines
-p text	Display a prompt to the left of the input field
-v	Print version string and exit

Examples

Vertical list with a prompt:

printf "st\nfirefox\nthunderbird\n" | tmenu -p "run: " -l 5

Bottom-aligned horizontal menu:

printf "suspend\nreboot\npoweroff\n" | tmenu -b -p "power: "

---

Key Bindings

Key	Action
Enter / KP_Enter	Execute selected item or typed text
Escape	Exit without executing
BackSpace	Delete character left of cursor
Up / Left	Move selection up or left
Down / Right	Move selection down or right
Ctrl+U	Clear entire input field
Ctrl+W	Delete one word left of cursor
Ctrl+K	Select next item (vertical list)
Ctrl+J	Select previous item (vertical list)

Key handling is a sthttps://github.com/tinyopsec/tmenuraightforward switch in tmenu.c. To remap keys, edit the source and recompile.

---

Configuration

tmenu has no runtime configuration file. All settings are defined as macros in tmenu.h and take effect after recompilation:

$EDITOR tmenu.h
make && sudo make install

Available settings

Setting	Default	Description
FONT	"-*-fixed-medium-r-*-*-13-*-*-*-*-*-*-*"	X11 core font string
FGNORM	"#bbbbbb"	Normal item foreground color
BGNORM	"#222222"	Normal item background color
FGSEL	"#eeeeee"	Selected item foreground color
BGSEL	"#005577"	Selected item background color
TOP	1	1 = top of screen, 0 = bottom
LINES	0	Default line count (0 = horizontal)
PROMPT	NULL	Default prompt string

To increase the maximum number of items or input length, adjust MAXITEMS and MAXTEXT in tmenu.c.

---

Contributing

Bug reports and patches are welcome via GitHub issues and pull requests.

Code style

• No comments in production code
• No external dependencies beyond Xlib
• No unnecessary abstraction
• Compiles clean: gcc -std=c99 -pedantic -Wall -Wextra
• Total source must remain under 300 lines

Features are added by patching the source, not by adding runtime options. Changes that require a config file or a new library dependency will not be accepted.

---

Related Projects

Project	Description	Link
dmenu	The original dynamic menu for X	suckless.org
suckless.org	Philosophy and tooling behind tmenu	suckless.org
Xlib manual	Reference for X11 programming	x.org

---

Star History

License

MIT. See LICENSE for details.