Make it yours

Themes

A theme of your own is a file in ~/.config/modisa/themes/<name>.toml, over a built-in or another of yours: any of its twelve colours, and the roles of the chrome (tabs, status row, sidebar, borders, menus, toasts). It applies as soon as you save it. theme = { dark = …, light = … } follows your terminal's background. modisa theme import <file> turns a Ghostty, iTerm2, Alacritty, kitty, Windows Terminal or base16 scheme into one.

inherits = "catppuccin-mocha"
accent = "#f5c2e7"

[roles]
"tab.active" = "bold $bg on $accent"
status = "$fg on #000000"

Formats

The status row, tab labels, pane titles, the terminal's window title and the sidebar's agent rows can each be a format: text with {variables}, {?condition|then|else}, #[styles] and #[click=action] parts.

[status]
left = "#[click=palette]#[bold $accent] modisa #[] {space} {?blocked|#[$blocked]! {blocked} need you|}"
right = "{git.branch}{?git.changes| ●{git.changes}|} #[$dim]{clock:%H:%M}"

[tabs]
format = "{tab.index}:{tab}"
position = "bottom"

[window]
title = "{space} · {name}"

Layout

[sidebar]
position = "right"
sections = ["agents", "plugin:radar", "commands"]
row = ["{icon} {name}", "  {agent} · {state}{?meta.context| · {meta.context}|}"]

[panes]
border = "light_triple_dashed"
title_position = "bottom_center"
dim_unfocused = 0.3

Keys and modes

Keys work without the prefix in [root_keys] (each needs Ctrl or Alt), [actions] names a list of actions to bind as one, and a key mode lets a few keys work alone until Escape.

[root_keys]
"focus-left" = "M-h"
"focus-right" = "M-l"

[actions]
"dev-layout" = ["split-right", "focus-left", "zoom"]

[modes.resize]
enter = "r"
keys = { "resize-left" = "h", "resize-right" = "l" }

Commands

Your own entries in the palette, on keys, with prompts that type or pick.

[[command]]
name = "Switch branch"
key = "B"
run = "git switch {branch}"
in = "background"
prompts = [{ name = "branch", pick = "git branch --format=%(refname:short)" }]

Hooks

Commands that run on events (an agent's state, a pane's exit, a message), and commands that stand in front of what agents do — a message they send, an agent they spawn, keys they type into a pane — and may stop it or change it.

[[hook]]
on = "agent.state"
when = "to == 'blocked'"
run = "say {name} needs you"

[[hook]]
on = "message.send"
run = "~/bin/redact-secrets"   # prints {"body": "…"} to change it, or {"allow": false} to stop it

Notifications and sound

[notify.<agent>] and [sound.<agent>] give one agent its own; [sound] pack names a directory of your own sounds; [notify] unread keeps a tab marked until you look at it; a pane's menu mutes it.

Metadata

Any program can show values in modisa — {meta.context} in a format — with modisa pane meta set context=43%, or the user-variable escape other terminals take.

Profiles

modisa profile export > my-setup.toml puts all of it in one file: config.toml, your themes, and where your plugins came from. modisa profile import <file or URL> shows what it changes and asks first.

Every setting, variable and event: CUSTOMIZE.md.