Configuration

Configuration

Mado reads ~/.config/mado/config.toml on startup. The file does not need to exist on first launch — all settings have sensible defaults and Mado will run without it. Once you want to change the theme, font, keybindings, or add plugins, run mado config to create it and open it in your editor.

To create the file with commented defaults, run:

mado config

This creates ~/.config/mado/config.toml if it does not exist and opens it in your editor ($VISUAL / $EDITOR, or vi as a fallback).

Live reload

Most settings take effect as soon as you save the file — no restart needed. Mado watches ~/.config/mado/ and picks up changes automatically, including saves from editors that write atomically (VS Code, vim, etc.).

Settings that reload live:

Setting	Notes
theme	Colours update immediately across all panes and panels
theme_starship	Rewrites ~/.config/mado/starship.toml on save
font_size	All panes reflow at the new size
sidebar_width / right_sidebar_width	Sidebar resizes instantly
top_bar_height	Top bar resizes instantly
top_right_panel_width / bottom_right_panel_width / browser_panel_width	Panel widths update instantly
show_bottom_bar	Bottom bar appears or disappears

Settings that require a restart: plugins, shell, font_family, tasku_position, disable_*.

---

Full reference

# ── Appearance ─────────────────────────────────────────────────────────────────

theme          = "gray"    # built-in theme name or a name from ~/.config/mado/themes/
font_size      = 18.0      # terminal font size in points
font_family    = ""        # system font name; leave empty for bundled Hack Nerd Font Mono

# ── Shell ──────────────────────────────────────────────────────────────────────

shell          = ""        # leave empty to use $SHELL

# ── Layout ─────────────────────────────────────────────────────────────────────

sidebar_width        = 380.0   # left sidebar width in logical pixels
right_sidebar_width  = 300.0   # right sidebar width in logical pixels
top_bar_height       = 200.0   # height of the top-bar Tasku overlay in logical pixels
show_bottom_bar      = false   # show the task-runner bar at the bottom

top_right_panel_width    = 600.0
bottom_right_panel_width = 300.0
browser_panel_width      = 600.0

# ── Built-in panels ────────────────────────────────────────────────────────────

tasku_position     = "top"    # "top" (overlay), "left" (sidebar), or "right" (sidebar)
disable_tasku      = false
disable_priorities = false
disable_workspaces = false

# ── Starship integration ───────────────────────────────────────────────────────

theme_starship = false   # write ~/.config/mado/starship.toml with theme colours

# ── Keybindings ────────────────────────────────────────────────────────────────

[keybindings]
split_right  = "cmd+d"
split_down   = "cmd+shift+d"
close_pane   = "cmd+w"
focus_left   = "cmd+opt+h"
focus_right  = "cmd+opt+l"
focus_up     = "cmd+opt+k"
focus_down   = "cmd+opt+j"
focus_left_alt  = "cmd+opt+left"
focus_right_alt = "cmd+opt+right"
focus_up_alt    = "cmd+opt+up"
focus_down_alt  = "cmd+opt+down"

---

AI panel

Mado has a built-in AI panel powered by Claude. To enable it, set your Anthropic API key in your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ANTHROPIC_API_KEY="sk-ant-..."

The panel opens via the AI button in the toolbar. Panel width is controlled by:

top_right_panel_width = 600.0

---

Keybinding syntax

Shortcuts are written as modifier+key. Valid modifiers:

Token	Meaning
cmd / meta / super	Command key
ctrl	Control key
opt / alt	Option / Alt key
shift	Shift key

Valid keys: any single character (d, w, h, etc.) or left, right, up, down.

Examples:

split_right = "cmd+d"
split_down  = "cmd+shift+d"
focus_left  = "cmd+opt+h"
focus_left  = "ctrl+h"

---

Plugins

External plugins are defined as [[plugins]] entries. Each plugin appears as a panel in the sidebar.

[[plugins]]
id      = "pomodoro"
command = "/usr/local/bin/mado-pomodoro"
kind    = "pixel"        # "pixel" or "" (PTY terminal)
icon    = ""             # Nerd Font glyph, e.g. "\uf017"
position = "left"        # "left", "right", "top-right", "bottom-right", "browser"

See the Plugins wiki page for the full protocol specification.

---

Projects

Workspace definitions live in a separate file: ~/.config/mado/projects.toml. To create and edit it:

mado projects

default = "API"

[API]
path   = "~/Projects/my-api"
icon   = "terminal"
task   = "cargo run"
deploy = "cargo build --release"

[WEB]
path   = "~/Projects/my-frontend"
icon   = "web"
task   = "npm run dev"
deploy = "npm run build"
url    = "http://localhost:3000"

Key	Description
path	Root directory opened when the workspace is selected
icon	Sidebar icon preset: terminal, web, mobile, design, data, docs
task	Command run by the bottom-bar play button
deploy	Command run by the bottom-bar deploy button
url	URL opened in the browser panel when the globe button is clicked — typically a local dev server (e.g. http://localhost:3000)
show	Set to false to hide the project from the Workspaces and Priorities panels (default: true)
default	Top-level key — workspace code to activate on launch

Globe button / local dev server

When a project has a url configured, a globe button appears in the runner sidebar alongside the play/stop/restart/deploy buttons. Clicking it opens that URL in the native browser panel; clicking again closes it. The button is highlighted while the panel is open.

This is useful for local dev servers — start your server with the play button, then click the globe to preview the site without leaving Mado.

The section name (API, WEB) must match the project code used in Tasku for automatic task filtering.

Hiding a project

Add show = false to any project to remove it from the sidebar panels without deleting it. The project remains fully functional — its pane layout is still saved and restored, and it can still be activated. To reinstate it, set show = true or remove the line entirely. All changes take effect immediately without restarting Mado.

[ARCHIVE]
path = "~/Projects/old-app"
show = false

---

FAQ

I edited config.toml but nothing changed. Most settings reload live — check that you saved the file. Settings that require a restart are: plugins, shell, font_family, tasku_position, and disable_*.

How do I reset config to defaults? Delete or rename ~/.config/mado/config.toml. Mado will use built-in defaults on next launch. Run mado config to recreate the file with commented-out defaults.

My keybinding conflicts with a system shortcut. macOS system shortcuts take priority. If Cmd+D is claimed by another app, remap the Mado binding:

[keybindings]
split_right = "ctrl+shift+d"

Can I have multiple config files for different setups? Not directly. The config path is fixed at ~/.config/mado/config.toml. To switch between setups you can symlink the file to different versions.

The browser panel is too narrow. Adjust browser_panel_width in config.toml. It takes effect immediately on save:

browser_panel_width = 900.0

Where is the projects file? At ~/.config/mado/projects.toml. Run mado projects to open it in your editor.