cowiconman(1)
cowiconman(1) cowiconman - cow window icon manager cowiconman(1)

cowiconman - CoW Icon Manager

cowiconman [-c config] [-h]

cowiconman displays a clickable list of windows known to cow(1).

Without a configuration file, one icon manager is created using built-in defaults. It shows every window in a single column, sorted by title.

Its configuration can define several named icon managers. Each top-level show iconman line creates a separate cowiconman window.

The window size follows the visible button grid, growing or shrinking as windows enter or leave the list. It is capped to the selected output's usable area.

-c config

Load config instead of the default configuration file.

-h

Show usage.

The format is line-oriented. Blank lines and lines starting with # are ignored. Values containing whitespace must be double quoted.

By default, cowiconman reads cowiconman.conf from $XDG_CONFIG_HOME/cow/cowiconman.conf or ~/.config/cow/cowiconman.conf.

Top-level settings are shared defaults. Named iconman blocks override those defaults for the instances which select them. For example:

show iconman current
show iconman applications

sort title
button-width 240

iconman current {
	output current
	desk current
	page current
}

iconman applications {
	group-by app
	icons true
}

Each show iconman line creates one window. Multiple names on the same line combine those blocks into one instance, in the order in which their definitions occur:

show iconman common current-output

Supported commands are described below.

output VALUE

Limit the list to an output. VALUE may be an output name, @N, @current, @next, or @prev. The existing current alias selects cow's current output, while self selects the output containing the cowiconman window. Use all to clear an inherited output filter. The default is to show all outputs.

desk VALUE

Limit the list to a desk. VALUE may be a desk number or current. Use all to clear an inherited desk filter. The default is to show all desks.

page VALUE

Limit the list to a page. VALUE may be X,Y or current. Use all to clear an inherited page filter. The default is to show all pages.

sort MODE

Sort rows by title, app, id, or leave them in cow's order with none. The default is title.

group-by MODE

Group matching windows into one row. MODE may be none, app, title, output, or desk. The default is none.

match FIELD=TEXT

Only show windows whose FIELD contains TEXT. FIELD may be title, app, or id. Matching is case-insensitive. Repeat the command to add filters. Prefix TEXT with ! to exclude matching windows.

format FMT

Set the row label format. Supported escapes are %t title, %a app_id, %i short window id, %o output, %d desk, and %%. The default is %t.

rows N

Arrange buttons into at most N rows before starting a new column.

columns N

Arrange buttons into N columns. The number of rows is computed from the visible window count.

anchor none|top|bottom

Move the cowiconman window to the selected output's top or bottom usable edge. The default is none.

button-width N

Set the preferred button width in pixels. The default is 300.

button-height N

Override the row height derived from cow's current titlebar theme.

style element colour

Override a palette colour. element is one of background, active.bg, active.fg, inactive.bg, inactive.fg, or iconified.bg. Colours use CoW's RGB or RGBA syntax. Styles may be shared at top level or set separately inside an iconman block.

min-button-width N

Set the minimum button width used when the preferred grid would exceed the output's usable width. The default is 80.

icons true|false

Show each window's application icon before its label. cowiconman uses the icon resolved by cow. The default is false.

icon-size N

Set the application icon size in pixels. The default is 16 and the maximum is 20.

iconified-marker true|false

Reserve space before each label and draw a small square there for iconified windows. The default is false.

show-self true|false

Include cowiconman windows in the list. Hidden by default.

frame-padding N

Add a border of N pixels around the window list. The default is 4.

Without explicit style settings, focused and unfocused rows use CoW's active and inactive titlebar colours. The empty background follows the selected output, and an iconified row uses a darkened inactive background. Explicit styles override these inherited colours; an unset iconified.bg is derived from the effective inactive.bg colour.

Left-click a row to focus the window. If the window is iconified, it is restored and focused.

Left-click a grouped row to open a selector for the windows in that group. The selector is a native cow menu using the current menu style. Its rows include the short window id, output, and desk. Selecting a window switches to its output, desk, and page, activates its container member when necessary, restores it when iconified, and focuses it. Type-ahead is disabled for these selectors; number keys, arrows, Enter, and Escape remain available.

Middle-click a row to toggle the window's iconified state.

Use the pointer wheel to scroll when a fixed row layout has more entries than fit on screen.

An anchored rows 1 layout behaves like a bar: it spans the selected output's usable width and divides that space evenly between entries.

Show windows on the current output, desk, and page in a top task bar:

show iconman taskbar

iconman taskbar {
	output current
	desk current
	page current
	rows 1
	anchor top
	icons true
}

Create a separate grouped list for each of two outputs:

show iconman left
show iconman right

group-by app
format "%a (%t)"

iconman left {
	output HDMI-A-1
}

iconman right {
	output eDP-1
	style active.bg 0x458588
	style active.fg 0xffffff
	style inactive.bg 0x83a598
	style inactive.fg 0x000000
}

Show xterm windows but exclude titles containing "logs":

show iconman terminals

iconman terminals {
	match app=xterm
	match title=!logs
}

Remove cowiconman's own window decors while preserving the active decor theme:

decor -d cowiconman-nodecor border.width 0
decor -d cowiconman-nodecor border.handles false
decor -d cowiconman-nodecor titlebar.enabled false
rule -g -Ton-map -ncowiconman-nodecor -s %cowiconman decor -a cowiconman-nodecor

$XDG_CONFIG_HOME/cow/cowiconman.conf ~/.config/cow/cowiconman.conf

cow(1), moocow(1), cowbuttons(1), cowpager(1)

Thomas Adam <thomas@xteddy.org>

2026-08-28 0.2-34-ge7151ab