Creating a space

Creating a space

Spaces live in the spaces array of ~/.config/omarchy-spaces/spaces.json. Adding one means adding an object to that array.

The smallest useful space

{
  "id": "side",
  "name": "Side project",
  "icon": "󰂜",
  "color": "#e0af68",
  "apps": ["Discord", "Figma"],
  "notifications": { "allowFrom": ["side"] }
}

id is the only required field. Everything else has a default.

Every field

Field	Meaning
id	Stable identifier. Used by the CLI, hotkeys, and allowFrom. Do not rename it casually.
name	Display name in the bar, picker, and status output. Defaults to id.
icon	Glyph shown in the bar. Any Nerd Font codepoint.
color	Accent color. Currently unused by the bar widget, reserved.
browser.command	Executable, for example brave or google-chrome-stable.
browser.profile	Passed as --profile-directory.
browser.args	Extra flags, inserted before the profile flag.
email	Address for this space. Readable with omarchy-spaces get email.
assistants	Map of tool name to account name.
apps	App names this space owns. Matched case insensitively.
notifications.allowFrom	Baseline list of space ids whose notifications show.
notifications.allowUnassigned	Whether apps in no space get through. Defaults to true.
notifications.schedule	Time windows that override the baseline.

A complete example

{
  "id": "work",
  "name": "HiScale",
  "icon": "󰌛",
  "color": "#9ece6a",
  "browser": { "command": "brave", "profile": "Profile 1" },
  "email": "you@company.com",
  "assistants": { "claude": "work", "codex": "work" },
  "apps": ["Slack", "zoom", "google-chrome", "Thunderbird"],
  "notifications": {
    "allowFrom": ["work"],
    "allowUnassigned": false,
    "schedule": [
      { "from": "08:00", "to": "18:00", "allowFrom": ["work"], "label": "Work hours" },
      { "from": "18:00", "to": "08:00", "allowFrom": [], "allowUnassigned": false, "label": "Off hours" }
    ]
  }
}

Finding the right app name

apps matches the app_name a program sends over D-Bus, not the window title or the desktop file name. Trailing .desktop is stripped and case is ignored, so Slack, slack, and slack.desktop all match.

To see what an app actually reports, send yourself a notification and read the history:

ls -t ~/.local/state/omarchy/notifications/history/*.json | head -1 | \
  xargs python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['app'])"

Or test a name directly:

notify-send -a Slack "test" "does this show"

After adding one

omarchy-spaces validate      # catches typos and schedule gaps
omarchy-spaces install-menu  # add the new row to the picker
omarchy-spaces list

The bar widget and the running shell pick up config changes on their own. No restart needed.

Add a hotkey for it too, see Hotkeys.

Choosing an icon

Icons are Nerd Font glyphs. Browse them at nerdfonts.com/cheat-sheet. Paste the glyph straight into the JSON. If it shows as a box or a stray digit, the codepoint is outside the font, so pick another.