Repository navigation
feat(clients): add --client host adapters for Claude, Kiro, OpenCode, Cursor, Codex, and Antigravity [1/4] - #2251
Merged
tamirdresher merged 3 commits intoOct 22, 2026
Conversation
Contributor
🟠 Impact Analysis — PR #2251Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedroot (2 files)
squad-cli (5 files)
squad-sdk (12 files)
tests (2 files)
|
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 3 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 2 active Copilot thread(s) resolved (4 outdated skipped) |
| ✅ | CI passing | All checks passing |
Files Changed (21 files, +3728 −2)
| File | +/− |
|---|---|
.changeset/squad-2-0-multi-host-clients.md |
+8 −0 |
cspell.json |
+3 −0 |
packages/squad-cli/src/cli-entry.ts |
+22 −2 |
packages/squad-cli/src/cli/core/clients.ts |
+176 −0 |
packages/squad-cli/src/cli/core/command-help.ts |
+2 −0 |
packages/squad-cli/src/cli/core/init.ts |
+12 −0 |
packages/squad-cli/src/cli/core/upgrade.ts |
+30 −0 |
packages/squad-sdk/package.json |
+4 −0 |
packages/squad-sdk/src/client/adapter-contract.ts |
+207 −0 |
packages/squad-sdk/src/client/adapters/adapters.ts |
+375 −0 |
packages/squad-sdk/src/client/adapters/apply.ts |
+866 −0 |
packages/squad-sdk/src/client/adapters/capabilities.ts |
+140 −0 |
packages/squad-sdk/src/client/adapters/coordinator.ts |
+201 −0 |
packages/squad-sdk/src/client/adapters/index.ts |
+6 −0 |
packages/squad-sdk/src/client/adapters/portable.ts |
+72 −0 |
packages/squad-sdk/src/client/adapters/types.ts |
+87 −0 |
packages/squad-sdk/src/client/index.ts |
+5 −0 |
packages/squad-sdk/src/clients/index.ts |
+9 −0 |
packages/squad-sdk/src/index.ts |
+5 −0 |
test/clients-real-cli.test.ts |
+217 −0 |
test/clients.test.ts |
+1281 −0 |
Total: +3728 −2
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Configuration preservation, credential redaction, Codex activation, and the stated opt-in contract have unresolved issues.
6 open issues
What changed in this PR
Adds the first layer of multi-host support, exposing SDK adapters and CLI options for seven clients while sharing Squad’s coordinator protocol and state configuration.
Changes:
- Adds host projections, capability declarations, and runtime delegation interfaces.
- Wires
--clientparsing, persistence, and projection refresh into init and upgrade. - Adds configuration-preservation tests and optional real-CLI checks.
| File | Description |
|---|---|
| test/clients.test.ts | Tests adapters, configuration merging, and safeguards. |
| test/clients-real-cli.test.ts | Adds optional host CLI checks. |
| packages/squad-sdk/src/index.ts | Exports adapter APIs. |
| packages/squad-sdk/src/clients/index.ts | Adds deprecated compatibility exports. |
| packages/squad-sdk/src/client/index.ts | Exposes host adapters. |
| packages/squad-sdk/src/client/adapters/types.ts | Defines host projection types. |
| packages/squad-sdk/src/client/adapters/portable.ts | Normalizes persisted client IDs. |
| packages/squad-sdk/src/client/adapters/index.ts | Consolidates adapter exports. |
| packages/squad-sdk/src/client/adapters/coordinator.ts | Defines shared protocol and host dispatch instructions. |
| packages/squad-sdk/src/client/adapters/capabilities.ts | Declares and intersects capabilities. |
| packages/squad-sdk/src/client/adapters/apply.ts | Applies and removes managed configuration. |
| packages/squad-sdk/src/client/adapters/adapters.ts | Implements seven host projections. |
| packages/squad-sdk/src/client/adapter-contract.ts | Adds runtime delegation facade. |
| packages/squad-sdk/package.json | Exports the compatibility subpath. |
| packages/squad-cli/src/cli/core/upgrade.ts | Refreshes configured client projections. |
| packages/squad-cli/src/cli/core/init.ts | Installs requested client projections. |
| packages/squad-cli/src/cli/core/command-help.ts | Documents client options. |
| packages/squad-cli/src/cli/core/clients.ts | Handles flags, persistence, and synchronization. |
| packages/squad-cli/src/cli-entry.ts | Passes client selections to commands. |
| cspell.json | Adds vocabulary. |
| .changeset/squad-2-0-multi-host-clients.md | Records SDK and CLI release changes. |
Review effort: Balanced
…ions (Layer 1) Carves Layer 1 of #2239 targeting dev and applies all Layer 1 review fixes: - Isolate host coordinator projections so non-Squad sessions are not hijacked: - Codex writes full coordinator prompt to .codex/agents/squad.md and only a short discovery pointer block in AGENTS.md - Kiro sets .kiro/steering/squad.md to inclusion: manual (loaded by .kiro/agents/squad.json) - Cursor sets .cursor/rules/squad.mdc to alwaysApply: false - Make multi-client projection strictly opt-in (no default .claude/worktrees/ or NUL in .gitignore on plain init/upgrade) - Synchronize coordinator.ts with .github/agents/squad.agent.md as the canonical coordinator source of truth - Throw on unclosed or inverted Squad managed block markers in upsertBlock/removeBlock - Normalize inline and dotted squad_state TOML definitions in upsertTomlTable/removeTomlTable without duplicates - Import from @bradygaster/squad-sdk/client, merge repeated --client flags, preserve unknown portable client IDs in config.json with a warning, and reject symlinked .squad directories Refs #2239 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7a8a1fc8-bd63-4811-920c-7be89c631d5e
…link root handling, EOL/indent-preserving merges) - H1: Codex coordinator is now a TOML custom agent (.codex/agents/squad.toml with name/description/developer_instructions, escaped multi-line string); AGENTS.md pointer, ANCHORS, dispatch text and uninstall updated - H2: resolveInsideRoot realpaths the root once and only lstats components below it, so junctioned/symlinked ancestors (OneDrive, ~/code -> /Volumes) work; syncClients returns early with no requested/configured clients before any filesystem checks - M2: symlinked target files inside the root (AGENTS.md -> CLAUDE.md) are written through; symlinks escaping the root are still refused - M1: new 'lines' projection kind for .gitignore (plain lines under a `# squad:<id>` comment, no HTML markers); uninstall removes only the lines Squad added - M3: emitted content follows the existing file's dominant EOL (LF for new files) for blocks, lines, JSON, TOML and removals - M4: JSON merges preserve indentation (tabs/N spaces) and trailing-newline; OpenCode targets opencode.jsonc when it is the only config and reports an error instead of clobbering JSONC with comments - M5: only persist newly requested clients whose projection had no errors (configured ones stay); atomic temp+rename writes; `squad upgrade --dry-run --client` prints the clients it would project (syncClients dryRun option) - M6: real-CLI tests gated behind SQUAD_REAL_CLI_TESTS=1, PATH-only binary discovery, no hardcoded paths, shell:false, cursor-agent check is read-only - changeset wording updated; tests added/updated in test/clients.test.ts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841
- apply.ts (Thread 1): preserve parsed TOML key segments across sectionHeader,
tableHeaderKeys, findTable, stripConflictingDottedAndInline, and removeTomlTable
so quoted-dot server names ([mcp_servers."squad_state.env"]) remain untouched
- apply.ts (Thread 2): track multiline basic (""") and literal (''') string
boundaries in assignmentEnd and advance scanners across multiline assignments
so embedded TOML examples in developer_instructions are never rewritten
- apply.ts (Thread 3): refuse to extend enclosing ancestor inline/scalar tables
(e.g. mcp_servers = { other = ... }) or non-table squad_state assignments
- portable.ts (Thread 4): trim before sensitivity checks and redact bare
credential prefixes (ghp_, github_pat_, sk-, glpat-, xox*, AKIA, JWT) so
they never surface in unknown-ID warnings or persist in config.json
- adapters.ts & clients-real-cli.test.ts (Thread 5): project native Codex
.codex/agents/squad.toml role and verify real-CLI role discovery + coordinator
developer_instructions activation on spawn_agent
- clients.ts & clients.test.ts (Thread 6): document the default Copilot
bootstrap exception (.github/agents/squad.agent.md + .mcp.json) and test
both plain runInit and runUpgrade command pipelines directly
Refs #2251
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a8a1fc8-bd63-4811-920c-7be89c631d5e
tamirdresher
force-pushed
the
tamirdresher-microsoft-stack-1-client-adapters
branch
from
October 20, 2026 21:21
3bbb75d to
5052371
Compare
16 of 19 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary (Stack Layer 1 of 4 — splits #2239)
Adds opt-in
--client <list|all>host projections (@bradygaster/squad-sdk/client) for GitHub Copilot, Claude Code, Kiro, OpenCode, Cursor, OpenAI Codex CLI, and Google Antigravity.Review fixes included in Layer 1
.codex/agents/squad.mdand only a short discovery pointer block toAGENTS.md..kiro/steering/squad.mdusesinclusion: manual(loaded by.kiro/agents/squad.jsonviaprompt)..cursor/rules/squad.mdcusesalwaysApply: falsealongside.cursor/agents/squad.md.squad init/squad upgrade:squad initandsquad upgradewithout--client(and with noclients[]in.squad/config.json) leave.gitignore,.mcp.json, and host files untouched.coordinator.tsderives its canonical version and protocol headings from.github/agents/squad.agent.md(CANONICAL_COORDINATOR_AGENT_PATH), enforced by heading-sync tests.upsertBlock/removeBlockrefuse unclosed<!-- squad:begin -->markers rather than deleting trailing user content.upsertTomlTable/removeTomlTablenormalize inline and dotted-keysquad_statedefinitions in.codex/config.tomlwithout creating duplicate tables.@bradygaster/squad-sdk/client, merges repeated--clientflags, preserves unknown portableclients[]IDs in.squad/config.json, andlstat-guards.squaditself against symlink traversal.