cmux Custom Sidebar

Full reference

cmux docs sidebars
curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/docs/custom-sidebars.md

Workflow

1. Enable the beta (once). Custom sidebars are behind Settings → Beta features → Custom sidebars (

   customSidebars.beta.enabled

   ). If a written sidebar does not appear in the picker, this flag is the first thing to check.
2. Write a named file. The name becomes the menu label; use short kebab-case:

   ~/.config/cmux/sidebars/<name>.swift

   The file is a single SwiftUI-style view expression (no

   struct

   , no

   var body

   , no imports). A

   .json

   variant exists for static layouts; prefer

   .swift

   for anything dynamic.
3. Validate and select it:
   bash

   cmux sidebar validate <name>   # parse/interpret check with real data shapes
   cmux sidebar select <name>     # switch the sidebar to it

   The user can also pick it manually: right-click the sidebar toggle button.
4. Iterate. Saving the file hot-reloads the sidebar in place (

   cmux sidebar reload

   forces it). Look at the result, fix what looks off, and verify rows show real data and taps do the right thing before declaring it done.

Authoring rules

• Default to live data. Bind to the

  workspaces

  context instead of hard-coding text so the sidebar stays correct on its own.
• Make it interactive by default. Rows that represent something openable should run the matching

  cmux(...)

  action on tap. A list that just displays text is rarely what they wanted.
• Prefer

  Reorderable

  for workspace-like lists. It gives persisted drag-and-drop reordering for free.
• Keep it native and uncluttered: a title, a divider, then the content.
• Cap long lists (

  .prefix(20)

  , filter/sort before rendering). The sidebar re-evaluates about once a second; do not render hundreds of rows.
• Stay inside the supported subset. Unsupported syntax is skipped gracefully (never crashes), but choose the closest supported approach rather than shipping a half-blank sidebar.

Quick start

cat > ~/.config/cmux/sidebars/mine.swift <<'SWIFT'
VStack(alignment: .leading, spacing: 8) {
    Text("My sidebar").font(.title3).bold()
    Text(clock.time).font(.caption).foregroundColor(.secondary)
    Divider()
    Reorderable(workspaces, move: "workspace.reorder") { w in
        Button(action: { cmux("workspace.select", workspace_id: w.id) }) {
            HStack {
                Text(w.selected ? "●" : "○").foregroundColor(w.selected ? "#FF8800" : .secondary)
                Text(w.title)
                Spacer()
            }.padding(4)
        }
    }
}
SWIFT
cmux sidebar validate mine && cmux sidebar select mine

Live data context (read-only, refreshes ~1s)

• workspaces

  : array with

  id

  ,

  title

  ,

  selected

  ,

  pinned

  ,

  index

  ,

  directory

  ,

  ports

  +

  portCount

  ,

  unread

  ,

  tabs

  +

  tabCount

  ; plus, when present:

  description

  ,

  color

  ,

  branch

  +

  dirty

  ,

  pr

  /

  prs

  (

  {number, label, url, status, stale, branch}

  ),

  progress

  (

  {value, label}

  ),

  latestMessage

  ,

  latestPrompt

  ,

  latestAt

  ,

  remote

  (

  {target, state, connected}

  ).

• workspaces[i].tabs

  :

  id

  ,

  title

  ,

  focused

  ,

  pinned

  ; plus

  directory

  ,

  branch

  +

  dirty

  ,

  ports

  when available.

• clock

  :

  {time, hour, minute, second, weekday, epoch}

  .
• Scalars:

  workspaceCount

  ,

  selectedTitle

  ,

  selectedId

  ,

  unreadTotal

  .

if let b = w.branch { ... }

w.pr != nil ? ... : ...

Actions

.onTapGesture

cmux("<method>", param: value)

cmux

workspace.select

workspace_id

surface.focus

surface_id

workspace.reorder

workspace_id

index

openURL("https://...")

cmux docs api

Supported subset at a glance

Group

List

Section

ViewThatFits

ScrollView

HSplitView

Text

Label

Image(systemName:)

Button

Menu

ProgressView

Gauge

Spacer

Divider

.background

.padding

.frame

.background

.overlay

.mask

.contextMenu

.onTapGesture

.help

.disabled

let

func

for

ForEach

if/else

filter

map

sorted

prefix

@State

TextField

Toggle

Slider

Picker

struct

View

sheet

popover

AsyncImage

cmux(...)

Troubleshooting

• Sidebar missing from the right-click picker: the beta flag is off, or the file is not directly under

  ~/.config/cmux/sidebars/

  .
• Blank or partial render: run

  cmux sidebar validate <name>

  ; errors show inline in the sidebar with the failing location. A broken save keeps the last working render on screen, so re-save after fixing.
• Rows not tappable: wrap the row in

  Button(action: { cmux(...) }) { ... }

  or add

  .onTapGesture { cmux(...) }

  .
• Reorder not persisting: use

  Reorderable(data, move: "workspace.reorder")

  , not

  List

  /

  .onMove

  /

  .draggable

  .