Skip to content

[Feature]: Per-worktree Claude account binding (concurrent multi-account + per-project defaults) #6921

Closed

Description

@srs-adamr

Problem or use case

Summary: Let each worktree bind to a specific Claude managed account, so multiple worktrees can run different accounts at the same time.

Today, Claude account selection is global per host (activeClaudeManagedAccountId / activeClaudeManagedAccountIdsByRuntime, resolved in src/main/claude-accounts/runtime-selection.ts). New launches inherit the one active account, and switching is global — it re-materializes shared ~/.claude and is gated against live sessions (live-pty-gate). So you can't run worktree A on a work account and worktree B on a personal account concurrently, and per-project defaults aren't possible.

This is the concurrency superset of the per-project requests in #5203 and #5635, and it's the workflow heavy parallel-agent users hit immediately (e.g. spreading load across accounts, or keeping work and personal subscriptions separated per worktree).

Proposed solution

Add an optional claudeAccountId bound to the worktree (first-class, not per-PTY), and at launch inject that account's CLAUDE_CONFIG_DIR instead of materializing creds into shared ~/.claude.

The mechanism already exists in-tree: Orca's WSL path does exactly this per-account injection (src/main/claude-accounts/runtime-auth-service.ts:640-648 → { configDir: managedAuthPath, envPatch: { CLAUDE_CONFIG_DIR }, stripAuthEnv: true }). The host path is the only one that materializes instead. Proposal: when a worktree has an assigned account, the host path returns the same WSL-shaped injection and doSyncForCurrentSelection early-returns — bypassing materialization, the live-pty-gate switch block, and read-back. Unassigned worktrees are unchanged (purely additive).

Binding & resolution (pinning across agent churn). The assignment is durable worktree metadata (claudeAccountId on WorktreeMeta), resolved fresh at every spawn (worktreeId → account → CLAUDE_CONFIG_DIR, injected per-terminal and inherited by child agents). Nothing global is mutated and nothing is cached on the agent, so agents spawning/despawning in any order across worktrees stay deterministically pinned to their worktree's account (e.g. 6 worktrees split 2-on-account-A / 4-on-account-B, cycling agents continuously, never drift).

Isolation unit = account/config-dir; refresh is CLI-owned. Multiple worktrees may bind the same account (in the example above, 2 config dirs with several live tenants each), so config dirs are multi-tenant. Crucially, doSyncForCurrentSelection early-returns for injected accounts — Orca does no proactive refresh, read-back, or materialization for a pinned account; each Claude CLI manages its own config dir's tokens. So the multi-tenant refresh race is owned by the Claude CLI per config dir (Orca isn't doing the refresh and so can't lock it), and injected accounts never touch the shared ~/.claude runtime. The only coordination change needed is exempting injected launches from the global isClaudeAuthSwitchInProgress switch-block (they don't use shared creds, so a global account switch must not stall a pinned-worktree launch) — no new lock or gate rearchitecture. Token rotation (#6234) is preserved: each injected dir is single-tenant from Orca's side and the CLI refreshes it in place.

Cross-platform (verified — src/main/claude-accounts/keychain.ts credential ops are darwin-only no-ops):

Platform Work needed
Linux / Windows / SSH-remote host None — file-based; simpler than today's materialize-to-shared
WSL Already shipped (this is the WSL path)
macOS Seed the scoped Keychain service Claude Code-credentials-<sha256(configDir)[:8]> once per launch (reuse getActiveClaudeService)

UI: account selector in the create-worktree modal (beside the Agent picker in NewWorkspaceComposerCard) + an "Assign Account" submenu in WorktreeContextMenu (mirroring "Move to Status"). Accounts filtered by the worktree's runtime (a WSL worktree binds a WSL account, etc.).

We're ready to implement this and open the PR. We've already traced the full implementation path — data model on WorktreeMeta, launch-time resolution in pty.ts, the host-injection branch in runtime-auth-service.ts, exempting injected launches from the global switch-block, and the two UI surfaces — and can start as soon as you confirm the approach fits your intended direction. We're raising the design first only to align before writing code. v1 scope: binding + launch injection + the two UI surfaces; per-worktree usage/rate-limit display deferred as a documented limitation. Happy to adjust scope or structure to match your preferences.

Alternatives or additional context

Activity

  1. srs-adamr commented on Jun 30, 2026

    @srs-adamr
    ContributorAuthor

    Implemented in #6963 (draft) — branch srs-adamr/feat-per-worktree-claude-account, rebased on current main. Covers the additive claudeAccountId binding, host injection reusing the WSL path, the macOS scoped-keychain seed, the switch-block exemption, and the two UI surfaces (account selector + Assign Account submenu). Zero new test failures vs main.

  2. added theissue type on Jul 12, 2026
  3. metheoryt commented on Aug 1, 2026

    @metheoryt

    Answering your open question — "preferred home for the binding (on WorktreeMeta, following the workspaceStatus precedent?)" — with a suggestion for one extra tier in the resolution chain: project group.

    To be clear up front: per-project (this issue's per-project defaults, plus #5203 / #7782) already covers my immediate need, and it satisfies the #10922 constraint the same way — a static binding resolved at spawn, rather than a runtime switch. So this is not "group instead of project". The narrower claim is that group is the zero-config inheritance tier: drop a new repo into an existing group and it is already bound, with no per-repo step. For anyone who organises the sidebar by client/employer/personal, that's the difference between binding once and binding once per repo forever.

    Orca already scopes a runtime-affecting setting to a project group

    This isn't a new mechanism — executionHostId on ProjectGroup already does exactly this, and the resolver shape you'd need for accounts is shipped. Derived from the packaged bundle (v1.4.162), so worth confirming against source, but the behaviour is:

    • Repo → group fallback. Resolving a repo's execution host looks up the repo's projectGroupId, finds that group, and uses the group's executionHostId; the repo's own value wins and the group is the fallback. The same repo-then-group precedence is applied to connectionId.
    • Folder workspaces too. folderWorkspaceId → its folder workspace → projectGroupId → group → executionHostId.
    • Ancestor walk already exists. Groups nest via parentGroupId, and there is already a cycle-guarded walk up the parent chain (used for the group breadcrumb path). So inheritance through nested groups needs no new traversal.
    • The group-scoped resolution is a named concept in the bundle (GroupExecutionHostId, GroupExecutionHostIdForRows, GroupExecutionHostIdForFolderPathStatus), not an ad-hoc lookup.

    The ask, in one sentence

    Put the account binding on ProjectGroup alongside executionHostId, and resolve it through the same precedence walk: worktree → repo → group chain (via parentGroupId) → global.

    That composes with the worktree binding proposed here rather than competing with it — worktree stays the most specific tier, and #7782's proposed hierarchy just gains one level between project and global.

    Durability note

    projectGroups is persisted config, not transient sidebar state — it lives in orca-data.json with id, name, parentGroupId, connectionId, createdAt / updatedAt, etc. But it is per-profile and machine-local: the file sits under profiles/<profile>/, so a group binding would not follow a user to a second machine. That's fine for the execution-host precedent (hosts are machine-specific anyway) and probably fine for accounts, but it is worth being deliberate about, since an account identity is conceptually portable in a way an execution host isn't.

    Related: #7782 (project/worktree hierarchy), #5203, and #10922 — on a headless orca serve runtime, account switching does not work at all, which makes a static bound-at-spawn account the only viable model there rather than a convenience.

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

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestsize/lLarge PR (≤2500 added lines, ≤50 files)

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions