Getting Started

Getting Started

Mado is a terminal multiplexer with a sidebar task management panel, workspace switching, and a plugin system for custom tools. It runs on macOS and Linux.

---

Installation

macOS

Download the latest .dmg from the releases page, open it, and drag Mado.app to your Applications folder.

Mado requires macOS 13 or later.

CLI setup (optional)

The mado command gives you access to mado config, mado projects, and other utilities from your terminal. To set it up:

sudo ln -sf "/Applications/Mado.app/Contents/MacOS/mado" /usr/local/bin/mado

You only need to do this once. If you installed via Homebrew, this is handled automatically.

Linux

Packages are available from the releases page.

Download the package for your architecture from the releases page.

Debian / Ubuntu:

sudo dpkg -i mado_*_amd64.deb   # Intel/AMD
sudo dpkg -i mado_*_arm64.deb   # ARM

Raw binary (any distro):

tar -xzf mado-*-linux-x86_64.tar.gz   # Intel/AMD
tar -xzf mado-*-linux-aarch64.tar.gz  # ARM
cd mado-*-linux-*/
./install.sh

Linux requires GTK 3 and WebKitGTK 2.40 or later (libwebkit2gtk-4.1 on Debian/Ubuntu).

---

First launch

On first launch Mado opens a single terminal pane using your default shell ($SHELL). No configuration is needed — it works out of the box.

The sidebar is on the left. The first time you open it you will see three built-in panels:

Panel	What it does
Workspaces	Switch between projects; each remembers its own pane layout
Priorities	Pin high-priority tasks across all projects
Tasks	Full task list powered by Tasku

The Tasks panel requires Tasku to be installed:

gem install tasku

---

Pane management

Action	Shortcut
Split right	Cmd+D
Split down	Cmd+Shift+D
Close pane	Cmd+W
Focus left	Cmd+Opt+H or Cmd+Opt+←
Focus right	Cmd+Opt+L or Cmd+Opt+→
Focus up	Cmd+Opt+K or Cmd+Opt+↑
Focus down	Cmd+Opt+J or Cmd+Opt+↓

Drag the dividers between panes to resize them. All shortcuts can be remapped in config.toml.

---

Workspaces

A workspace is a named project with its own pane layout and working directory. Mado saves and restores the layout automatically when you switch.

To set up workspaces, run:

mado projects

This creates ~/.config/mado/projects.toml (if it doesn't exist) and opens it in your editor. Add a section for each project:

default = "API"

[API]
path = "~/Projects/my-api"

[WEB]
path = "~/Projects/my-frontend"

The section name (API, WEB) is the workspace code. It must match the project code used in Tasku if you want the Tasks panel to filter automatically.

---

Configuration

Mado looks for ~/.config/mado/config.toml on startup. The file does not need to exist on first launch — all settings have sensible defaults. Once you want to customise anything, run mado config to create it. Most settings take effect as soon as you save — no restart needed. To create it with commented defaults:

mado config

This opens the file in your editor. A minimal starting point:

theme        = "slate"       # any of the 22 built-in themes
font_size    = 18.0
font_family  = ""            # leave empty to use bundled Hack Nerd Font Mono
shell        = ""            # leave empty to use $SHELL

sidebar_width      = 380.0
show_bottom_bar    = false
tasku_position     = "top"   # "top", "left", or "right"

[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"

Changes to config.toml are applied live — no restart needed.

---

Fonts

Mado ships with Hack Nerd Font Mono built in — no setup required. To use a different font, install it on your system and set font_family in config.toml:

font_family = "JetBrains Mono"

Note: font_family requires a restart to take effect.

Recommended fonts

Font	Notes
Hack Nerd Font Mono	Built-in default, full Nerd Font icon support
JetBrains Mono	Excellent clarity, highly recommended
Fira Code	Good ligature support
Cascadia Code	Microsoft's monospace, clean rendering
SF Mono	Apple's monospace, ships with macOS

Any font installed on your system can be used. For Nerd Font icons in plugins and prompts, use a Nerd Font variant of your preferred font.

---

Themes

Mado ships with 22 themes based on Tailwind CSS palettes:

amber blue cyan emerald fuchsia gray green indigo lime neutral orange pink purple red rose sky slate stone teal violet yellow zinc

Set the theme in config.toml:

theme = "indigo"

To use Starship with matching colours, add:

theme_starship = true

Mado will write a Starship config to ~/.config/mado/starship.toml and set STARSHIP_CONFIG in all spawned shells.

Custom themes

Create ~/.config/mado/themes/mytheme.toml modelled on any file in the themes/ directory of the repo, then set theme = "mytheme".

---

Next steps

• Configuration reference — every config.toml key documented
• Plugins — add custom sidebar panels using the pixel plugin protocol
• Themes — create and share your own colour scheme

---

FAQ

Mado opens without focus — my typing goes nowhere. Click the window once to focus it, or press Cmd+Tab to bring Mado to the front. This is a known macOS quirk with apps that open from the dock on first launch.

How do I update Mado? If you installed via Homebrew:

brew upgrade --cask mado

Or download the latest .dmg from the releases page and drag the new app to Applications.

The sidebar panels are blank. The Tasks panel requires Tasku to be installed (gem install tasku). The Workspaces panel only shows tiles for projects that have at least one task with both a project name and a project code set. Plugin panels require the plugin binary to be installed and signed — run mado plugin install <name>.

My shell prompt doesn't look right. Mado ships with Hack Nerd Font Mono built in, which includes all the glyphs used by common prompt frameworks. If your prompt uses a different Nerd Font variant, set font_family in config.toml to match the font you use in other terminals.

Cmd+D / Cmd+W conflict with my browser. Mado only captures those shortcuts when its window is focused. If Mado and a browser are both open, focus determines which app receives the shortcut. You can remap any shortcut in config.toml under [keybindings].

Can I use Mado as my primary terminal? Yes. On macOS, add it to your Dock and set up the CLI symlink (sudo ln -sf "/Applications/Mado.app/Contents/MacOS/mado" /usr/local/bin/mado). On Linux, the binary is already in /usr/local/bin after installation. Run mado config and mado projects to configure it.