Skip to content

feat: support linked nested repos in pane workspaces#90

Open
xiao-do-do wants to merge 5 commits into
standardagents:mainfrom
xiao-do-do:feat/linked-repo-workspaces
Open

feat: support linked nested repos in pane workspaces#90
xiao-do-do wants to merge 5 commits into
standardagents:mainfrom
xiao-do-do:feat/linked-repo-workspaces

Conversation

@xiao-do-do
Copy link
Copy Markdown
Contributor

@xiao-do-do xiao-do-do commented May 11, 2026 •
edited
Loading

Summary

This PR adds support for linked nested repositories
inside a pane workspace.

Previously, dmux only managed the root repository for
a pane worktree. With this change, a pane can also
carry selected project-relative nested git
repositories through the same lifecycle as the root
repo, so create, reopen, resume, bootstrap, and
cleanup stay aligned.

This is different from Create Child Worktree: that
feature creates a new pane/worktree from an existing
pane branch, while this PR lets a single pane
workspace manage multiple related repositories
together.

What changed

  • add pane-level linked child repo selection in the new pane flow
  • persist linked repo metadata in worktree state
  • carry linked repos through reopen and resume flows
  • keep linked repos aligned during bootstrap and cleanup
  • add coverage for linked repo config, metadata, reopen/resume flows, and pane
    lifecycle integration

Testing

  • pnpm run typecheck
  • targeted tests for linked repo lifecycle behavior

@justin-schroeder
Copy link
Copy Markdown
Collaborator

justin-schroeder commented May 13, 2026

Is this different than creating a child worktree?

image

maybe you could provide some screenshots or other information about the PR and how you envision it working.

@xiao-do-do
Copy link
Copy Markdown
Contributor Author

xiao-do-do commented May 14, 2026

Yes — this is different from creating a child worktree.

Create Child Worktree creates a new pane/worktree from the
currently selected pane's branch.

This PR is about letting a single pane workspace manage
the root repo plus selected nested git repos together
through the same lifecycle:

  • create
  • reopen
  • resume
  • bootstrap
  • cleanup

Example use case:

  • app/ is the root repo
  • app/frontend/ is a separate git repo
  • app/backend/ is another separate git repo

With this PR, when creating a pane for a task, dmux can carry
the root repo and the selected nested repos together in one pane
workspace, instead of treating them as separate panes or only
managing the root repo.

So this is not “another child worktree” feature — it is
“multi-repo pane workspace lifecycle” support.

I’ll update the PR description and add screenshots to make
that clearer.

@xiao-do-do xiao-do-do changed the title feat: Support nested child repos in pane worktrees feat: support linked nested repos in pane workspaces May 14, 2026
@xiao-do-do
Copy link
Copy Markdown
Contributor Author

xiao-do-do commented May 14, 2026 •
edited
Loading

This PR adds support for linked nested repositories inside a
pane workspace.

Previously, dmux only managed the root repository for a pane
worktree. With this change, a pane can also carry selected
project-relative nested git repositories through the same
lifecycle as the root repo, so create, reopen, resume,
bootstrap, and cleanup stay aligned.

This is different from Create Child Worktree: that feature
creates a new pane/worktree from an existing pane branch, while
this PR lets a single pane workspace manage multiple related
repositories together.

When creating a pane, the user can optionally select nested repositories under
the project root.

image image

dmux then keeps the root repo and those selected nested repos aligned through
the same pane lifecycle:

  • create the pane workspace
  • persist linked repo metadata
  • reopen/resume the same linked repos later
  • bootstrap them together
  • clean them up together

This is aimed at setups like frontend/backend repos stored as separate nested
git repositories under one project directory.

xiao-do-do added 3 commits May 14, 2026 15:42
@xiao-do-do
feat: support nested child repos in pane worktrees
6ddbd2e 
Projects can contain child repos under the root repo. This adds pane-level support for selecting those child repos and carrying them through the same worktree lifecycle as the root repo, so create, reopen, resume, bootstrap, and cleanup keep the pane's related repos together.

Constraint: Preserve existing root-only behavior and keep child repo paths project-scoped and relative

Rejected: Treating child repos as separate panes | one task should keep root and child repo changes in the same pane lifecycle

Confidence: high

Scope-risk: moderate

Directive: Keep root and nested child repo lifecycle behavior aligned when changing pane creation, reopen/resume, bootstrap, or cleanup

Tested: pnpm run typecheck; pnpm vitest run __tests__/linkedRepoConfig.test.ts __tests__/worktreeMetadata.test.ts __tests__/reopenWorktree.test.ts __tests__/resumeBranches.test.ts __tests__/worktreeCleanupService.test.ts __tests__/integration/paneLifecycle.test.ts; pnpm vitest run
@xiao-do-do
Clarify linked nested repo terminology
306a632 
Constraint: Avoid confusion with the existing Create Child Worktree feature
Rejected: Keep 'child repos' wording | Too easy to confuse with child worktrees
Confidence: high
Scope-risk: narrow
Directive: Prefer 'linked nested repos' in user-facing copy for pane-scoped multi-repo workspaces
Tested: pnpm vitest run __tests__/popupManager.newPanePopup.test.ts __tests__/integration/paneLifecycle.test.ts __tests__/reopenWorktree.test.ts __tests__/paneRestore.test.ts
Not-tested: Full manual UI review on all locales
@xiao-do-do
Keep popup settings refresh test stable across local defaults
dc09f77 
Constraint: The popup settings refresh test must not depend on ambient git-options defaults from a developer machine
Rejected: Assert a hardcoded git-options flag value | The test only needs to verify refreshed goal-mode settings
Confidence: high
Scope-risk: narrow
Directive: Keep popup argument assertions focused on the behavior under test when unrelated defaults can vary
Tested: pnpm vitest run __tests__/popupManager.newPanePopup.test.ts __tests__/integration/paneLifecycle.test.ts __tests__/reopenWorktree.test.ts __tests__/paneRestore.test.ts __tests__/linkedRepoConfig.test.ts __tests__/worktreeMetadata.test.ts __tests__/resumeBranches.test.ts; pnpm run typecheck
Not-tested: Full test suite
@xiao-do-do xiao-do-do force-pushed the feat/linked-repo-workspaces branch from b650587 to dc09f77 Compare May 14, 2026 07:45
@xiao-do-do
Copy link
Copy Markdown
Contributor Author

xiao-do-do commented May 14, 2026

I refreshed this branch on top of the current
upstream main and force-pushed the updated history.

Also, I renamed the user-facing terminology from
“Linked Child Repos” to “Linked Nested Repos” to
avoid confusion with the existing “Create Child
Worktree” feature.

This PR is about allowing a single pane workspace to
carry the root repo plus selected nested git repos
through the same lifecycle (create, reopen, resume,
bootstrap, cleanup). It is separate from creating a
child worktree from an existing pane branch.

I also validated the linked repo flow with targeted
tests and typecheck on the refreshed branch.

@xiao-do-do
Prevent linked nested repos from blocking root merges
2d39c44 
Constraint: Root merge validation must treat linked nested repos as independent repos while still surfacing real root-repo changes
Rejected: Force users to commit or ignore nested repo dirs manually | contradicts linked nested repo lifecycle support and keeps merge UX broken
Confidence: high
Scope-risk: narrow
Directive: Keep root merge status filtering aligned with worktree metadata and dmux-managed agent state scaffolding
Tested: pnpm run typecheck; pnpm exec vitest run __tests__/mergeValidation.test.ts __tests__/actions/createPullRequestAction.test.ts __tests__/linkedRepoConfig.test.ts __tests__/integration/paneLifecycle.test.ts __tests__/reopenWorktree.test.ts __tests__/paneRestore.test.ts __tests__/resumeBranches.test.ts
Not-tested: Full interactive tmux merge flow after rebuilding dist in a live dmux session
@xiao-do-do xiao-do-do closed this May 14, 2026
@xiao-do-do xiao-do-do reopened this May 14, 2026
@xiao-do-do xiao-do-do closed this May 14, 2026
@xiao-do-do
Handle gitlink placeholder dirs when attaching linked repo worktrees
0ddb965 
Constraint: Root worktree checkout can create empty gitlink placeholder directories before child repo worktrees attach
Rejected: Failing on any pre-existing directory | blocks valid linked repo bootstrap for gitlink layouts
Confidence: high
Scope-risk: narrow
Directive: Keep linked child repo attach strict for non-empty directories while allowing safe empty placeholder replacement
Tested: user-reported full test; pnpm run typecheck; pnpm exec vitest run __tests__/linkedWorktrees.test.ts __tests__/reopenWorktree.test.ts __tests__/resumeBranches.test.ts
Co-authored-by: OmX <omx@oh-my-codex.dev>
@xiao-do-do xiao-do-do reopened this May 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@xiao-do-do @justin-schroeder