[FEATURE]: Support explicit workspace naming and make workspace sessions run in the workspace directory via the plugin API

Feature hasn't been suggested before.

I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

What problem am I trying to solve?

I'm experimenting with OpenCode workspaces as a way to organize parallel streams of work in the UI.

At the moment, a plugin can successfully:

create a workspace
create a session with a workspaceID
switch the UI to that session

That already makes workspaces useful for grouping and navigation.

The problem is that two important pieces are still missing:

I can't give a workspace a meaningful name that OpenCode actually preserves
sessions created for a workspace still seem to run built-in tools in the repo root, not in the workspace directory

What feature would I like?

I'd like workspaces to support both of these things:

allow callers to provide a meaningful workspace name and/or branch that is actually used
make a session created for a workspace execute built-in tools in that workspace's directory

What does the current behavior look like?

Right now, even if I request a semantic branch like opencode/fix-hook-routing, OpenCode still creates workspaces with generated names like:

glowing-star
stellar-cabin

Also, even when a session is created with a workspaceID, the session still points at the repo root directory.

For example:

workspace directory:
~/.local/share/opencode/worktree/.../glowing-star
session directory:
/path/to/repo-root

If I run bash pwd in that workspace-bound session, it still returns the repo root.

What would the ideal behavior be?

Something like this:

{
  "type": "worktree",
  "name": "fix-hook-routing",
  "branch": "opencode/fix-hook-routing"
}

And OpenCode would preserve that when creating the workspace.

Then, if a session is created for that workspace:

session.workspaceID points to the workspace
session.directory is the workspace directory
built-in tools like bash, write, edit, and apply_patch run there by default

Why would this help?

It would make workspaces much more useful for real multi-workstream workflows.

It would help with:

clearer, topic-based workspace/session naming in the UI
better organization of parallel work
a cleaner plugin/workspace integration model
using workspaces as an actual execution boundary, not just a UI grouping concept

Additional context

I tested this with a local plugin prototype and local OpenCode Web instance.

What works today:

workspace creation
session creation with workspaceID
switching the UI to the new session

What doesn't work yet:

semantic naming is not preserved
built-in tool execution still happens in repo root
session is not associated with the workspace

I was logged in with my agent account, but it is a real feature request :)

I don't have the same behavior as you do.

Example:

Also, being able to name Workspaces exists already, it's just hard, in the GUI, to find out what branch we are on, and therefor I need to name my workspaces like [branch-name] feature name. But it's fine I guess.

Let me clarify:

I built a small plugin prototype to test whether workspace bootstrap can be done from plugin code rather than manually through the UI.

What the prototype does successfully:

creates a workspace via experimental.workspace.create(...)
creates a session bound to that workspace via session.create({ workspaceID })
switches the UI to that session via tui.selectSession(...)

What is still not solved:

the created session still reports the repo root as session.directory
built-in tools still execute in repo root instead of the workspace directory
semantic naming is not preserved reliably, because OpenCode still chooses its own workspace name/branch
the plugin-provided client did not expose the needed workspace APIs directly, so I had to create my own @opencode-ai/sdk/v2 client from serverUrl

So the missing capability is not just “GUI switching”, but “plugin-created workspaces becoming the real execution root for the session”.

I’m aware this is still an experimental feature, so I’m sharing this mainly as informative feedback and as a signal of capability interest.

Adding another use case to support this request.

I have a project-level plugin (.opencode/plugins/worktree.ts) that creates a git worktree for each session on session.created. The worktrees are created correctly, but the session directory is always the repo root — so built-in tools like bash, read, and edit still run there instead of in the worktree.

What I'd like is a way to configure this in opencode.json so that every new session automatically gets its own worktree workspace and runs tools there. Something like:

{
  "experimental": {
    "workspace": {
      "type": "worktree"
    }
  }
}

This would make the worktree the default execution context for all sessions in that project, without requiring manual workspace selection in the TUI each time.

@KochC

@KochC i can second your findings, this was my first approach and I ran into the same limitations. As I understand it, you cant mutate the current active workdir from within a plugin, or at least it is not getting propagated to tools. I tried a different hook, but observation was as you just described.

await Plugin.trigger("tool.execute.before", ..., { args: args3 });
const result = await item.execute(args3, ctx);

So if a plugin is able to change the current working directory in a running session, one could make the switch and build up custom workflows. It might also be, that this is intended to create immutable session runtime for stability / security concerns. However, then i would appreciate to be able to at least fork the session with respective runtime settings (e.g. a worktree path becoming the sessions working directory) adjusted for the tools.

Then my above suggestions would even become obsolete :)

I feel like some core features (especially the custom workspace naming) are also discussed in #13592, however my request here goes beyond the manual UI task.

Since a new workspace gets assigned to its own session and the path of the working directory is switched to the assigned work-tree path already in the latest OpenCode versions, I would really love to see this access level possible from within a plugin to enhance customization of workflows in OpenCode.

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Navigation Menu

Repository navigation

[FEATURE]: Support explicit workspace naming and make workspace sessions run in the workspace directory via the plugin API #20262

Feature hasn't been suggested before.

Describe the enhancement you want to request

What problem am I trying to solve?

What feature would I like?

What does the current behavior look like?

What would the ideal behavior be?

Why would this help?

Additional context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: Support explicit workspace naming and make workspace sessions run in the workspace directory via the plugin API #20262

Description

Feature hasn't been suggested before.

Describe the enhancement you want to request

What problem am I trying to solve?

What feature would I like?

What does the current behavior look like?

What would the ideal behavior be?

Why would this help?

Additional context

Activity

sven1103 commented on Mar 31, 2026

jacquesbh commented on Apr 1, 2026

sven1103 commented on Apr 1, 2026

KochC commented on Apr 1, 2026

sven1103 commented on Apr 1, 2026

sven1103 commented on Apr 8, 2026

github-actions commented on Jul 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions