Anatomy of rc.lua
The default rc.lua (called kilnrc.lua in the source tree) is a complete
desktop in about 1000 lines of Lua, written against the public API only: one
require, no compositor internals. Open your copy alongside (see
First Launch for where it lives). The
screenshots were captured from an earlier build.
The require line and the globals
local kiln = require("kiln")
local ui, key, rule, button = kiln.ui, kiln.key, kiln.rule, kiln.button
local widgets = kiln.widgets
local th = kiln.theme
kiln.modkey = "super"
require("kiln") is the whole import. It returns the kiln module: functions
(kiln.spawn, kiln.quit, kiln.dirty), submodules (kiln.ui,
kiln.layout, kiln.placement, kiln.widgets), the theme table, and the
binding constructors key, button, rule. The locals are just shorthand.
kiln.modkey is what the string "mod" resolves to in every key and button
spec below; it is read at each key{} and button{} call. The stdlib default
is alt; the shipped config picks super.
Beyond the module, a config sees seven globals: client, screen, tag,
layer, drag, notification (the object classes and buses), and core
(the native compositor boundary, which a normal config never needs). See
The object model.
Errors first
The config registers an error listener first:
kiln.on("error", function(_, err)
kiln.notify { urgency="critical", title="Oops, an error happened!", message=tostring(err) }
end)
Binding, listener, rule and spawn callback errors produce a critical notification through this handler. Bar, layout and direct timer errors are log-only. See error reporting.
Theme and its persistence
The theme section defines three inline palettes, each mapping the same nine keys:
local palettes = {
gruvbox = {
bg = "#282828", bg2 = "#1d2021", fg = "#ebdbb2", accent = "#83a598",
muted = "#665c54", titlebar = "#3c3836", titlebar_focus = "#504945",
close = "#cc241d", urgent = "#d79921",
},
catppuccin = {
bg = "#1e1e2e", bg2 = "#313244", fg = "#cdd6f4", accent = "#cba6f7",
muted = "#6c7086", titlebar = "#1e1e2e", titlebar_focus = "#313244",
close = "#f38ba8", urgent = "#f38ba8",
},
nord = {
bg = "#2e3440", bg2 = "#272c36", fg = "#eceff4", accent = "#88c0d0",
muted = "#4c566a", titlebar = "#3b4252", titlebar_focus = "#434c5e",
close = "#bf616a", urgent = "#ebcb8b",
},
}
The chosen name persists in one file, read back at the top of every run:
local theme_name = "catppuccin"
do
local f = io.open(theme_file, "r")
if f ~= nil then
local name = f:read("*l")
if name ~= nil and name ~= "" and palettes[name] ~= nil then
theme_name = name
end
f:close()
end
end
for k, v in pairs(palettes[theme_name]) do
th[k] = v
end
Switching is a write plus a reload. The write is synchronous on purpose: the reload re-runs this whole file, and the re-run has to see the new name.
local function switch_theme(name)
os.execute("mkdir -p -- " .. shell_quote(theme_dir))
local f = io.open(theme_file, "w")
if f ~= nil then
f:write(name .. "\n")
f:close()
end
kiln.reload()
end

There is no theme framework behind this: th is a plain table the stdlib
reads, and a palette is nine writes into it. See
Theming and the
theme variable reference.
Assets: the config makes its own images
The desktop's look is made of images: line-art glyphs for the layoutbox, the
titlebar buttons, the menu rows and the submenu chevron, plus a gradient
wallpaper with the logo centered on it. The renderer draws only rectangles,
borders, text and images. The config writes SVG strings, renders them to
cached PNGs with rsvg-convert through kiln.asset, and declares the PNGs
as image leaves (image = { path }).
The glyph set
Every glyph is a 24x24 viewBox drawn with a 2px round-capped stroke, so a new entry matches the others:
local glyph_body = {
close = '<path d="M6 6 18 18"/><path d="M18 6 6 18"/>',
move = '<path d="M12 3v18"/><path d="M3 12h18"/>' ..
'<path d="m9 6 3-3 3 3"/><path d="m9 18 3 3 3-3"/>' ..
'<path d="m6 9-3 3 3 3"/><path d="m18 9 3 3-3 3"/>',
maximize = '<path d="M4 9V4h5"/><path d="M15 4h5v5"/>' ..
'<path d="M20 15v5h-5"/><path d="M9 20H4v-5"/>',
chevron = '<path d="m10 6 6 6-6 6"/>',
The table continues with one shape per layout family, one per menu row, and
the three titlebar buttons. glyph_svg wraps a body in the shared <svg>
envelope with the stroke color filled in:
local GLYPH_PX = 64
local function glyph_svg(name, color)
return string.format(
'<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" ' ..
'viewBox="0 0 24 24" fill="none" stroke="%s" stroke-width="2" ' ..
'stroke-linecap="round" stroke-linejoin="round">%s</svg>',
color, glyph_body[name])
end
The rendering is batched: want(name, color) lists every name-and-color pair
the config will need (the color is part of the file, so the titlebar's two ink
states are two entries), then the config requests them all and flushes once.
All glyphs render in one rsvg-convert batch at load; the wallpaper renders
once per output size and scale.
local G = {}
for _, u in ipairs(glyph_use) do
local svg = glyph_svg(u[1], u[2])
u[3] = asset.request(u[1], GLYPH_PX, GLYPH_PX, svg)
end
asset.flush()
for _, u in ipairs(glyph_use) do
G[u[1]] = G[u[1]] or {}
G[u[1]][u[2]] = asset.path(u[3]) or false
end
local function glyph(name, color)
local by = G[name]
return (by ~= nil and by[color]) or nil
end
glyph(name, color) returns a readable PNG path, or nil. nil is not an
error: every call site is written to take it. Every glyph rasterizes at 64px
(GLYPH_PX) and downscales into its cell, which stays sharp at 1x and 2x
both. On a system without rsvg-convert the desktop degrades to text and
colored blocks instead of erroring.
The wallpaper
The wallpaper uses the same trick at screen size: the theme gradient corner to corner, the kiln mark centered on it, generated at the screen's physical pixel count so the ramp is free of banding and the mark stays true under any scale.

The wallpaper cache key is the physical size and the scale:
local dims = w .. "x" .. h
local hit = wallpapers[dims .. "@" .. scale]
if hit ~= nil then
return hit or nil
end
The scale has to be in the key even though the pixel count already is: a pure
scale change on a fixed mode leaves the physical size alone (logical shrinks
by exactly what the scale grew), so a size-only key would serve the old
picture, whose mark was sized for the old scale. The rest of the function
builds one SVG string (gradient, then a nested <svg> carrying the logo's own
viewBox, so every number written into the document is an integer) and hands it
to asset.svg, memoized per size and scale.
The wallpaper guide rebuilds the pattern in isolation.
Defaults and one history list
local terminal = os.getenv("TERMINAL") or "foot"
local editor = os.getenv("EDITOR") or "nano"
local editor_cmd = terminal .. " -e " .. editor
local conffile = (debug.getinfo(1, "S").source:match("^@(.+)$")) or "kilnrc.lua"
local eval_history = {}
conffile is the config file's own path, read off the running chunk; it feeds
the "edit config" menu item. eval_history keeps the Lua prompt's history out
of the shared run-command history.
Helpers the bindings and widgets share
Nine plain functions, all public-API arithmetic. The two the rest depend on
are view_relative, which views the tag delta steps from the current
selection, wrapping (shared by the arrow keys, the taglist scroll and the
backdrop wheel), and visible_union, which returns the screen's visible
client stack in declare order, deduped: clients on selected tags, then sticky
clients. It is the basis for focus and swap by index.
local function view_relative(s, delta)
local sel = s.selected_tag
if sel == nil or #s.tags == 0 then
return
end
for i, t in ipairs(s.tags) do
if t == sel then
s.tags[(i - 1 + delta) % #s.tags + 1]:view()
return
end
end
end
local function visible_union(s)
local out, seen = {}, {}
for _, t in ipairs(s.tags) do
if t.selected then
for _, c in ipairs(t.clients) do
if not seen[c] and c.mapped and not c.minimized
and not c.override_redirect then
seen[c] = true
out[#out + 1] = c
end
end
end
end
for _, t in ipairs(s.tags) do
for _, c in ipairs(t.clients) do
if c.sticky and not seen[c] and c.mapped and not c.minimized then
seen[c] = true
out[#out + 1] = c
end
end
end
return out
end
On top of visible_union sit focus_byidx and swap_byidx (walk the stack
by index, wrapping), and focus_screen_relative (jump to the next monitor's
most recent client). Beside them: layout_prev (because kiln.layout.next
has no prev twin), restore_minimized (unminimize the most recently minimized
client on a selected tag), jump_urgent (view the urgent client's tag and
focus it), and path_bins (the $PATH executable list for the run prompt's
completion, memoized, shelled to ls because Lua has no readdir).
The layout cycle
kiln.layout.list = {
kiln.layout.tile,
kiln.layout.tile.left,
kiln.layout.tile.bottom,
kiln.layout.tile.top,
kiln.layout.carousel,
kiln.layout.fair,
kiln.layout.fair.horizontal,
kiln.layout.max,
kiln.layout.corner.nw,
kiln.layout.floating,
kiln.layout.spiral,
kiln.layout.dwindle,
kiln.layout.magnifier,
}
This is the cycle mod+space walks. No fullscreen layout is in it by
construction: fullscreen is a client property (c:toggle_fullscreen()), not a
tiling arrangement. See the layout reference.
The menu
Menu items are { label, action } pairs. A table as the second element nests
a submenu, and icon = <path> renders a leading image cell:
local function menu_items(s)
return {
{ "hotkeys", icon = glyph("keys", th.fg), function()
kiln.hotkeys.show(s)
end },
{ "terminal", icon = glyph("terminal", th.fg),
function() kiln.spawn(terminal) end },
{ "theme", icon = glyph("palette", th.fg), {
{ "gruvbox", function() switch_theme("gruvbox") end },
{ "catppuccin", function() switch_theme("catppuccin") end },
{ "nord", function() switch_theme("nord") end },
} },
{ "edit config", icon = glyph("edit", th.fg), function()
kiln.spawn(editor_cmd .. " " .. shell_quote(conffile))
end },
{ "lock", icon = glyph("lock", th.fg), kiln.lock },
{ "restart", icon = glyph("restart", th.fg), kiln.reload },
{ "quit", icon = glyph("power", th.fg), kiln.quit },
}
end
th.menu_submenu_icon = glyph("chevron", th.muted)
local function main_menu(s)
return {
{ "kiln", icon = glyph("palette", th.fg), menu_items(s) },
{ "open terminal", icon = glyph("terminal", th.fg),
function() kiln.spawn(terminal) end },
}
end
The chevron line is the whole wiring for submenu markers: the stdlib menu
renders th.menu_submenu_icon as an image when it is set and keeps its text
> when it is not. The main menu opens from three places: the launcher glyph
in the bar, mod+w, and a right-click on the desktop.

See Menus.
The app launcher: one replaced filter
mod+p opens kiln.launcher: every installed .desktop application behind a
type-to-filter entry. The launcher itself is stdlib; what stays in the config
is the one thing about it that is this desktop's choice rather than the
stdlib's, the ranking:
local default_rank = kiln.launcher.default_filter
kiln.launcher.filter = function(text)
local out, term = {}, {}
for _, a in ipairs(default_rank(text)) do
if a.exec:sub(1, #terminal) == terminal then
term[#term + 1] = a
else
out[#out + 1] = a
end
end
for _, a in ipairs(term) do
out[#out + 1] = a
end
return out
end
launcher.filter is the whole extension point: this override keeps the
stdlib's ranking and moves terminal apps to the end of it, because a launcher
opened by keyboard is usually not reaching for one. The exec test is a plain
prefix compare, not a pattern: terminal comes from $TERMINAL, and a dash in
it would be a Lua pattern metacharacter. The
app launcher guide builds the idea up from parts.
The bar widgets
The bar's widgets are hand-rolled wrappers over
kiln.widgets. The stock
widgets.taglist/widgets.tasklist/widgets.layoutbox wire only the one
gesture they can name; these wrappers pass an
on = { press = ..., scroll = ... } table that branches on the press button
and modifiers. A handler that returns a truthy value preempts the stock
behavior; falling off the end declines to it.
The launcher glyph
The blocky "s" in the bar's corner is not an image. It is a Clay-composed square in the accent color with two thin cuts floated over it in the bar color, at one third and two thirds of its height:
local function launcher_glyph(s)
local size = th.bar_height - 4
local cut = math.max(1, math.floor(size / 9))
ui.box({
id = "launcher",
w = size, h = size, color = th.accent, radius = 2, align = "center",
on_press = function()
if kiln.menu.open ~= nil then
kiln.menu.close()
else
kiln.menu.show { under = "launcher", screen = s,
items = main_menu(s) }
end
end,
}, function()
ui.box({
float = { to = "parent",
anchor = { parent = "right_top", element = "right_top" },
offset = { x = 0, y = math.floor(size / 3) } },
w = math.floor(size * 2 / 3), h = cut, color = th.bg,
})
ui.box({
float = { to = "parent",
anchor = { parent = "left_top", element = "left_top" },
offset = { x = 0, y = math.floor(size * 2 / 3) } },
w = math.floor(size * 2 / 3), h = cut, color = th.bg,
})
end)
end
Pressing it toggles the main menu, anchored under the element by id:
kiln.menu.show { under = "launcher", ... }.
The taglist
The widget declares the cells, the squares and the plain-click default. Only the added gestures live here:
local function taglist(s)
widgets.taglist(s, { on = {
press = function(t, ev)
local mod = ev ~= nil and ev.mods ~= nil and ev.mods[kiln.modkey]
local btn = (ev ~= nil and ev.button) or 1
local c = client.focus
if btn == 1 and mod then
if c ~= nil then
c.tags = { t }
end
return true
elseif btn == 3 and mod then
if c ~= nil then
local nt, has = {}, false
for _, tt in ipairs(c.tags) do
if tt == t then
has = true
else
nt[#nt + 1] = tt
end
end
if not has then
nt[#nt + 1] = t
end
if #nt > 0 then
c.tags = nt
end
end
return true
elseif btn == 3 then
t:toggle()
return true
end
end,
scroll = function(ev)
view_relative(s, (ev.dy or 0) > 0 and 1 or -1)
end,
} })
end
A plain left press is not handled, so the stdlib default views the tag.
The tasklist
local function tasklist(s)
widgets.tasklist(s, {
filter = function(c, sc)
if c.sticky then
return true
end
return widgets.filter.currenttags(c, sc)
end,
on = {
press = function(c, ev)
local btn = (ev ~= nil and ev.button) or 1
if btn == 3 then
kiln.menu.client_list { screen = s }
return true
elseif c == client.focus then
c.minimized = true
return true
end
end,
scroll = function(ev)
focus_byidx((ev.dy or 0) > 0 and 1 or -1)
end,
},
})
end
A left press on any row but the focused one is not handled, so the stdlib default unminimizes and focuses it. The filter adds sticky clients to the default predicate.
The layoutbox
The cell draws a glyph rather than the layout's name. The glyphs reach the
widget the way the menu chevron does, as a theme key, keyed by layout
family, so every variant of tile shares the tile glyph:
th.layout_icons = {}
for family, name in pairs(layout_glyph) do
th.layout_icons[family] = glyph(name, th.fg)
end
local function layoutbox(s)
widgets.layoutbox(s, { on = {
press = function(t, ev)
if ev ~= nil and ev.button == 3 then
t.layout = layout_prev(t.layout)
return true
end
end,
scroll = function(ev)
local sel = s.selected_tag
if sel == nil then
return
end
if (ev.dy or 0) > 0 then
sel.layout = kiln.layout.next(sel.layout)
else
sel.layout = layout_prev(sel.layout)
end
end,
} })
end
A plain left press is not handled, so the stdlib default steps forward. The widget falls back to its text label for any family the table does not name.
The backdrop
The wallpaper enters the tree here: one image leaf floated to root in the
background band. It also carries the root wheel binding, so a scroll over
empty desktop walks the tags. The screen.on("changed") line above it
re-renders the wallpaper when an output's size or scale changes.
screen.on("changed", function(s) wallpaper(s) end)
local function backdrop(s)
local wp = os.getenv("KILN_WALLPAPER")
if wp == nil or wp == "" then
wp = wallpaper(s)
end
ui.box({
id = "backdrop",
float = { to = "root", band = "background", passthrough = true },
w = "grow", h = "grow",
color = (wp == nil or wp == "") and th.bg or nil,
image = (wp ~= nil and wp ~= "") and { path = wp } or nil,
on_scroll = function(ev)
view_relative(s, (ev.dy or 0) > 0 and 1 or -1)
end,
})
end
passthrough = true is not decoration: a background float defaults to
capture, and a captured full-screen root float would sit over the bar's
in-flow widgets in Clay's pointer test, taking clicks meant for the bar.
Passthrough keeps the bar hittable while the backdrop still catches the wheel
over empty desktop. The theme color is written only when no wallpaper
resolved, because a color on an image box tints the image.
KILN_WALLPAPER wins when set; with no wallpaper, the box is filled with
th.bg.
Titlebars
The stock widgets.titlebar draws icon, title, maximize and close. This
config overrides it with a version that adds the floating toggle, keeping the
stock ids ({"close", c.handle} etc.) so code that looks buttons up by id
still works. widgets.client calls widgets.titlebar through the module
table, so the override is a public-symbol swap, zero stdlib edits.
local function titlebar_button(id, name, color, press)
ui.box({
id = id, w = 14, h = 14, radius = 2, align = "center",
on_press = press,
}, function()
local g = glyph(name, color)
if g ~= nil then
ui.image(g, { w = 12, h = 12 })
else
ui.box({ w = 12, h = 12, color = color, radius = 2 })
end
end)
end
kiln.widgets.titlebar = function(c, focused)
ui.row({
id = { "titlebar", c.handle },
w = "grow", h = th.titlebar_height,
color = focused and th.titlebar_focus or th.titlebar,
pad = { x = 4 }, gap = 4, align = { y = "center" },
on_press = function(ev)
c:focus()
if ev ~= nil and ev.button == 3 then
c:grab_resize_nearest()
else
c:grab_move()
end
end,
}, function()
local ic = kiln.icon.client(c)
if ic ~= nil then
ui.image(ic, { w = 12, h = 12 })
else
ui.box({ w = 12, h = 12, color = th.accent, radius = 2 })
end
ui.box({ w = "grow", align = "center", clip={horizontal=true} }, function()
ui.text(c.title or c.app_id or "",
{ color = focused and th.fg or th.muted, ellipsize=true })
end)
local ink = focused and th.fg or th.muted
titlebar_button({ "float", c.handle }, "move", ink, function()
c.floating = not c.floating
end)
titlebar_button({ "maximize", c.handle }, "maximize", ink,
function() c:toggle_maximized() end)
titlebar_button({ "close", c.handle }, "close", th.close,
function() c:close() end)
end)
end

When no glyph rendered, titlebar_button falls back to a plain colored block,
because a pressable button has to be visible. The title sits in one growing,
clipped cell and is ellipsized, so a long title cannot push the buttons off a
narrow client. A press focuses the client, then left drags and right resizes
from the nearest corner. The line-art ink follows focus, and the two colors
are two glyph cache entries, because the color is part of the file.
The screen: tags and the bar
Everything per-screen happens in one handler:
screen.on("added", function(s)
tag.new { name = "dev", screen = s, layout = kiln.layout.tile }
tag.new { name = "web", screen = s, layout = kiln.layout.tile }
tag.new { name = "chat", screen = s, layout = kiln.layout.tile }
tag.new { name = "files", screen = s, layout = kiln.layout.tile }
tag.new { name = "media", screen = s, layout = kiln.layout.tile }
s.tags[1]:view()
wallpaper(s)
ui.bar(s, { edge = "top", dir = "row", h = th.bar_height,
color = th.bg, pad = { x = 8 } }, function()
backdrop(s)
ui.row({ w = "33.33%", h = "grow", gap = 6,
clip = { horizontal = true },
align = { y = "center" } }, function()
launcher_glyph(s)
taglist(s)
tasklist(s)
end)
ui.row({ w = "33.33%", h = "grow", align = "center" }, function()
ui.box({ id = "clock", color = th.bg2, radius = 4,
pad = { x = 8 },
on_hover = ui.tooltip(function()
return os.date("%A %d %B %Y")
end),
}, widgets.clock)
end)
ui.row({ w = "33.33%", h = "grow", gap = 6,
clip = { horizontal = true },
align = { x = "right", y = "center" } }, function()
widgets.systray()
layoutbox(s)
end)
end)
end)
screen.on("added") fires once per output, at boot and whenever a monitor is
plugged in, so tags and bars exist on every screen without special-casing
multi-monitor. tag.new creates a tag with a layout; t:view() selects it.
The wallpaper(s) call warms the render outside the frame path; backdrop()
would ask again and memoize either way.
ui.bar(s, cfg, fn) registers a bar whose fn is a declare function: it runs
again on every dirty frame and states what the bar contains right now. The
body is three percent-third regions in a row. The thirds are the centering
mechanism: Clay sizes a percent child unconditionally, so the middle region's
center is the bar's center however wide the tasklist gets, and the side
regions clip so an overfull tasklist truncates at its third instead of pushing
into the middle. Nothing floats and nothing computes a position.

The clock is a plain box in the middle region; ui.tooltip(fn) returns its
on_hover handler:
The full build-up of a bar like this one is A bar from scratch.
Key bindings
Every binding is one key{} call: mods, key, a press handler, plus desc and
group. The sheet on mod+s is stdlib (kiln.hotkeys.toggle); it reads the
same registry these calls fill, so the desc and group on every binding below
are the whole of what the config contributes to it:

The groups:
kiln
Session verbs, most of them one-line bindings to stdlib functions:
key { mods = { "mod" }, key = "s", desc = "show help", group = "kiln",
press = kiln.hotkeys.toggle }
key { mods = { "mod" }, key = "w", desc = "show main menu", group = "kiln",
press = function()
local s = screen.focused
kiln.menu.show { under = "launcher", screen = s, items = main_menu(s) }
end }
key { mods = { "mod", "ctrl" }, key = "r", desc = "reload kiln", group = "kiln",
press = kiln.reload }
key { mods = { "mod", "shift" }, key = "q", desc = "quit kiln", group = "kiln",
press = kiln.quit }
Three more bindings in this group sit at the very end of the file:
key {mods={"alt"},key="Escape",desc="quit kiln",group="kiln",press=kiln.quit}
key {mods={"mod","shift"},key="Escape",desc="lock screen",group="kiln",press=kiln.lock}
key { mods = { "mod", "shift" }, key = "i", desc = "toggle clay inspector",
group = "kiln", press = function() kiln.inspector() end }
alt+Escape quits without the modkey. The inspector is Clay's own debug panel over the live desktop;
it takes 400px off the right of the screen while it is up, so the desktop
reflows into what is left rather than being covered (see
Inspect the Live Element Tree).
mod+x is a Lua prompt against the running compositor. Try an expression
first, fall back to a statement, notify the result either way:
key { mods = { "mod" }, key = "x", desc = "lua execute prompt", group = "kiln",
press = function()
kiln.prompt.run {
label = "Run Lua code: ",
history = eval_history,
done = function(str)
if str == "" then
return
end
local chunk, cerr = loadstring("return " .. str)
if chunk == nil then
chunk = loadstring(str)
end
if chunk == nil then
kiln.notify { title="Lua error", message=tostring(cerr) }
return
end
local ok, res = pcall(chunk)
kiln.notify { title=ok and "=" or "Lua error", message=tostring(res) }
end,
}
end }
Notifications sent while notification.suspended is true are queued. So
enabling do-not-disturb sends the confirmation before suspending, and
disabling unsuspends (flushing the queue) before confirming:
key { mods={"mod","shift"}, key="d", desc="toggle do-not-disturb", group="kiln",
press=function()
if notification.suspended then
notification.suspended=false
kiln.notify {title="Notifications",message="Resumed",timeout=2}
else
kiln.notify {title="Notifications",message="Do Not Disturb",timeout=2}
notification.suspended=true
end
end }
launcher
key { mods = { "mod" }, key = "Return", desc = "open a terminal", group = "launcher",
press = function() kiln.spawn(terminal) end }
key { mods = { "mod" }, key = "r", desc = "run prompt", group = "launcher",
press = function()
kiln.prompt.run {
label = "Run: ",
completion = kiln.prompt.completion(function() return path_bins() end),
done = function(cmd)
if cmd ~= "" then
kiln.spawn(cmd)
end
end,
}
end }
key { mods = { "mod" }, key = "p", desc = "show the menubar", group = "launcher",
press = function() kiln.launcher.open() end }
tag
The arrows walk tags through view_relative; mod+Escape restores the
previous selection through tag.history; mod+shift+r renames the current
tag through a prompt pre-filled with its name:
key { mods = { "mod" }, key = "Left", desc = "view previous", group = "tag",
press = function() view_relative(screen.focused, -1) end }
key { mods = { "mod" }, key = "Right", desc = "view next", group = "tag",
press = function() view_relative(screen.focused, 1) end }
key { mods = { "mod" }, key = "Escape", desc = "go back", group = "tag",
press = function() tag.history.restore(screen.focused) end }
Then the numrow. "1-9" is a range: one key{} call expands to nine chords,
and the handler receives the index. Four Mod variants cover the whole
tag-number vocabulary:
key { mods = { "mod" }, key = "1-9", desc = "only view tag", group = "tag",
press = function(i)
local t = screen.focused.tags[i]
if t ~= nil then
t:view()
end
end }
mod+ctrl+1-9 toggles the tag into the selection, mod+shift+1-9 moves the
focused client to it, and mod+ctrl+shift+1-9 toggles the focused client onto
it with the same add-or-remove loop the taglist's mod+right-click uses.
client and screen
Focus and swap walk visible_union by index; mod+Tab jumps through the
focus history:
key { mods = { "mod" }, key = "j", desc = "focus next by index", group = "client",
press = function() focus_byidx(1) end }
key { mods = { "mod" }, key = "k", desc = "focus previous by index", group = "client",
press = function() focus_byidx(-1) end }
key { mods = { "mod" }, key = "Tab", desc = "go back", group = "client",
press = function()
local c = client.history.previous()
if c ~= nil then
c:focus()
c:raise()
end
end }
key { mods = { "mod" }, key = "u", desc = "jump to urgent client", group = "client",
press = jump_urgent }
mod+shift+j and mod+shift+k are the swap twins, and mod+ctrl+n restores
the most recently minimized client. The screen group is two bindings over
focus_screen_relative.
audio, brightness, screenshot
The media keys shell out; every kiln.spawn string runs via /bin/sh -c:
key { mods = {}, key = "XF86AudioRaiseVolume", desc = "raise volume", group = "audio",
press = function() kiln.spawn("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+") end }
Volume and mute use wpctl, brightness uses brightnessctl, and screenshots
use grim:
key { mods = {}, key = "Print", desc = "screenshot full output", group = "screenshot",
press = function()
kiln.spawn(
"mkdir -p ~/Pictures && grim ~/Pictures/screenshot-$(date +%Y%m%d-%H%M%S).png")
end }
The "interactive screenshot" chord (mod+ctrl+p) is the same
slurp | grim -g - region pipeline the Shift+Print binding uses. slurp
draws the selection and grim captures it; there is no compositor overlay.
layout
The tiling knobs are tag properties, so every handler is a property write on
screen.focused.selected_tag:
key { mods = { "mod" }, key = "l", desc = "increase master width factor",
group = "layout",
press = function()
local t = screen.focused.selected_tag
if t ~= nil then
t.master_width_factor = math.min(0.95,
(t.master_width_factor or 0.5) + 0.05)
end
end }
mod+h decreases it; mod+shift+h/l walk master_count, mod+ctrl+h/l walk
column_count, and mod+space / mod+shift+space walk the layout cycle
declared above. Layout-by-number is nine explicit numpad bindings, generated
in a loop because key ranges only expand single digits or letters:
for i = 1, 9 do
key { mods = { "mod" }, key = "KP_" .. i, desc = "select layout " .. i,
group = "layout",
press = function()
local t = screen.focused.selected_tag
if t ~= nil then
t.layout = kiln.layout.list[i] or t.layout
end
end }
end
per-client verbs
All wrapped in kiln.focused, which runs the verb on the focused client or
no-ops:
key { mods = { "mod" }, key = "f", desc = "toggle fullscreen", group = "client",
press = kiln.focused(function(c)
c:toggle_fullscreen()
c:raise()
end) }
key { mods = { "mod", "shift" }, key = "c", desc = "close", group = "client",
press = kiln.focused(function(c) c:close() end) }
key { mods = { "mod", "ctrl" }, key = "space", desc = "toggle floating",
group = "client",
press = kiln.focused(function(c)
c.floating = not c.floating
end) }
key { mods = { "mod", "ctrl" }, key = "Return", desc = "move to master",
group = "client",
press = kiln.focused(function(c)
local s = (c.tag ~= nil and c.tag.screen) or screen.focused
if s == nil then
return
end
for _, o in ipairs(visible_union(s)) do
if o ~= c and not o.floating then
c:swap(o)
return
end
end
end) }
c:close() asks politely; c:kill() is SIGKILL, and no chord binds it. The
rest of the group is one-line property toggles: move to screen (mod+o), keep
on top (mod+t), sticky (mod+comma), minimize (mod+n), maximize
(mod+m).
Maximized is one boolean, so the per-axis chords both toggle the same state:
key { mods = { "mod", "ctrl" }, key = "m", desc = "(un)maximize vertically",
group = "client",
press = kiln.focused(function(c)
c:toggle_maximized()
c:raise()
end) }
mod+shift+m ("horizontally") is the same handler. The
keybindings tutorial covers the key{}
mechanism from scratch.
Mouse bindings
button { mods = {}, button = 3, on = "root", press = function()
local s = screen.focused
if kiln.menu.open ~= nil then
kiln.menu.close()
else
kiln.menu.show { under = "launcher", screen = s, items = main_menu(s) }
end
end }
button { mods = { "mod" }, button = 1, press = function(c) c:grab_move() end }
button { mods = { "mod" }, button = 3,
press = function(c) c:grab_resize_nearest() end }
Root right-click toggles the main menu, opened at the launcher anchor rather
than the pointer, because a button handler receives only the client (nil on
the root), not the pointer position. The root wheel is not here: it is
handled by the backdrop's on_scroll, declared with the wallpaper. Plain
left-click on a client focuses (the built-in default); mod+left drags;
mod+right resizes from the nearest corner.
Rules
Three rule{} calls: global placement, floating apps, and routing for nested
compositors.
rule { match = { fn = function() return true end },
on = function(c)
kiln.placement.no_overlap(c)
kiln.placement.no_offscreen(c)
end }
rule { match_any = {
app = { "pinentry", "Blueman%-manager", "Gpick" },
instance = { "pinentry" },
class = { "Blueman%-manager", "Gpick" },
role = { "pop%-up" },
},
props = { floating = true } }
rule { match_any = { app = { "^kiln$" }, class = { "^kiln$" } },
props = { tag = "media", focus = false } }
Rules run when a client maps: selectors (match, match_any, except)
against app, class, instance, title, role, dialog, or an arbitrary
predicate; props are property writes; on is a callback. Note:
- An empty match clause matches nothing, because a fire-on-everything rule
is a mistake worth catching. "All clients" is therefore spelled
match = { fn = function() return true end }. - Apps are named in both their Wayland (
app) and X11 (class/instance) forms, so the rule fires whichever way the client arrives. The dash inpop-upis escaped because a rule string is a Lua pattern. - A tag assignment does not switch the view.
focus = falsesuppresses focus on map; later activation requests use a separate policy.
Titlebars need no rule: they are on by default and opted out per client with
titlebar = false. See Client rules.
What is deliberately not here
The config does not configure notifications or replace any of the ten
kiln.defaults.* functions; the stdlib defaults apply. Its only added policy
is focus-follows-mouse:
client.on("mouse::enter", function(c) c:focus() end)
Focus follows the mouse, and focus does not raise. Swapping a default
wholesale is the same shape in reverse:
client.off("request::activate", kiln.defaults.activate), then client.on
with your own. See
Replace default policies and the
defaults reference.
Where to go next
Work through the tutorials in order:
- Basics: drive the stock desktop, then reload a change
- Keybindings
- A bar from scratch
- Widgets
- Theming