Workspaces are an advanced feature for working on multiple tasks in the same project at the same time. If you’re not doing software development on a Git repository, you can skip this lesson — workspaces won’t apply to your workflow.
The problem workspaces solve
When you run two OpenCode sessions on the same project simultaneously, they’re both working on the same files. If session A is refactoring one part of the codebase while session B is adding a feature in another, they can accidentally overwrite each other’s changes. At best, you lose work. At worst, you don’t notice and end up with a broken project.
This is the same problem Git branches solve for human developers working in parallel. Workspaces solve it for parallel OpenCode sessions.
What workspaces are
A workspace is a complete, isolated copy of your project files on its own Git branch. Each workspace has its own files and its own sessions. Changes made in one workspace don’t affect any other workspace.
It’s similar in concept to Git branching — you’re working on an isolated version of the codebase — but instead of all branches sharing a single working directory, each workspace gets its own separate directory on disk.
How to create a workspace
Workspaces are a Desktop-only feature. Your project must be a Git repository.
- Right-click the project in the left sidebar in OpenCode Desktop
- Select Enable Workspaces
- Click New Workspace to create an isolated copy
Each workspace gets an auto-generated name. You can create as many as you need — one per task, one per experiment, or however you want to organize your work.
What happens under the hood
When you create a workspace, OpenCode uses Git worktrees to create a new branch named opencode/<name> and checks it out to a separate directory on disk. The result is a fully independent copy of your project at the current state of your main branch.
When you’re done with a workspace, merge its branch back into your main branch via Git — the same way you’d merge any other feature branch.
When to use workspaces
Workspaces are most useful when you want to:
- Run two or more long-running sessions on the same project simultaneously
- Experiment with a risky change without touching your main working directory
- Work on independent tasks in parallel and merge the results when each is ready
For single-session work, or for projects that aren’t Git repositories, you don’t need workspaces.