Skip to content

How to surface manually created git worktrees in the workspace list? #18414

Closed as not planned

Description

@Cellule

Question

I'm using the experimental workspaces feature (OPENCODE_EXPERIMENTAL_WORKSPACES=true) and I love it for managing parallel work streams. However, I ran into an issue with my workflow and I'm not sure if I'm doing something wrong or if this is a missing feature.

The problem: When I manually create a git worktree outside of opencode (e.g. git worktree add ../my-feature), it doesn't show up in the workspace list in the web UI. Only worktrees created through the "New workspace" button appear.

I sometimes create worktrees manually because I want control over the branch name and directory location, or I'm setting up a worktree from an existing remote branch. Is there a way to register these with opencode after the fact, or is the expectation that all worktrees should be created through the UI?

What I found in the code: The workspace list is driven by the sandboxes array in ProjectTable. This only gets populated when a worktree is created through the API (Worktree.createFromInfo() → Project.addSandbox()). There's no mechanism to discover worktrees that exist in git but aren't registered in the DB — so manual worktrees are invisible.

Some ideas for potential fixes:

  1. Auto-discover on list — when Project.sandboxes() is called, also run git worktree list --porcelain, parse the paths, and auto-register missing ones via addSandbox().
  2. Merge git state at the API layer — have GET /experimental/worktree merge git worktree list results with the DB sandboxes.
  3. Manual registration endpoint — expose something like POST /experimental/worktree/register so users can bring external worktrees into opencode explicitly.

My questions:

  • Is the current behavior intentional — i.e., are workspaces meant to only be managed through opencode?
  • Is anyone else using a workflow that involves manually created worktrees?
  • Would a discovery/sync mechanism be welcome, or would it cause issues with the workspace lifecycle (bootstrap, start scripts, etc.)?

Possibly related: #10060, #13343 — though those are about different aspects of the worktree/workspace UX.

Thanks for any guidance!

Activity

  1. github-actions commented on Mar 20, 2026

    @github-actions
    Contributor

    This issue doesn't fully meet our contributing guidelines.

    What needs to be fixed:

    • No issue template was used. This issue appears to be a question or feature request, but it doesn't follow the Question template (missing the required Question field) nor the Feature Request template (missing the verification checkbox, and the title should start with [FEATURE]:). Please pick the appropriate template and resubmit or edit the issue to match it.

    Please edit this issue to address the above within 2 hours, or it will be automatically closed.


    This issue might be a duplicate of or closely related to existing issues. Please check:

    If you believe this was flagged incorrectly, please let a maintainer know.

  2. added
    needs:complianceThis means the issue will auto-close after 2 hours.
    and removed
    needs:complianceThis means the issue will auto-close after 2 hours.
    on Mar 20, 2026
  3. github-actions commented on Mar 20, 2026

    @github-actions
    Contributor

    Thanks for updating the issue! It now follows the Question template with clear, substantive content. The compliance flag has been removed.

  4. Cellule commented on Mar 20, 2026

    @Cellule
    Author

    I'm using this script now to create a sandbox in opencode from my worktrees that are missing

    Details

    #!/usr/bin/env bash
    # oc-sync-worktrees.sh — Register all untracked git worktrees with opencode
    #
    # Usage: oc-sync-worktrees.sh [/path/to/repo]
    #        Defaults to current directory.
    
    set -euo pipefail
    
    PROJECT_DIR="$(cd "${1:-.}" && pwd)"
    DB="${XDG_DATA_HOME:-$HOME/.local/share}/opencode/opencode.db"
    
    if [ ! -f "$DB" ]; then
      echo "error: opencode database not found at $DB" >&2
      exit 1
    fi
    
    # Find the project row by its worktree path
    ROW=$(sqlite3 "$DB" "SELECT id, sandboxes FROM project WHERE worktree = '$PROJECT_DIR';")
    if [ -z "$ROW" ]; then
      echo "error: no opencode project found for $PROJECT_DIR" >&2
      exit 1
    fi
    
    PROJECT_ID=$(echo "$ROW" | cut -d'|' -f1)
    SANDBOXES=$(echo "$ROW" | cut -d'|' -f2)
    
    # Get all git worktree paths (skip the main worktree)
    MAIN=$(git -C "$PROJECT_DIR" worktree list --porcelain | head -1 | sed 's/^worktree //')
    WORKTREES=$(git -C "$PROJECT_DIR" worktree list --porcelain | grep '^worktree ' | sed 's/^worktree //' | grep -v "^${MAIN}$" || true)
    
    if [ -z "$WORKTREES" ]; then
      echo "no secondary worktrees found"
      exit 0
    fi
    
    MISSING=()
    while IFS= read -r wt; do
      if echo "$SANDBOXES" | grep -q "$wt"; then
        echo "  already registered: $wt"
      else
        echo "  missing: $wt"
        MISSING+=("$wt")
      fi
    done <<< "$WORKTREES"
    
    if [ ${#MISSING[@]} -eq 0 ]; then
      echo "all worktrees are registered"
      exit 0
    fi
    
    # Build updated JSON array
    NEW="$SANDBOXES"
    for wt in "${MISSING[@]}"; do
      if [ "$NEW" = "[]" ]; then
        NEW="[\"$wt\"]"
      else
        NEW="${NEW%]},\"$wt\"]"
      fi
    done
    
    sqlite3 "$DB" "UPDATE project SET sandboxes = json('$NEW'), time_updated = $(date +%s000) WHERE id = '$PROJECT_ID';"
    echo ""
    echo "registered ${#MISSING[@]} worktree(s)"

  5. dzianisv commented on Mar 29, 2026

    @dzianisv

    I fixed this downstream in my fork and merged it to main.

    References:

    • fork PR: dzianisv/opencode#89
    • fork branch commit: e5d02d8a89014ea36b1e81a0fad34aee4f9838cd
    • fork merge commit: 6338e0b406c90a330a84725dfcdbef1d8221430e

    Fix summary:

    • refresh worktree/sandbox state from git worktree list --porcelain
    • surface existing/manual worktrees without requiring OpenCode-managed creation paths
    • keep stale/non-existent sandbox entries pruned while preserving the current sandbox path when applicable

    Validation on the fork package:

    • cd packages/opencode && bun test
    • cd packages/opencode && bun typecheck
  6. rekram1-node commented on Jun 23, 2026

    @rekram1-node
    Contributor

    Automated: closing question issues.

    GitHub Issues are for bug reports and feature requests only — questions / support are no longer tracked here.

    If this is a bug or feature request, please open a new issue with the appropriate template.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions