Workspace

Themes

Themes control Swarm’s UI colors. Swarm has a global theme, optional custom themes, and optional workspace theme overrides so different projects can visibly feel separate.

Model

Theme order is: preview, workspace override, then global default.

Swarm starts with the configured global theme. The default global theme is crimson. When a workspace has a theme override, that workspace theme controls the active UI. When a theme modal is previewing a choice, the preview temporarily wins until it is applied or cleared.

Custom themes extend the built-in catalog. They are normalized by id, stored with the UI settings, and can be selected like built-in themes after they are created.

Commands

Terminal theme commands

/themes

Open the theme modal with live preview. /theme is an alias.

/themes list

List built-in and custom themes by name and numbered index.

/themes status

Show the active theme, available theme count, custom count, and command hints.

/themes set <name|#n>

Apply a theme by id, name, prefix, or numbered list entry.

/themes next / prev

Rotate through the theme catalog.

/themes create <id> [from <theme>]

Create a custom theme from a base theme.

/themes edit <id> <slot> <#RRGGBB>

Edit one color slot in a custom theme.

/themes delete <id>

Delete a custom theme. Built-in themes are not removed this way.

Global and workspace

Desktop separates global theme from workspace overrides.

Global themeThe default Desktop theme. Workspaces set to inherit use this value.

Workspace overrideA saved workspace can choose its own theme instead of inheriting the global theme.

Active workspaceDesktop applies the active workspace’s override immediately; otherwise it applies the global theme.

InheritThe workspace-level “inherit” option stores no workspace theme id, so the global theme controls that workspace.

Custom themes

Custom themes are named palettes in the same catalog.

Custom theme ids are normalized before saving. Swarm ignores invalid or duplicate custom ids and does not allow a custom theme to replace a built-in theme id. If a custom theme has no display name, Swarm derives one from the normalized id.

Use /themes slots when editing a custom palette. It shows the available color slots so you can update one slot at a time without guessing the internal palette names.

TUI and Desktop

The surfaces share the theme catalog, but expose it differently.

Terminal UIUses /themes for live preview, list/status, global or workspace-scoped apply, and custom palette creation/editing.

Desktop settingsHas a Themes settings page with a global theme selector and per-workspace override selectors.

Workspace editorLets a saved workspace choose a theme while creating or editing the workspace.

Shared settingsCustom themes and global theme settings come from the same UI settings shape used by both surfaces.

This page avoids button-by-button UI instructions. The important concept is whether a color choice is global, workspace-scoped, or a temporary preview.

Safe defaults

If you do nothing, Swarm uses the built-in default.

DefaultThe default global theme is crimson.

FallbackIf Swarm cannot resolve the configured theme, it falls back to the default theme.

Workspace clarityWorkspace overrides are useful when you want separate visual identity for different projects or hosts.