Skip to content

feat: shared squad — external state backend for multi-clone workflows #958

Closed

Description

@akubly

Problem

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
  • squad shared status|diagnose|list|doctor — operational tooling
  • squad migrate --to shared — move existing squad state externally

Related

Partially addresses #943 (monorepo/persistence concerns)

Activity

  1. tamirdresher commented on Apr 11, 2026

    @tamirdresher
    Collaborator

    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?

  2. tamirdresher commented on Apr 12, 2026

    @tamirdresher
    Collaborator

    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).

  3. bradygaster commented on Apr 12, 2026

    @bradygaster
    Collaborator

    Seems like a nice extension to what we already have, eh, @tamirdresher?

  4. bradygaster commented on Apr 25, 2026

    @bradygaster
    Collaborator

    Closed by #theSquadsquad triage — verified fixed/superseded in v0.9.4.

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

Metadata

Metadata

Assignees

No one assigned

    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