Repository navigation
Description
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Note: #1543 requests the same concept. This issue adds a concrete implementation proposal and references the broader set of related symlink issues.
Describe the enhancement you want to request
When working across multiple projects (e.g., a frontend and backend in separate repos, or a shared library), OpenCode can only see files in the directory it was launched from. Files in other directories aren't indexed for @ file search, and reading/writing them triggers permission prompts every time.
This is a common workflow. VS Code and Cursor solve it with "Add Folder to Workspace", which lets you bring additional directories into your current session. OpenCode doesn't have an equivalent.
Related issues:
- [Feature Request] Adding directories / creating workspaces #1543 Adding directories / creating workspaces
- OpenCode can't see symbolic link files/folders #747 Symlinked files/folders not visible
- Symlinked directories not visible in project picker (opencode serve) #10365 Symlinked directories not visible in project picker
- Does OpenCode not recognize the reference paths of symbolic links? in windows 11 #16342 Symbolic links not recognized on Windows
- Directory symlink displayed as empty file #18963 Directory symlink displayed as empty file
- [FEATURE]: Enhanced Workspace Support: Custom Settings & Creation Dialog #13592 Enhanced Workspace Support
- [FEATURE]: Multi-project core and API #13623 Multi-project core and API
Multiple PRs (#10366, #11351, #12992, #18291) have tried fixing symlink following, but none have landed. PR #18291 showed that global --follow causes Windows CI timeout due to junction loops. The symlink approach is fundamentally fragile.
Proposed solution: add a workspace field to opencode.jsonc:
{
"workspace": ["../backend", "~/src/shared-lib"]
}Directories listed here would be:
- Indexed for
@file search (visible in fuzzy picker) - Accessible without external directory permission prompts
- Watched for file changes
They would not affect snapshots, git operations, project identity, or the existing desktop "workspace" feature (git worktrees). Workspace folders are independent trusted directories that don't participate in branching or undo/redo.
Why this approach:
- Explicit over implicit: no surprise expansion from symlinks or junctions
- Cross-platform: works on Windows, macOS, Linux without junction/symlink issues
- Small surface area: the main change is extending
Instance.containsPath()andFile.scan()(~50 lines) - Familiar pattern: similar to Cursor/VS Code's workspace folders concept
Longer term, workspace folders could be managed directly through the UI (desktop, web, TUI), e.g. an "Add Folder" action that updates the config without manual editing.
Happy to implement this if the approach sounds reasonable.
Activity
[-]feat: workspace folders — explicit multi-directory support[/-][+][FEATURE]: workspace folders — explicit multi-directory support[/+]github-actions commentedon Mar 28, 2026
Thanks for updating the issue! It now meets our contributing guidelines. We appreciate you taking the time to improve the submission.
jeroenev commentedon Apr 2, 2026
Looks good, I had a PR that makes following Symlinks opt-in, which means you can just symlink the required folders in your project and start working
but this way also makes a lot of sense
paul-vd commentedon Apr 23, 2026
Use case: umbrella coordination repo with 15+ nested git repos
We use a coordination repo for cross-repo planning (OpenSpec artifacts, specs, tasks) with 15 independent product repos cloned into a gitignored
projects/directory. Agent sessions routinely span the umbrella and 2-3 project repos in a single session.File search is already solved, we work around the indexing limitation by adding
!projects/*to a.ignorefile (docs), which makes ripgrep include project files for@search. This works well.The remaining gap is git diff visibility. When the agent edits files inside
projects/acme-backend/, OpenCode Desktop's diff panel shows nothing, because OpenCode resolves the git root by walking up fromcwdto the nearest.git, and never scans for nested git repositories within the workspace. Each project has its own.gitthat OpenCode doesn't detect.This means:
Request: When workspace folders land, they should also register additional git roots for the diff panel, not just file indexing and permission scoping. VS Code handles this via
git.autoRepositoryDetection, which scans for nested.gitdirectories and adds each as a separate Source Control provider.For the workspace folders feature, git awareness would mean:
.gitin each workspace folder (or its children)This is currently the biggest workflow friction for multi-repo development in OpenCode Desktop. File search and permissions are solvable with
.ignore, diff blindness is not.msangals commentedon May 27, 2026
Hey @kitlangton, I saw this issue is assigned to you, so I wanted to check in directly.
There seems to be strong interest in solving this properly: this issue already has 31 👍 reactions, #1543 has 131 👍, and there are several related issues/PRs around symlinks and multi-directory workflows that never quite landed.
I’d really appreciate your view on whether this is aligned with how you’d like to see this solved. If the direction makes sense, I’m happy to discuss this further.
oeholmen commentedon Jun 3, 2026
One major use case is having an api in one repo, and multiple front ends consuming the api. It is very useful to be able to work across API+affected front ends for a single, focused change.
treddington4 commentedon Jul 17, 2026
Use case: Yocto/OpenBMC multi-repo workspaces
I work on embedded firmware with Yocto/OpenBMC. A dev workspace has 5–15 independent git repos that are all related but don't share a common git root:
Repos get pulled in through
devtool modify, provisioning scripts, or just cloning. Most are git worktrees off a central clone. The workspace root is not a git repo — it's just the directory that ties everything together, with its own config and scripts.Fixing a bug or adding a feature usually touches 3–4 of these repos at once. A new sensor means changes in the meta-layer recipe, the kernel driver, the userspace daemon, and the test suite. Splitting that across separate OpenCode sessions kills the context that makes the agent useful in the first place.
What works fine: the agent can read/write files everywhere, and I can have it run
git difforgit statusinside any sub-repo via bash.What's broken: the Changes panel in the TUI and desktop app is completely empty. OpenCode walks up from
cwdlooking for a.git, doesn't find one, and disables all git integration. No diff view, no change tracking, no undo/snapshots across the workspace.I dug into the source to understand the scope:
packages/core/src/git.ts—discover()finds one.gitby walking upward. Returns one repo or nothing.packages/opencode/src/project/project.ts— calls discover, sets git mode on or off for the whole session.packages/opencode/src/project/vcs.ts— every diff/status operation checksctx.project.vcs !== "git"and bails if it's not set. All operations target a single directory.So the change is pretty contained. A
discoverAll()that scans workspace folder children for.gitentries, plus making the diff/status functions iterate over multiple repos with path prefixes, would cover it. The UI doesn't need to change — it already renders a list of file diffs.This lines up with @paul-vd's comment. The
"workspace"config proposed here is the right hook — it just needs to also register git roots for the diff panel, not only file indexing and permissions.I put together a minimal patch that adds child-repo discovery to the existing git integration. It's working for us — the Changes panel now shows diffs from all nested repos when the workspace root has no
.gitof its own.Two files touched:
packages/core/src/project.ts— whendiscover()finds no.gitat the root, scans immediate children and one level deeper for child repos. If any are found, setsvcs: "git"so the rest of the pipeline doesn't bail out.packages/opencode/src/project/vcs.ts—status(),diff(), anddiffRaw()now also scan for child repos and aggregate their results with path prefixes. Existing single-repo behavior is untouched — the child-repo scan runs in addition to, not instead of, the root repo path.No changes to types, schemas, snapshots, undo, or the UI. Tested against a workspace with 9 independent git worktrees under
src/.Not proposing this as a PR — just sharing what's working for us in case it's useful as a reference for whoever picks this up. Aware that #24589 is a full multi-root implementation.
git format-patch (2 files, +257 -42) — apply with
git amgithub-actions commentedon Sep 17, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.