Skip to content
Merged
Show file tree
Hide file tree
Changes from 33 commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
1cf0071
feat: add sidebar ExtensionKit host
azooz2003-bit May 29, 2026
f69d418
Address sidebar ExtensionKit review feedback
azooz2003-bit May 29, 2026
2fc7dd9
Split sidebar ExtensionKit sources
azooz2003-bit May 29, 2026
6764a3a
Organize sidebar extension sources into folders
azooz2003-bit May 29, 2026
de4a77e
Add sample sidebar extension package to workspace
azooz2003-bit May 29, 2026
13289ad
Add runnable sample sidebar ExtensionKit app
azooz2003-bit May 29, 2026
9e44614
Give sample sidebar extension a unique app identity
azooz2003-bit May 29, 2026
131df68
Fix sidebar extension titlebar placement
azooz2003-bit May 29, 2026
1ee1091
Use ExtensionKit browser for sidebar extensions
azooz2003-bit May 29, 2026
fca8e6d
Fix sidebar extension browser presentation
azooz2003-bit May 29, 2026
cd7b11b
Fix sidebar ExtensionKit approval
azooz2003-bit May 29, 2026
ee2d90d
Observe sidebar ExtensionKit enablement
azooz2003-bit May 29, 2026
fb49cba
Harden sidebar extension dogfood flow
azooz2003-bit May 29, 2026
1d87f0a
Harden sidebar ExtensionKit host state
azooz2003-bit May 30, 2026
fc51da5
Add sidebar extension grants
azooz2003-bit May 30, 2026
245bf97
Tear down disabled sidebar extensions
azooz2003-bit May 30, 2026
19c91bc
Require sidebar extension manifests before host access
azooz2003-bit May 30, 2026
a0676d2
Add sidebar extension host controls
azooz2003-bit May 30, 2026
e03c71a
Cap sidebar extension XPC payload sizes
azooz2003-bit May 30, 2026
81a6344
Show sidebar extension details
azooz2003-bit May 30, 2026
b587225
Gate sidebar metadata behind scope grant
azooz2003-bit May 30, 2026
d35232e
Require grants for sidebar extension actions
azooz2003-bit May 30, 2026
5c52883
Enforce sidebar XPC payload caps on encode
azooz2003-bit May 30, 2026
00c64ba
Make sidebar extension grants reversible
azooz2003-bit May 30, 2026
6fbd721
Show blocked sidebar extension state
azooz2003-bit May 30, 2026
2594ca9
Tear down sidebar extension host explicitly
azooz2003-bit May 30, 2026
4fa8f62
Add sidebar extension empty-state actions
azooz2003-bit May 30, 2026
aead7eb
Show interrupted sidebar extension state
azooz2003-bit May 30, 2026
3e906ad
Add sidebar extension author connection helper
azooz2003-bit May 30, 2026
56270dc
Clarify sidebar extension permission grant
azooz2003-bit May 30, 2026
ef81b41
Document sidebar extension quickstart
azooz2003-bit May 30, 2026
59f1282
Timeout stalled sidebar extension manifests
azooz2003-bit May 30, 2026
db59ca5
Refresh hosted sidebar extension snapshots
azooz2003-bit May 30, 2026
a820c88
Improve sidebar extension recovery copy
azooz2003-bit May 30, 2026
632e809
Fix sidebar extension retry and XPC actor isolation
azooz2003-bit May 30, 2026
27fb01e
Add sidebar ExtensionKit support
azooz2003-bit May 30, 2026
b706047
Tighten titlebar accessory divider spacing
azooz2003-bit May 30, 2026
341aaf6
Keep extension sidebar chrome within minimum width
azooz2003-bit May 30, 2026
c6e3a17
Fix titlebar accessory traffic light alignment
azooz2003-bit May 30, 2026
504cf5f
Guard modern extension monitor for Xcode 16
azooz2003-bit May 30, 2026
0d72b16
Reduce titlebar accessory minimum width
azooz2003-bit May 30, 2026
97a35f5
Merge remote-tracking branch 'origin/main' into feature-sidebar-exten…
azooz2003-bit May 30, 2026
c816094
Update sidebar extension for latest main
azooz2003-bit May 30, 2026
43c1fcd
Run release build on macOS 15
azooz2003-bit May 30, 2026
67e62a1
Give UI regressions cold builds more time
azooz2003-bit May 30, 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
60 changes: 60 additions & 0 deletions Examples/SampleSidebarExtensionApp/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# CMUX Sample Sidebar Extension

This is a standalone macOS app that embeds a CMUX sidebar ExtensionKit app extension. It is the reference project for third-party sidebar authors.

## Build and Enable

1. Open `SampleSidebarExtensionApp.xcodeproj`.
2. Select the app and extension targets.
3. Replace the Manaflow signing team with your own team.
4. Replace the app and extension bundle identifiers with your own reverse-DNS identifiers.
5. Keep the extension point identifier as `com.manaflow.cmux.sidebar`.
6. Keep the ExtensionKit scene identifier as `sidebar`.
7. Build and launch the containing app once.
8. In CMUX, click the titlebar puzzle button, open Sidebar Extensions, and enable the sample.
9. Choose `CMUX ExtKit Sample Sidebar` as the active sidebar provider.

The sample targets macOS 26 because it exercises CMUX's current ExtensionFoundation browser and ExtensionKit host path. The `CmuxExtensionKit` data contract is plain Swift and remains separate from that host requirement.

## What It Shows

The extension renders real workspace data supplied by CMUX:

- workspace count
- unread total
- listening port count
- pull request count
- selected workspace
- focus queue based on unread workspaces

It does not use fake workspaces. If CMUX only grants limited access, the sample still renders the metadata CMUX shares by default. After you grant requested access in CMUX, it can also show paths, ports, notifications, and pull request links.

## Authoring Pattern

The sample keeps app-specific state in `SidebarConnectionModel` and delegates XPC plumbing to `CMUXSidebarExtensionConnection`:

```swift
private lazy var extensionConnection = CMUXSidebarExtensionConnection(
manifest: Self.manifest,
onSnapshot: { [weak self] snapshot in
self?.snapshot = snapshot
},
onError: { [weak self] message in
self?.errorText = message
}
)

func accept(connection: NSXPCConnection) -> Bool {
extensionConnection.accept(connection)
}
```

The manifest is the permission request CMUX shows to users. Request only the scopes your sidebar actually needs.

## Troubleshooting

If the extension does not appear in CMUX, launch the containing app once, then reopen CMUX's Sidebar Extensions browser.

If it appears but cannot be enabled, check signing on both the containing app and the embedded appex.

If it loads but shows limited information, open the CMUX extension details popover and grant the requested data/actions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
import Foundation
import Observation
import SwiftUI
import CmuxExtensionKit

@Observable
final class SidebarConnectionModel: @unchecked Sendable {
static let shared = SidebarConnectionModel()
static let manifest = CMUXExtensionManifest(
id: "co.manaflow.CMUXExtKitSampleSidebarApp.Extension",
displayName: "CMUX Sample Sidebar Extension",
requestedScopes: [
.workspaceMetadata,
.workspacePaths,
.notifications,
.networkPorts,
.pullRequests,
],
requestedActionScopes: [
.selectWorkspace,
]
)

private(set) var snapshot: CMUXSidebarSnapshot?
private(set) var errorText: String?

@ObservationIgnored
private lazy var extensionConnection = CMUXSidebarExtensionConnection(
manifest: Self.manifest,
onSnapshot: { [weak self] snapshot in
self?.snapshot = snapshot
},
onError: { [weak self] message in
self?.errorText = message.map(Self.localizedHostMessage)
}
)

private init() {}

func accept(connection: NSXPCConnection) -> Bool {
extensionConnection.accept(connection)
}

var insights: SidebarInsightModel? {
snapshot.map(SidebarInsightModel.init(snapshot:))
}

func refreshSnapshot() {
extensionConnection.refreshSnapshot()
}

func selectWorkspace(_ id: UUID) {
extensionConnection.perform(.selectWorkspace(id))
}

private static func localizedHostMessage(_ message: String) -> String {
switch message {
case "Waiting for cmux":
return String(localized: "sampleSidebar.waitingForHost", defaultValue: "Waiting for cmux")
case "cmux did not send a workspace snapshot":
return String(localized: "sampleSidebar.emptySnapshot", defaultValue: "cmux did not send a workspace snapshot")
default:
return message
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import ExtensionFoundation
import ExtensionKit
import SwiftUI
import CmuxExtensionKit

@main
final class SampleSidebarExtension: AppExtension {
required init() {}

@AppExtensionPoint.Bind
var boundExtensionPoint: AppExtensionPoint {
AppExtensionPoint.Identifier("com.manaflow.cmux.sidebar")
}

var configuration: AppExtensionSceneConfiguration {
AppExtensionSceneConfiguration(self.body)
}

var body: some AppExtensionScene {
PrimitiveAppExtensionScene(id: "sidebar") {
SampleSidebarView(model: SidebarConnectionModel.shared)
} onConnection: { connection in
SidebarConnectionModel.shared.accept(connection: connection)
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>EXAppExtensionAttributes</key>
<dict>
<key>EXExtensionPointIdentifier</key>
<string>com.manaflow.cmux.sidebar</string>
</dict>
</dict>
</plist>
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
import Foundation
import CmuxExtensionKit

struct SidebarInsightModel {
var sequence: UInt64
var totalCount: Int
var pinnedCount: Int
var unreadCount: Int
var portCount: Int
var pullRequestCount: Int
var selectedWorkspace: WorkspaceInsight?
var focusQueue: [WorkspaceInsight]

init(snapshot: CMUXSidebarSnapshot) {
let insights = snapshot.workspaces.map {
WorkspaceInsight(workspace: $0, selectedWorkspaceID: snapshot.selectedWorkspaceID)
}
sequence = snapshot.sequence
totalCount = insights.count
pinnedCount = insights.filter(\.isPinned).count
unreadCount = insights.reduce(0) { $0 + $1.unreadCount }
portCount = insights.reduce(0) { $0 + $1.portCount }
pullRequestCount = insights.reduce(0) { $0 + $1.pullRequestCount }
selectedWorkspace = insights.first(where: \.isSelected)
focusQueue = insights
.filter { $0.hasSignal && !$0.isSelected }
.sorted { lhs, rhs in
if lhs.score != rhs.score { return lhs.score > rhs.score }
return lhs.title.localizedCaseInsensitiveCompare(rhs.title) == .orderedAscending
}
}
}

struct WorkspaceInsight: Identifiable {
var id: UUID
var title: String
var subtitle: String
var isSelected: Bool
var isPinned: Bool
var unreadCount: Int
var portCount: Int
var pullRequestCount: Int
var branch: String?
var latestNotification: String?

init(workspace: CMUXSidebarWorkspace, selectedWorkspaceID: UUID?) {
id = workspace.id
title = workspace.title
subtitle = workspace.detail ?? workspace.rootPath?.lastPathComponent ?? workspace.projectRootPath?.lastPathComponent ?? ""
isSelected = workspace.id == selectedWorkspaceID
isPinned = workspace.isPinned
unreadCount = max(0, workspace.unreadCount)
portCount = workspace.listeningPorts.count
pullRequestCount = workspace.pullRequestURLs.count
branch = workspace.gitBranch
latestNotification = workspace.latestNotification
}

var hasSignal: Bool {
isSelected || isPinned || unreadCount > 0 || portCount > 0 || pullRequestCount > 0 || latestNotification != nil
}

var score: Int {
(isSelected ? 1000 : 0)
+ (unreadCount * 100)
+ (portCount * 20)
+ (pullRequestCount * 10)
+ (isPinned ? 5 : 0)
}
}

private extension String {
var lastPathComponent: String {
(self as NSString).lastPathComponent
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import SwiftUI

struct SampleSidebarView: View {
var model: SidebarConnectionModel

var body: some View {
ScrollView {
VStack(alignment: .leading, spacing: 12) {
if let insights = model.insights {
header(insights)
if let selected = insights.selectedWorkspace {
WorkspaceInsightRow(
insight: selected,
action: { model.selectWorkspace(selected.id) }
)
}
Divider()
focusQueue(insights)
} else {
waitingState
}
Spacer(minLength: 0)
}
.padding(.horizontal, 12)
.padding(.vertical, 14)
.frame(maxWidth: .infinity, alignment: .topLeading)
}
.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
}

private func header(_ insights: SidebarInsightModel) -> some View {
VStack(alignment: .leading, spacing: 8) {
Text(String(localized: "sampleSidebar.title", defaultValue: "Workspace Signals"))
.font(.system(size: 14, weight: .semibold))
HStack(spacing: 6) {
SummaryPill(value: "\(insights.unreadCount)", label: String(localized: "sampleSidebar.unread", defaultValue: "Unread"))
SummaryPill(value: "\(insights.portCount)", label: String(localized: "sampleSidebar.ports", defaultValue: "Ports"))
SummaryPill(value: "\(insights.pullRequestCount)", label: String(localized: "sampleSidebar.prs", defaultValue: "PRs"))
}
}
}

private func focusQueue(_ insights: SidebarInsightModel) -> some View {
VStack(alignment: .leading, spacing: 7) {
Text(String(localized: "sampleSidebar.focusQueue", defaultValue: "Focus Queue"))
.font(.system(size: 11, weight: .medium))
.foregroundStyle(.secondary)
if insights.focusQueue.isEmpty {
Text(String(localized: "sampleSidebar.noSignals", defaultValue: "No active workspace signals"))
.font(.system(size: 12))
.foregroundStyle(.secondary)
} else {
ForEach(insights.focusQueue) { insight in
WorkspaceInsightRow(
insight: insight,
action: { model.selectWorkspace(insight.id) }
)
}
}
}
}

private var waitingState: some View {
VStack(alignment: .leading, spacing: 8) {
ProgressView()
.controlSize(.small)
Text(model.errorText ?? String(localized: "sampleSidebar.waitingForHost", defaultValue: "Waiting for cmux"))
.font(.system(size: 12))
.foregroundStyle(.secondary)
.fixedSize(horizontal: false, vertical: true)
Button(String(localized: "sampleSidebar.refresh", defaultValue: "Refresh")) {
model.refreshSnapshot()
}
.buttonStyle(.borderless)
.font(.system(size: 12, weight: .medium))
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
import SwiftUI

struct SummaryPill: View {
var value: String
var label: String

var body: some View {
VStack(spacing: 1) {
Text(value)
.font(.system(size: 13, weight: .semibold))
Text(label)
.font(.system(size: 9, weight: .medium))
.foregroundStyle(.secondary)
}
.frame(maxWidth: .infinity)
.padding(.vertical, 5)
.background(.quaternary.opacity(0.35), in: RoundedRectangle(cornerRadius: 6, style: .continuous))
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
import SwiftUI

struct WorkspaceInsightRow: View {
var insight: WorkspaceInsight
var action: () -> Void

var body: some View {
Button(action: action) {
HStack(spacing: 8) {
Image(systemName: insight.isSelected ? "target" : "terminal")
.font(.system(size: 12, weight: .semibold))
.frame(width: 16, height: 16)
.foregroundStyle(insight.isSelected ? .blue : .secondary)
VStack(alignment: .leading, spacing: 2) {
Text(insight.title)
.font(.system(size: 12, weight: .semibold))
.lineLimit(1)
if !insight.subtitle.isEmpty {
Text(insight.subtitle)
.font(.system(size: 10))
.foregroundStyle(.secondary)
.lineLimit(1)
}
signalLine
}
Spacer(minLength: 0)
}
.padding(.horizontal, 8)
.padding(.vertical, 7)
.contentShape(Rectangle())
}
.buttonStyle(.plain)
.background(insight.isSelected ? Color.blue.opacity(0.16) : Color.clear, in: RoundedRectangle(cornerRadius: 6, style: .continuous))
}

private var signalLine: some View {
HStack(spacing: 5) {
if insight.unreadCount > 0 {
Label("\(insight.unreadCount)", systemImage: "bell.badge")
}
if insight.portCount > 0 {
Label("\(insight.portCount)", systemImage: "network")
}
if insight.pullRequestCount > 0 {
Label("\(insight.pullRequestCount)", systemImage: "arrow.triangle.pull")
}
if let branch = insight.branch, !branch.isEmpty {
Label(branch, systemImage: "arrow.branch")
.lineLimit(1)
}
}
.font(.system(size: 9, weight: .medium))
.foregroundStyle(.secondary)
.labelStyle(.titleAndIcon)
}
}
Loading
Loading