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
Commit e8e07ff
Browse filesBrowse the repository at this point in the historyBrowse files
`squad init` now tells you to run the host you chose (#2453). `squad init --client claude` ends with `claude --agent squad --mcp-config .mcp.json` and a matching `claude -p` tip, instead of telling Claude Code users to run Copilot. With several hosts, it gives one line per host.
Committed files no longer contain paths from your machine (#2462). When the Squad CLI is installed, `squad init` and `squad upgrade` used to write `node /your/path/cli-entry.js state-mcp` into `.mcp.json`, the other hosts' MCP configs and every Claude Code hook in `.claude/settings.json`, so they failed on any other clone. They now write `node .squad/squad.mjs state-mcp`, a launcher Squad commits that finds a Squad CLI on each machine (`SQUAD_CLI`, the project's `node_modules`, then `squad` on PATH; `npx` only with `SQUAD_ALLOW_NPX=1`). Claude hooks reach it through `$CLAUDE_PROJECT_DIR`, and standalone bundle installs write `squad state-mcp`. Run `squad upgrade` once to fix an existing repository. `squad doctor` has a new check that flags machine-specific launch commands and a missing launcher.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+9-1Lines changed: 9 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -64,7 +64,15 @@ Claude Code is the first host after GitHub Copilot where Squad uses the host's o
64
64
65
65
- The Claude coordinator names Claude Code's `Agent` subagent tool (formerly `Task`). The Claude Code spec, docs and host feature matrix now match the code, and host-projection regression guards keep them that way (#2440, #2445).
66
66
- Every generated Claude Markdown file states its projection version. Files from earlier projections are still recognised as Squad's and upgraded in place, and rolling back the `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` blocks restores the original bytes exactly (#2450).
67
-
- Copilot output, `.github/agents/squad.agent.md` and the projections for other hosts are unchanged.
67
+
- Copilot output, `.github/agents/squad.agent.md` and the projections for other hosts are unchanged, apart from the portable `squad_state` launch command below, which every host gets.
68
+
69
+
#### Fixed
70
+
71
+
-**Committed files no longer contain paths from your machine** (#2462). With the Squad CLI installed, `squad init` and `squad upgrade` used to write `node /your/path/cli-entry.js state-mcp` into `.mcp.json`, the other hosts' MCP configs and every Claude Code hook, so a clone on any other machine failed. They now write `node .squad/squad.mjs state-mcp`.
72
+
-`.squad/squad.mjs` is a launcher Squad commits. It finds a Squad CLI on each machine: `SQUAD_CLI`, the project's `node_modules`, then `squad` on PATH. It skips a CLI older than the one that wrote it, and uses `npx` only with `SQUAD_ALLOW_NPX=1`. It shares its code with the plugin's launcher.
73
+
- Claude hooks reach the launcher through `$CLAUDE_PROJECT_DIR`. Standalone bundle installs write `squad state-mcp`. A CLI run through `npx` keeps the exact-version `npx` command.
74
+
-`squad doctor` flags machine-specific launch commands and a missing launcher. Run `squad upgrade` once to fix an existing repository.
75
+
-`squad init --client claude` tells you to run `claude --agent squad --mcp-config .mcp.json`, not Copilot. With several hosts it gives one line per host (#2453).
Copy file name to clipboardExpand all lines: docs/src/content/docs/features/mcp.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,6 +31,8 @@ Where you add a server depends on your host:
31
31
32
32
Copilot CLI doesn't read a `.copilot/mcp-config.json` inside the project (`squad init` writes a sample one there), so a server added to it never loads. Hosts added with `squad init --client` have their own MCP config (Claude Code shares `.mcp.json`), and Squad adds `squad_state` to it for you.
33
33
34
+
The `squad_state` entry Squad writes works on every clone of the repository. If you installed the Squad CLI (globally, in the project, or from a source build), the entry runs `node .squad/squad.mjs state-mcp`. That small launcher, which Squad writes and you commit, finds a Squad CLI on whichever machine runs it: `SQUAD_CLI` if set, then the project's `node_modules`, then `squad` on PATH. It skips a CLI older than the one that wrote it. If none is found, it prints how to install one; set `SQUAD_ALLOW_NPX=1` to let it run the exact version with `npx` instead. Claude Code hooks use the same launcher. A standalone bundle install writes `squad state-mcp`, and a CLI run through `npx` writes the exact-version `npx` command. `squad doctor` warns when a committed entry points at a path on one machine.
35
+
34
36
This guide covers Copilot CLI and VS Code. Pick the one that matches your workflow.
Copy file name to clipboardExpand all lines: docs/src/content/docs/scenarios/troubleshooting.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -154,6 +154,16 @@ declarations, which multiplied the process count.
154
154
155
155
---
156
156
157
+
## `squad_state` or Claude hooks fail after cloning
158
+
159
+
**Problem:** On a fresh clone or another machine, the `squad_state` MCP server doesn't start, or every Claude Code hook reports an error. `squad doctor` shows **portable squad_state launch** failing.
160
+
161
+
**Cause:** The repository was set up with a Squad version that wrote absolute paths from one machine into `.mcp.json` and `.claude/settings.json`.
162
+
163
+
**Fix:** run `squad upgrade` once and commit the result. It replaces those paths with `node .squad/squad.mjs`, a launcher that finds the Squad CLI on each machine. If the launcher says no Squad CLI was found, install one (`npm install -g @bradygaster/squad-cli`) or set `SQUAD_ALLOW_NPX=1`.
164
+
165
+
---
166
+
157
167
## Upgrade doesn't change anything
158
168
159
169
**Problem:** Running `squad upgrade` completes but nothing changes.
Copy file name to clipboardExpand all lines: docs/src/content/docs/scenarios/upgrading.md
+8-7Lines changed: 8 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -183,12 +183,12 @@ Every row below is a pinned, published artifact of an older Squad release driven
183
183
184
184
### Runs
185
185
186
-
All recorded runs executed against **one tree**, commit `9da01a2e41ba15794d31b0b8251ddaa3abd34ba8`, with harness hash `bca27c39dc2dcbff…` (sha256 over the suite, renderer, workflow, fs hook and this fixture minus `runs`; the integrity test refuses a recorded run whose harness differs from the committed one, so folding results may change nothing but the runs data).
186
+
All recorded runs executed against **one tree**, commit `9b254ba858abc19ef62e513993d9802312bfe34c`, with harness hash `a9713d320fdb479c…` (sha256 over the suite, renderer, workflow, fs hook and this fixture minus `runs`; the integrity test refuses a recorded run whose harness differs from the committed one, so folding results may change nothing but the runs data).
187
187
188
188
| Platform | Arch | Node | Target | Tree (targetSha) | Trigger | Recorded | Outcome |
| Linux (`linux`) | x64 | v22.23.3|v1.2.0-preview.1|`9da01a2e41ba`|[workflow_dispatch](https://github.com/bradygaster/squad/actions/runs/39903943542)| 2026-10-23| 35 rows passed all non-xfail assertions; 4 of them carry a known expected failure (F3: Squad 0.9.1 squad upgrade --dry-run is not dry); 0 rows failed; 7 rows are structurally inapplicable (listed below). |
191
-
| Windows (`win32`) | x64 | v22.23.4 |v1.2.0-preview.1|`9da01a2e41ba`|[workflow_dispatch](https://github.com/bradygaster/squad/actions/runs/39903943542)| 2026-10-23| 35 rows passed all non-xfail assertions; 4 of them carry a known expected failure (F3: Squad 0.9.1 squad upgrade --dry-run is not dry); 0 rows failed; 7 rows are structurally inapplicable (listed below). |
190
+
| Linux (`linux`) | x64 | v22.23.4|v2.0.0-preview.4|`9b254ba858ab`|[pull_request](https://github.com/github/squad/actions/runs/43147851248)| 2026-11-12| 35 rows passed all non-xfail assertions; 4 of them carry a known expected failure (F3: Squad 0.9.1 squad upgrade --dry-run is not dry); 0 rows failed; 7 rows are structurally inapplicable (listed below). |
191
+
| Windows (`win32`) | x64 | v22.23.4 |v2.0.0-preview.4|`9b254ba858ab`|[pull_request](https://github.com/github/squad/actions/runs/43147851248)| 2026-11-12| 35 rows passed all non-xfail assertions; 4 of them carry a known expected failure (F3: Squad 0.9.1 squad upgrade --dry-run is not dry); 0 rows failed; 7 rows are structurally inapplicable (listed below). |
192
192
193
193
### Producers (pinned, immutable provenance)
194
194
@@ -197,8 +197,8 @@ All recorded runs executed against **one tree**, commit `9da01a2e41ba15794d31b0b
197
197
|**0.9.1**| npm |`@bradygaster/squad-cli@0.9.1`<br>sha1 `a5ee3dbfc44b7457eba56476f708ad6fdc2e09ca`<br>`sha512-TcZqRbJk3XBg4N8Y5/5OWJeA52ARAMuzk4MGtB0bfdr87e7iJRV6lJEw8+OIYz9IQ+1JxN/Q30dZDALMOcdi2w==`<br>`@bradygaster/squad-sdk@0.9.1`<br>sha1 `4735aba9f125de415160cd979ea3f1467903f16e`<br>`sha512-1KqZ2N6Lt/B4uYlU/Su9JjA1s/7ng0OAEb9CZrkRk19YSPi6tg7K5QWdTKl5gY/gp8zPAJqfjVffOwrZwGlzmw==`| Oldest 0.x line that still installs on Node 22 (engines >=22.5); pinned with its own @bradygaster/squad-sdk@0.9.1 (its `>=0.9.0` range would otherwise float to 1.0.1). Scaffolds `.squad/` with an EMPTY `casting/` directory and skills under `.copilot/skills/`; predates --state-backend. | no |
198
198
|**0.13.1**| npm |`@bradygaster/squad-cli@0.13.1`<br>sha1 `c8f6427bab4cae989934574315eabda98495fb37`<br>`sha512-ogfx2nhyx6fqMyqlaI5tDnOzUbRdh+a6Uh/rMQ0aNJwAXnvQp4N37Xp/eOTyB5CxcB7E34NBtAfCxyXbWSiS8w==`<br>`@bradygaster/squad-sdk@0.13.1`<br>sha1 `90e98450971e921ca2072673b325fcc8126a2fb6`<br>`sha512-1Jt6c9kahJq1JCcE77j/50D79YcXVG6Rt1genuLJ3O9J2SKTZKemlbvHgftkc5LgGH22DkWqHh5zLNEQ/p+ukA==`| Last 0.x stable; first line with --state-backend (local\|orphan\|two-layer) and user-profile squads (writes teamRoot when a profile squad exists). | yes |
199
199
|**1.0.0**| npm |`@bradygaster/squad-cli@1.0.0`<br>sha1 `e4e776ef938cbe8c65d8d2c729f2249a48bca638`<br>`sha512-mnZXnA+GAtp4KSLf7a4Zw0BpeOaHFAxYV5oxAy58ancZ9C2LguUGbcTxWIG0djM96XWET8K9fcncif3Vm6Z9RQ==`<br>`@bradygaster/squad-sdk@1.0.0`<br>sha1 `4abb8e450e79827b865a7846af6589789d079cab`<br>`sha512-9f4NthJaQDq6ifXU3f6VfsZz2bbWs2u57fHhXKtDgDMSvZ3Xq8FPjMvddxhRvseWqaSlkYcWsag3M/lzTtKaJA==`| First 1.x stable; last version published to npm (dist-tag latest). | yes |
200
-
|**1.0.1**| GitHub Release |[bradygaster/squad v1.0.1](https://github.com/bradygaster/squad/releases/tag/v1.0.1) — assets by immutable id:<br>`squad-darwin-arm64.tar.gz` id `610330560` sha256 `47a8d44d0a9a338ae2c2b6192cb761187ebd71edbd1171a4800cee11cb001b43`<br>`squad-darwin-x64.tar.gz` id `610330564` sha256 `b88db7e8949878ba2cdf756758651cd50a0e9b5fc83f4c759bd7438d596b4951`<br>`squad-linux-arm64.tar.gz` id `610330558` sha256 `9d8105c903eeac4d1762e43432f54827a6c4676f4aa42cfdf34bf645e497e756`<br>`squad-linux-x64.tar.gz` id `610330551` sha256 `283a1893be9ddad11056dcc8bd0673eff6b48a789bbf523b3f7ec31994d27ac7`<br>`squad-win32-arm64.zip` id `610330674` sha256 `586c4e2d3d708f4d3f08b2c8ffb965d9312d6586d0830a1b8a817b27c3c14bd0`<br>`squad-win32-x64.zip` id `610330559` sha256 `f38a8f85e60982dba340187b761488f01de1aec68ea50c1b85725783d32df2fe`| Patch release whose CLI never reached npm (release run 37222633918: SDK publish failed, CLI publish skipped); only the standalone bundles exist. | yes |
201
-
| **1.1.0** | GitHub Release | [bradygaster/squad v1.1.0](https://github.com/bradygaster/squad/releases/tag/v1.1.0) — assets by immutable id:<br>`squad-darwin-arm64.tar.gz` id `659607638` sha256 `057c8d2296e1c95cd77933bae55475409a2dce88aa5b3443cc6ca6cfcd545631`<br>`squad-darwin-x64.tar.gz` id `659607644` sha256 `4e4e8574f6a339f5537c82eb586d66ecf2ee3005e86b058b834b965be33a43cd`<br>`squad-linux-arm64.tar.gz` id `659607639` sha256 `992e9dbfe677e3c772446960051329aaed1578d5e4dbcb3350827dbb755e8b00`<br>`squad-linux-x64.tar.gz` id `659607641` sha256 `2de647a3feaef334051eb1b3084acba37a511818aad029a16abfe32fadb41aff`<br>`squad-win32-arm64.zip` id `659607808` sha256 `3c922c37863b255546403cffb2aa1c7dff2a347be87ca582759c149aec7bb1da`<br>`squad-win32-x64.zip` id `659607643` sha256 `571d734f7ae718fefefdfa9864f9f82a3d1fb1546f01ec8bf8866fa7e1829c57` | Latest 1.x release; npm CLI publish failed in release run 39442663504 ("Could not verify @bradygaster/squad-cli@1.1.0 on npm dist-tag 'latest' after 20 attempts"), so the standalone bundle is the only published artifact. | yes |
200
+
|**1.0.1**| GitHub Release |[github/squad v1.0.1](https://github.com/github/squad/releases/tag/v1.0.1) — assets by immutable id:<br>`squad-darwin-arm64.tar.gz` id `610330560` sha256 `47a8d44d0a9a338ae2c2b6192cb761187ebd71edbd1171a4800cee11cb001b43`<br>`squad-darwin-x64.tar.gz` id `610330564` sha256 `b88db7e8949878ba2cdf756758651cd50a0e9b5fc83f4c759bd7438d596b4951`<br>`squad-linux-arm64.tar.gz` id `610330558` sha256 `9d8105c903eeac4d1762e43432f54827a6c4676f4aa42cfdf34bf645e497e756`<br>`squad-linux-x64.tar.gz` id `610330551` sha256 `283a1893be9ddad11056dcc8bd0673eff6b48a789bbf523b3f7ec31994d27ac7`<br>`squad-win32-arm64.zip` id `610330674` sha256 `586c4e2d3d708f4d3f08b2c8ffb965d9312d6586d0830a1b8a817b27c3c14bd0`<br>`squad-win32-x64.zip` id `610330559` sha256 `f38a8f85e60982dba340187b761488f01de1aec68ea50c1b85725783d32df2fe`| Patch release whose CLI never reached npm (release run 37222633918: SDK publish failed, CLI publish skipped); only the standalone bundles exist. | yes |
201
+
| **1.1.0** | GitHub Release | [github/squad v1.1.0](https://github.com/github/squad/releases/tag/v1.1.0) — assets by immutable id:<br>`squad-darwin-arm64.tar.gz` id `659607638` sha256 `057c8d2296e1c95cd77933bae55475409a2dce88aa5b3443cc6ca6cfcd545631`<br>`squad-darwin-x64.tar.gz` id `659607644` sha256 `4e4e8574f6a339f5537c82eb586d66ecf2ee3005e86b058b834b965be33a43cd`<br>`squad-linux-arm64.tar.gz` id `659607639` sha256 `992e9dbfe677e3c772446960051329aaed1578d5e4dbcb3350827dbb755e8b00`<br>`squad-linux-x64.tar.gz` id `659607641` sha256 `2de647a3feaef334051eb1b3084acba37a511818aad029a16abfe32fadb41aff`<br>`squad-win32-arm64.zip` id `659607808` sha256 `3c922c37863b255546403cffb2aa1c7dff2a347be87ca582759c149aec7bb1da`<br>`squad-win32-x64.zip` id `659607643` sha256 `571d734f7ae718fefefdfa9864f9f82a3d1fb1546f01ec8bf8866fa7e1829c57` | Latest 1.x release; npm CLI publish failed in release run 39442663504 ("Could not verify @bradygaster/squad-cli@1.1.0 on npm dist-tag 'latest' after 20 attempts"), so the standalone bundle is the only published artifact. | yes |
202
202
|**HEAD**| local HEAD (pack) | npm pack of packages/squad-sdk and packages/squad-cli from the tree under test (targetSha) | Same-version idempotency: the CLI packed from this tree scaffolds and then upgrades itself. | yes |
203
203
204
204
npm tarballs are fetched by exact version through the registry npm is configured for and verified against the recorded sha1 + sha512 before use; GitHub Release bundles are downloaded by immutable asset id and verified against the recorded sha256. A verification mismatch **fails** the producer's rows (it is never a skip); only an unreachable registry/release yields a skip, and that skip carries the reason.
@@ -314,6 +314,7 @@ Paths a plain `squad upgrade` may create or rewrite (the only changes `user-stat
@@ -394,12 +395,12 @@ Recorded by the `downgrade-probe` check (dry-run on a copy; the only assertion i
394
395
395
396
| Platform | Producer | Shapes | Observed |
396
397
|----------|----------|--------|----------|
397
-
|`linux`| 0.9.1 | all 4 shapes | exit 0, last lines "[32m✓[0m refreshed .squad/templates/ \| Upgrade complete: v1.2.0-preview.1 → v0.9.1 \|[2mPreserves user state: team.md, decisions/, agents/*/history.md[0m"; MODIFIED 45 files (20 coordinator/templates/workflows, e.g. .copilot/skills/agent-collaboration/SKILL.md, .copilot/skills/cross-squad/SKILL.md, .copilot/skills/git-workflow/SKILL.md …) |
398
+
|`linux`| 0.9.1 | all 4 shapes | exit 0, last lines "[32m✓[0m refreshed .squad/templates/ \| Upgrade complete: v2.0.0-preview.4 → v0.9.1 \|[2mPreserves user state: team.md, decisions/, agents/*/history.md[0m"; MODIFIED 68 files (20 coordinator/templates/workflows, e.g. .copilot/skills/agent-collaboration/SKILL.md, .copilot/skills/agent-conduct/SKILL.md, .copilot/skills/architectural-proposals/SKILL.md …) |
398
399
|`linux`| 0.13.1 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
399
400
|`linux`| 1.0.0 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
400
401
|`linux`| 1.0.1 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
401
402
|`linux`| 1.1.0 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
402
-
|`win32`| 0.9.1 | all 4 shapes | exit 0, last lines "[32m✓[0m refreshed .squad/templates/ \| Upgrade complete: v1.2.0-preview.1 → v0.9.1 \|[2mPreserves user state: team.md, decisions/, agents/*/history.md[0m"; MODIFIED 44 files (20 coordinator/templates/workflows, e.g. .copilot/skills/agent-collaboration/SKILL.md, .copilot/skills/cross-squad/SKILL.md, .copilot/skills/git-workflow/SKILL.md …) |
403
+
|`win32`| 0.9.1 | all 4 shapes | exit 0, last lines "[32m✓[0m refreshed .squad/templates/ \| Upgrade complete: v2.0.0-preview.4 → v0.9.1 \|[2mPreserves user state: team.md, decisions/, agents/*/history.md[0m"; MODIFIED 67 files (20 coordinator/templates/workflows, e.g. .copilot/skills/agent-collaboration/SKILL.md, .copilot/skills/agent-conduct/SKILL.md, .copilot/skills/architectural-proposals/SKILL.md …) |
403
404
|`win32`| 0.13.1 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
404
405
|`win32`| 1.0.0 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
405
406
|`win32`| 1.0.1 | all 6 shapes | exit 0, last lines "overwrite ../.github/workflows/squad-triage.yml \| overwrite ../.github/workflows/sync-squad-labels.yml \| Run without --dry-run to apply."; modified nothing |
0 commit comments