Expose workspace label assignment to plugins

[scottt732]

What are you trying to do?

Find the workspace for a given ticket, at a glance, in a list of twenty.

I'm building a Linear plugin. It turns a Linear issue into a worktree workspace plus an agent, and labels the agent linear.issue=ENG-1234. Inside the workspace that binding works well — a composer pill and a turn-end row both key off it.

How do you do it today?

I encode the identifier into the workspace title: ENG-1234 · Enable General logging on cosmos-prod-rabbitmq-blue.

Where does Paseo get in the way?

The title is the only workspace field a plugin controls, and it already has a job: describing the work. A prefix competes with that, can't be filtered or colored, and degrades as soon as anything else wants to prefix it too.

Workspace labels look like the right mechanism and already exist — the protocol defines workspace.label.list.request, workspace.label.assignment.set.request, workspace.label.update.request and workspace.label.delete.request, with a fixed palette (violet, sky, emerald, orange, pink, indigo, teal, red, amber, blue), and the app renders assigned labels as chips on workspace rows. That's exactly the affordance I want.

Plugins can't reach it:

• PluginClientContext has no workspace-row contribution. The full surface is addSettingsScreen, addSurface, addSidebarItem, addWorkspacePanel, addCommandCenterItem, addSlashCommand, addHeaderButton, addComposerPill, addAttachmentSource, addTheme, addTimelineTransformer, addTimelineRenderer.
• PaseoWorkspaceHandle exposes setTitle, archive, refresh, subscribe, agents, terminals — no label read or write.
• The only labels in the client SDK is PaseoAgentCreateOptions.labels?: Record<string, string>, which is agent-scoped and isn't rendered on workspace rows.
• paseo workspace has no label subcommand (setup, create, ls, rename, archive).

So a plugin that creates a workspace can name it, but can't tag it.

What would a better workflow look like?

A plugin that creates workspaces from an external tracker tags each one, and the existing chips do the rest — scanning, and eventually filtering.

This isn't Linear-specific, which is why I'm raising it as a capability rather than a workflow: the same shape applies to any plugin fronting an external system — Jira, GitHub Issues, an internal tracker, an incident tool. Each one wants to say "this workspace is for that thing" in the place a person is already looking.

A minimal shape, mirroring the protocol message:

interface PaseoWorkspaceHandle {
  // …existing members
  readonly labels: {
    list(): Promise<WorkspaceLabel[]>;
    set(label: { name: string; color: WorkspaceLabelColor }, assigned: boolean): Promise<void>;
  };
}

Catalog read access would let a plugin reuse an existing label instead of creating a near-duplicate. Assignment alone would cover the case above; create/update/delete could stay in the app if you'd rather plugins not shape the catalog.

Alternatives I considered

• Encode it in the title — what I do today; described above.
• Agent labels — already set, but not surfaced on workspace rows.
• Speak the protocol directly from the plugin server — rejected. The plugin gets an IPC session rather than a credentialed WebSocket, so this would mean sourcing daemon credentials the plugin isn't given and depending on an unversioned message shape. It would work until an upgrade.

Paseo 0.8.0 (daemon and CLI), macOS, plugin API v0.8.

---

I originally filed this as issue #4689 before reading CONTRIBUTING.md properly — moving it here, and closing that.

[maxwell-01]

Adding a second use case for this, from a different kind of plugin.

Beam mirrors one workspace's working tree onto the user's main checkout, so a running dev server shows that workspace's changes. Only one workspace can be beaming at a time, and with several open the user needs to see which one it is from the workspace list.

Scott's case is a stable tag ("this workspace is ENG-1234"). Beam's is transient state ("this workspace is beaming right now"), which is set and cleared many times a day. Like Scott, the only field we can write is the title, so Beam prefixes it with ⚡ on beam-in and restores it on beam-out.

Transient state makes the title workaround worse than it is for a stable tag, because the plugin must undo its own write:

• If the restore fails, or the daemon dies mid-beam, the ⚡ stays in a field the user owns, and nothing in Paseo will clear it.
• If the user renames the workspace during a beam, a naive restore overwrites their rename. We compare before restoring to avoid that, but we are guessing at intent in the user's own field.

So on top of Scott's proposed shape (labels.list() and labels.set(label, assigned) on PaseoWorkspaceHandle), one extra property would help plugins that hold state: the daemon owns cleanup of a plugin's assignments. For example, plugin-scoped assignments that are removed when the plugin is disabled, reloaded or removed. Then a crash cannot leave a stale badge, and the plugin never writes to a field the user edits.

Checked against 0.9.1: PaseoWorkspaceHandle still exposes setTitle but no label read or write, and PluginWorkspaceSnapshot has no labels field.

[harwal2000]

Adding a GitHub Issues case, and confirming this is still open on 0.11.1.

I run one worktree workspace per GitHub issue, usually 5–10 at once. Paseo already puts the linked PR on the row, but the issue isn't shown, and most of my workspaces have no PR yet: they're still in progress. So the title carries it today ("Fix Esc discarding pending crop framing (#1442)"), with the problems Scott describes.

What I'd build if labels were reachable: a plugin that reads the workspace's issue (from the branch name, the PR's closingIssuesReferences, or a number set when the workspace is created) and assigns a #1442 label. A second label could follow the issue's project-board status, which is the transient-state case @maxwell-01 raised. The plugin-scoped cleanup suggested there would matter for this one too.

Checked against 0.11.1: PaseoWorkspaceHandle still has setTitle and no label read or write, and PluginClientContext has no workspace-row contribution.

[MACscr]

Confirming this is still open on 0.12.0-beta.2: PaseoWorkspaceActions has list/ref/open/create/archive/subscribe and no label methods, and PluginWorkspaceSnapshot does not expose labels.

Our use case: a ClickUp plugin mirrors each task's status onto its workspace as a label (and copies the task's tags). Because the plugin API cannot set labels, the plugin opens its own DaemonClient on ws://127.0.0.1:6767/ws and calls setWorkspaceLabel. That means the plugin needs the daemon password even though normal plugin SDK calls go over trusted IPC, and we keep it in a file because the macOS Keychain is not readable from a launchd-run daemon. Label set/assign on PaseoApi, plus labels on the workspace snapshot, would remove all of that.