Skip to content

Add cmux sidebar builder skill #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lawrencecchen merged 3 commits into from
Jun 4, 2026
Merged

Add cmux sidebar builder skill #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d740e24
Add cmux sidebar vibe skill
lawrencecchen Jun 4, 2026
4bf634c
Rename sidebar skill to builder
lawrencecchen Jun 4, 2026
b7253a3
Document sidebar beta dogfood setup
lawrencecchen Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ You can also clone the repo and symlink the skills you want into your agent's sk
| [`cmux-customize`](skills/cmux-customize) | Customize tab bar buttons, plus-button menus, custom actions, commands, and right sidebar entries through `cmux.json`. |
| [`cmux-ref`](skills/cmux-ref) | Interpret pasted cmux workspace, pane, surface, and window refs or UUIDs as explicit target context. |
| [`cmux-groups`](skills/cmux-groups) | Manage collapsible sidebar workspace groups, anchor workspaces, group placement, and per-cwd group config. |
| [`cmux-sidebar-builder`](skills/cmux-sidebar-builder) | Build left-sidebar custom views with cmux's runtime SwiftUI-style interpreter. |
| [`cmux-workspace`](skills/cmux-workspace) | Work inside the current cmux workspace: caller surface, panes, surfaces, tagged reloads, socket targeting, non-interfering automation. |
| [`cmux-browser`](skills/cmux-browser) | Drive cmux browser surfaces: snapshot refs, DOM actions, waits, screenshots, cookies, storage, tabs, downloads, console, errors. |
| [`cmux-artifact`](skills/cmux-artifact) | Build durable HTML walkthrough artifacts for dogfood, verification, demos, and evidence pages, and open them in the current workspace. |
Expand All @@ -45,6 +46,7 @@ skills/
cmux-customize/SKILL.md
cmux-freestyle/SKILL.md
cmux-groups/SKILL.md
cmux-sidebar-builder/SKILL.md
cmux-ref/SKILL.md
cmux-settings/SKILL.md
cmux-workspace/SKILL.md
Expand Down
1 change: 1 addition & 0 deletions skills.sh.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"skills": [
"cmux-ref",
"cmux-groups",
"cmux-sidebar-builder",
"cmux-workspace",
"cmux-browser",
"cmux-artifact"
Expand Down
75 changes: 75 additions & 0 deletions skills/cmux-sidebar-builder/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
name: cmux-sidebar-builder
description: "Build, inspect, or revise cmux left-sidebar custom views using the runtime SwiftUI-style interpreter. Use for custom sidebars, left sidebar building, sidebar vibe coding, interpreted Swift sidebars, ~/.config/cmux/sidebars/*.swift, cmux docs sidebars, or Aziz's Swift interpreter work."
---

# cmux sidebar builder

Use this skill when the task is to create or modify a cmux left-sidebar custom view. These are user/agent-authored `.swift` files in `~/.config/cmux/sidebars/` rendered by cmux's runtime SwiftUI-style interpreter, not compiled app code.

## Orientation

- The original work is PR `https://github.com/manaflow-ai/cmux/pull/5254` by Aziz Albahar.
- The feature is opt-in behind the UserDefaults-backed key `customSidebars.beta.enabled`.
- Custom sidebars live under `~/.config/cmux/sidebars/` and appear in the left sidebar picker when the beta is enabled.
- Start from the cmux app checkout docs: `repo/docs/custom-sidebars.md`.

Important cmux source entrypoints:

- `repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/SwiftViewInterpreter.swift`
- `repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ExpressionEvaluator.swift`
- `repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/RenderNode.swift`
- `repo/Packages/CmuxSwiftRenderUI/Sources/CmuxSwiftRenderUI/Sidebar/CustomSidebarView.swift`
- `repo/Sources/ContentView.swift`, around `customSidebarsDirectory`, `customSidebarDataContext`, and `CustomSidebarView(...)`.

Follow-up implementation branches to inspect when needed:

- `origin/feat-interpreter-primitives` for the broader supported SwiftUI-ish primitive surface.
- `origin/feat-sidebar-interpreter-isolation` for the out-of-process crash-isolated interpreter worker.

## Workflow

1. Inspect the current app docs and interpreter surface before authoring:
```bash
sed -n '1,220p' repo/docs/custom-sidebars.md
rg -n "struct SwiftViewInterpreter|func evaluate|func parse|enum RenderNode|customSidebarDataContext|customSidebarsDirectory" repo/Packages/CmuxSwiftRender repo/Packages/CmuxSwiftRenderUI repo/Sources/ContentView.swift
```

2. Create or edit the sidebar file in the user's config directory:
```bash
mkdir -p ~/.config/cmux/sidebars
$EDITOR ~/.config/cmux/sidebars/<name>.swift
```

3. Stay inside the interpreted subset. Prefer simple SwiftUI-style expressions: `VStack`, `HStack`, `Text`, `Image`, `Button`, `ForEach`, conditionals, supported modifiers, and data from the provided context. Do not assume arbitrary Swift, imports, async work, filesystem access, networking, custom types, or compiled dependencies are available.

4. Use the provided data context instead of shelling out. If the sidebar needs data that is not exposed, identify the missing field in `customSidebarDataContext` and treat adding it as an app code change in a cmux worktree.

5. If you change app/runtime code, follow the cmux repo workflow: create a worktree, read repo-local instructions, localize user-facing strings, test appropriately, and reload with a tag before dogfood handoff. Config-only sidebar `.swift` edits do not require an app rebuild.

## Authoring rules

- This is the left sidebar. Do not use right-sidebar configuration or ExtensionKit unless the user explicitly asks for that surface.
- Keep custom sidebar files small and inspectable. If a design gets complicated, split behavior into simple helper functions only if the interpreter supports them.
- Make every visible action explicit through supported `Button` action payloads. Do not invent action ids without checking `repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ActionCommand.swift` and app dispatch wiring.
- Prefer real workspace, surface, notification, port, git, and progress fields from the cmux context. Avoid placeholder dashboards unless the task is only a mockup.
- When a rendering failure happens, reduce to the smallest sidebar file that reproduces it, then compare against `CmuxSwiftRender` tests and corpus examples.

## Verification

For config-only sidebars:

```bash
ls ~/.config/cmux/sidebars
```

Then ensure `customSidebars.beta.enabled` is on and ask the user to select the named sidebar from the left sidebar picker. This is not a `cmux.json` setting in current cmux builds; it is stored in the app's `UserDefaults.standard` domain. For temporary local dogfood only, it is acceptable to set the running app domain directly:

```bash
defaults write <bundle-id> customSidebars.beta.enabled -bool true
defaults write <bundle-id> cmuxExtensionSidebar.providerId "cmux.sidebar.custom.<name>"
Comment on lines +69 to +70

@cubic-dev-ai cubic-dev-ai Bot Jun 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: <bundle-id> in the defaults write commands is parsed by the shell as a stdin redirection (redirect from file bundle-id), not as a literal placeholder argument. Both defaults write commands will fail because the bundle-id domain argument is consumed by the redirection parser rather than passed to defaults write.

Fix: Replace <bundle-id> with a concrete example bundle ID such as com.manaflow.cmux.dev, since the surrounding note already lists the actual bundle IDs to use.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/cmux-sidebar-builder/SKILL.md, line 69:

<comment>`<bundle-id>` in the `defaults write` commands is parsed by the shell as a stdin redirection (redirect from file `bundle-id`), not as a literal placeholder argument. Both `defaults write` commands will fail because the bundle-id domain argument is consumed by the redirection parser rather than passed to `defaults write`.

Fix: Replace `<bundle-id>` with a concrete example bundle ID such as `com.manaflow.cmux.dev`, since the surrounding note already lists the actual bundle IDs to use.</comment>

<file context>
@@ -0,0 +1,75 @@
+Then ensure `customSidebars.beta.enabled` is on and ask the user to select the named sidebar from the left sidebar picker. This is not a `cmux.json` setting in current cmux builds; it is stored in the app's `UserDefaults.standard` domain. For temporary local dogfood only, it is acceptable to set the running app domain directly:
+
+```bash
+defaults write <bundle-id> customSidebars.beta.enabled -bool true
+defaults write <bundle-id> cmuxExtensionSidebar.providerId "cmux.sidebar.custom.<name>"
+```
</file context>
Suggested change
defaults write <bundle-id> customSidebars.beta.enabled -bool true
defaults write <bundle-id> cmuxExtensionSidebar.providerId "cmux.sidebar.custom.<name>"
defaults write com.manaflow.cmux.dev customSidebars.beta.enabled -bool true
defaults write com.manaflow.cmux.dev cmuxExtensionSidebar.providerId "cmux.sidebar.custom.<name>"

@cubic-dev-ai cubic-dev-ai Bot Jun 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Verification step uses an Extension sidebar provider key, which conflicts with this skill’s left-sidebar interpreted workflow and can misconfigure the wrong sidebar surface.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/cmux-sidebar-builder/SKILL.md, line 70:

<comment>Verification step uses an Extension sidebar provider key, which conflicts with this skill’s left-sidebar interpreted workflow and can misconfigure the wrong sidebar surface.</comment>

<file context>
@@ -0,0 +1,75 @@
+
+```bash
+defaults write <bundle-id> customSidebars.beta.enabled -bool true
+defaults write <bundle-id> cmuxExtensionSidebar.providerId "cmux.sidebar.custom.<name>"
+```
+
</file context>

```

Use the actual running bundle id, often `com.cmuxterm.app.nightly` for nightly or `com.manaflow.cmux.dev` for the default dev app. State that this is temporary dogfood setup, not a product default.

For interpreter or app changes, prefer focused package tests for `CmuxSwiftRender` plus the smallest real dogfood reload. Do not run local cmux `xcodebuild ... test`; use the project's remote or CI test guidance.
4 changes: 4 additions & 0 deletions skills/cmux-sidebar-builder/agents/openai.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "cmux Sidebar Builder"
short_description: "Build left-sidebar custom views with cmux's runtime SwiftUI-style interpreter."
default_prompt: "Use this skill to create, inspect, or revise cmux left-sidebar custom sidebars in ~/.config/cmux/sidebars using the runtime Swift interpreter and current cmux docs/source entrypoints."

@cubic-dev-ai cubic-dev-ai Bot Jun 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Terminology inconsistency: short_description says "SwiftUI-style interpreter" (accurate — a DSL interpreter for SwiftUI-like declarative syntax) but default_prompt says "Swift interpreter" (which reads as an interpreter for the Swift programming language). These describe different things: the sidebar DSL is a limited declarative subset, not general-purpose Swift.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At skills/cmux-sidebar-builder/agents/openai.yaml, line 4:

<comment>Terminology inconsistency: `short_description` says "SwiftUI-style interpreter" (accurate — a DSL interpreter for SwiftUI-like declarative syntax) but `default_prompt` says "Swift interpreter" (which reads as an interpreter for the Swift programming language). These describe different things: the sidebar DSL is a limited declarative subset, not general-purpose Swift.</comment>

<file context>
@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Sidebar Builder"
+  short_description: "Build left-sidebar custom views with cmux's runtime SwiftUI-style interpreter."
+  default_prompt: "Use this skill to create, inspect, or revise cmux left-sidebar custom sidebars in ~/.config/cmux/sidebars using the runtime Swift interpreter and current cmux docs/source entrypoints."
</file context>