You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat: shared squad — external state backend for multi-clone workflows #958
Some development workflows involve multiple clones of the same repository (worktrees, parallel clones, CI build environments, #multiple dev machines). In these environments:
Branch switches can destroy untracked files including .squad/
Multiple checkouts of the same repo each need their own squad init - duplicating team identity
Team identity, decisions, and agent knowledge can't be shared across clones
.squad/ committed to the repo isn't viable for large repos with strict policies on untracked content
In very large monorepos, teams often work in isolated subtrees — committing .squad/ at the repo root may not be practical or permitted
Proposed Solution
Enable squad team state to live outside the repository — in a user-managed directory (git-backed squad repo or platform app data directory). Discovery happens via origin URL matching against a lightweight registry at ~/.squad/squad-repos.json.
Key design points
Zero repo writes — shared mode writes nothing to the target repository
URL-based matching — git remote get-url origin matched against registry patterns (GitHub, ADO, SSH URL forms all normalized)
Git-backed squad repos — team state lives in its own repo, committable and shareable across machines
Per-clone runtime state — clone-local ephemeral data stored under the platform's local app data directory (Windows/macOS/Linux)
Cross-platform — ~/.squad/ pointer on all platforms; local data uses platform-appropriate paths
New commands
squad init --shared — create or connect to a shared squad
For context: PR #797 (merged to insider Apr 5) already implements the foundation — \squad externalize\ moves .squad/ state to a platform-specific global directory, keyed by repo path. This solves the 'branch switches destroy state' and 'state not in VCS' parts.
PR #959 (from @akubly) extends this with URL-based registry discovery (~/.squad/squad-repos.json), git-backed shared squad repos, per-clone runtime state, and the \squad init --shared\ / \squad shared status|diagnose|list|doctor\ CLI surface.
So #797 = external/local mode, #959 = shared/discovered mode on top. They're complementary, not competing. #959 should be reviewed as an extension that builds on #797's
esolveExternalStateDir()\ foundation.
Key dedup point: the resolution chain in #959 should check #797's external state as one of its discovery steps (which it appears to do — local .squad/ → external state → shared registry).
Activity
tamirdresher commentedon Apr 11, 2026
hi @akubly
i believe we already solved that, look here: https://github.com/bradygaster/squad/blob/dev/docs/src/content/docs/features/external-state.md
it's in the insider version
am i missing something?
tamirdresher commentedon Apr 12, 2026
For context: PR #797 (merged to insider Apr 5) already implements the foundation — \squad externalize\ moves .squad/ state to a platform-specific global directory, keyed by repo path. This solves the 'branch switches destroy state' and 'state not in VCS' parts.
PR #959 (from @akubly) extends this with URL-based registry discovery (~/.squad/squad-repos.json), git-backed shared squad repos, per-clone runtime state, and the \squad init --shared\ / \squad shared status|diagnose|list|doctor\ CLI surface.
So #797 = external/local mode, #959 = shared/discovered mode on top. They're complementary, not competing. #959 should be reviewed as an extension that builds on #797's
esolveExternalStateDir()\ foundation.
Key dedup point: the resolution chain in #959 should check #797's external state as one of its discovery steps (which it appears to do — local .squad/ → external state → shared registry).
bradygaster commentedon Apr 12, 2026
Seems like a nice extension to what we already have, eh, @tamirdresher?
bradygaster commentedon Apr 25, 2026
Closed by #theSquadsquad triage — verified fixed/superseded in v0.9.4.