cmux Custom Sidebar
cmux renders custom sidebars from a small SwiftUI-style file at runtime: no Xcode, no build step, no signing. The file hot-reloads on save, binds to live cmux state (workspaces, tabs, git, PRs, clock), and runs real cmux commands on tap.
The person asking is describing a result ("a sidebar that shows my workspaces and lets me jump between them"), not an implementation. Make the engineering decisions for them; do not ask them about SwiftUI, files, or syntax.
This skill is the workflow summary. Read the complete authoring contract (every supported view, modifier, language feature, and data field) before writing a non-trivial sidebar:
cmux docs sidebars
curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/docs/custom-sidebars.md
Workflow
- Enable the beta (once): Settings > Beta features > Custom sidebars (
customSidebars.beta.enabled). If a written sidebar does not appear in the picker, check this first.
- Write a named file at
~/.config/cmux/sidebars/<name>.swift. The name becomes the menu label; use short kebab-case. 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.
- Validate and select:
cmux sidebar validate <name> # parse/interpret check with real data shapes
cmux sidebar select <name>
The user can also right-click the sidebar toggle button to pick it.
- Iterate. Saving hot-reloads in place (
cmux sidebar reload forces it). Verify rows show real data and taps do the right thing before declaring it done.
Authoring rules
- Bind to the
workspaces context instead of hard-coding text, so the sidebar stays correct on its own.
- Rows that represent something openable run the matching
cmux(...) action on tap. A list that only displays text is rarely what they wanted.
- Use
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.
- Stay inside the supported subset. Unsupported syntax is skipped gracefully rather than crashing, but choose the closest supported approach instead of 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: id, title, selected, pinned, index, directory, ports + portCount, unread, tabs + tabCount; when present also 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.
Optional fields are omitted when absent; guard with if let b = w.branch { ... } or w.pr != nil ? ... : ....
Actions
A button or .onTapGesture body calls cmux("<method>", param: value), dispatched through the same surface as the CLI. Common methods: workspace.select (workspace_id), surface.focus (surface_id), workspace.reorder (workspace_id + index). openURL("https://...") opens links. Full command surface: cmux docs api.
Supported subset
Containers: stacks (including lazy), Group, List, Section, grids, ViewThatFits, ScrollView, HSplitView (two resizable columns). Content: Text, Label, Image(systemName:), Button (title and label form), Menu, ProgressView, Gauge, Spacer, Divider, shapes, gradients via .background. Modifiers: full typography set, colors as hex strings or tokens, .padding/.frame/layout, .background/.overlay/.mask/.contextMenu with arbitrary nested views, shadows/borders/opacity/effects, .onTapGesture, .help, .disabled. Language: let, user func helpers, for/ForEach, if/else, ternary, string interpolation, arithmetic, array methods (filter/map/sorted/prefix), string and number formatting.
Not yet supported (write the natural Swift anyway; it degrades gracefully): @State and input controls (TextField, Toggle, Slider, Picker), custom struct/View definitions, navigation (sheet/popover), AsyncImage. Two-way editing does not work yet; taps that run cmux(...) do.
Troubleshooting
- 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.
1---
2name: cmux-custom-sidebar
3description: "Build a custom cmux sidebar from a plain-language request. Use when the user asks for a custom sidebar, a sidebar that shows their workspaces/tabs/PRs/clock, a vibe-coded sidebar, or anything involving files in ~/.config/cmux/sidebars/. Covers authoring the interpreted SwiftUI-style file, enabling the beta flag, selecting it, and iterating with hot reload."
4metadata:
5 source: https://skillmd.com/skills/manaflow-ai/cmux-custom-sidebar
6---
7
8# cmux Custom Sidebar
9
10cmux renders custom sidebars from a small SwiftUI-style file at runtime: no Xcode, no build step, no signing. The file hot-reloads on save, binds to live cmux state (workspaces, tabs, git, PRs, clock), and runs real cmux commands on tap.
11
12The person asking is describing a result ("a sidebar that shows my workspaces and lets me jump between them"), not an implementation. Make the engineering decisions for them; do not ask them about SwiftUI, files, or syntax.
13
14This skill is the workflow summary. Read the complete authoring contract (every supported view, modifier, language feature, and data field) before writing a non-trivial sidebar:
15
16```bash
17cmux docs sidebars
18curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/docs/custom-sidebars.md
19```
20
21## Workflow
22
231. **Enable the beta** (once): Settings > Beta features > Custom sidebars (`customSidebars.beta.enabled`). If a written sidebar does not appear in the picker, check this first.
242. **Write a named file** at `~/.config/cmux/sidebars/<name>.swift`. The name becomes the menu label; use short kebab-case. 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.
253. **Validate and select:**
26 ```bash
27 cmux sidebar validate <name> # parse/interpret check with real data shapes
28 cmux sidebar select <name>
29 ```
30 The user can also right-click the sidebar toggle button to pick it.
314. **Iterate.** Saving hot-reloads in place (`cmux sidebar reload` forces it). Verify rows show real data and taps do the right thing before declaring it done.
32
33## Authoring rules
34
35- Bind to the `workspaces` context instead of hard-coding text, so the sidebar stays correct on its own.
36- Rows that represent something openable run the matching `cmux(...)` action on tap. A list that only displays text is rarely what they wanted.
37- Use `Reorderable` for workspace-like lists; it gives persisted drag-and-drop reordering for free.
38- Keep it native and uncluttered: a title, a divider, then the content.
39- Cap long lists (`.prefix(20)`, filter/sort before rendering). The sidebar re-evaluates about once a second.
40- Stay inside the supported subset. Unsupported syntax is skipped gracefully rather than crashing, but choose the closest supported approach instead of shipping a half-blank sidebar.
41
42## Quick start
43
44```bash
45cat > ~/.config/cmux/sidebars/mine.swift <<'SWIFT'
46VStack(alignment: .leading, spacing: 8) {
47 Text("My sidebar").font(.title3).bold()
48 Text(clock.time).font(.caption).foregroundColor(.secondary)
49 Divider()
50 Reorderable(workspaces, move: "workspace.reorder") { w in
51 Button(action: { cmux("workspace.select", workspace_id: w.id) }) {
52 HStack {
53 Text(w.selected ? "●" : "○").foregroundColor(w.selected ? "#FF8800" : .secondary)
54 Text(w.title)
55 Spacer()
56 }.padding(4)
57 }
58 }
59}
60SWIFT
61cmux sidebar validate mine && cmux sidebar select mine
62```
63
64## Live data context (read-only, refreshes ~1s)
65
66- `workspaces`: `id`, `title`, `selected`, `pinned`, `index`, `directory`, `ports` + `portCount`, `unread`, `tabs` + `tabCount`; when present also `description`, `color`, `branch` + `dirty`, `pr` / `prs` (`{number, label, url, status, stale, branch}`), `progress` (`{value, label}`), `latestMessage`, `latestPrompt`, `latestAt`, `remote` (`{target, state, connected}`).
67- `workspaces[i].tabs`: `id`, `title`, `focused`, `pinned`; plus `directory`, `branch` + `dirty`, `ports` when available.
68- `clock`: `{time, hour, minute, second, weekday, epoch}`.
69- Scalars: `workspaceCount`, `selectedTitle`, `selectedId`, `unreadTotal`.
70
71Optional fields are omitted when absent; guard with `if let b = w.branch { ... }` or `w.pr != nil ? ... : ...`.
72
73## Actions
74
75A button or `.onTapGesture` body calls `cmux("<method>", param: value)`, dispatched through the same surface as the CLI. Common methods: `workspace.select` (`workspace_id`), `surface.focus` (`surface_id`), `workspace.reorder` (`workspace_id` + `index`). `openURL("https://...")` opens links. Full command surface: `cmux docs api`.
76
77## Supported subset
78
79Containers: stacks (including lazy), `Group`, `List`, `Section`, grids, `ViewThatFits`, `ScrollView`, `HSplitView` (two resizable columns). Content: `Text`, `Label`, `Image(systemName:)`, `Button` (title and label form), `Menu`, `ProgressView`, `Gauge`, `Spacer`, `Divider`, shapes, gradients via `.background`. Modifiers: full typography set, colors as hex strings or tokens, `.padding`/`.frame`/layout, `.background`/`.overlay`/`.mask`/`.contextMenu` with arbitrary nested views, shadows/borders/opacity/effects, `.onTapGesture`, `.help`, `.disabled`. Language: `let`, user `func` helpers, `for`/`ForEach`, `if/else`, ternary, string interpolation, arithmetic, array methods (`filter`/`map`/`sorted`/`prefix`), string and number formatting.
80
81Not yet supported (write the natural Swift anyway; it degrades gracefully): `@State` and input controls (`TextField`, `Toggle`, `Slider`, `Picker`), custom `struct`/`View` definitions, navigation (`sheet`/`popover`), `AsyncImage`. Two-way editing does not work yet; taps that run `cmux(...)` do.
82
83## Troubleshooting
84
85- Missing from the right-click picker: the beta flag is off, or the file is not directly under `~/.config/cmux/sidebars/`.
86- 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.
87- Rows not tappable: wrap the row in `Button(action: { cmux(...) }) { ... }` or add `.onTapGesture { cmux(...) }`.
88- Reorder not persisting: use `Reorderable(data, move: "workspace.reorder")`, not `List`/`.onMove`/`.draggable`.