setup-gbrain on Windows: 6 papercut failures requiring manual workarounds at almost every step
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Environment
- OS: Windows 11 Pro (10.0.26200)
- Shell: Git Bash via Claude Code's Bash tool (and PowerShell available)
- gstack: v1.43.3.0 (auto-upgraded mid-skill from v1.40.0.0)
- gbrain target: v0.18.2 (pinned by installer)
- Engine path: Supabase auto-provision
Ran `/setup-gbrain` end-to-end. Skill completed and produced a working brain, but only after working around 6 distinct issues. Listing them in encounter order so anyone reproducing on Windows can see the chain.
---
### 1. `./setup` build fails on Windows
On `cd ~/.claude/skills/gstack && ./setup`:
```
error: Failed to run script build due to error
Subshells with redirections are currently not supported. Please open a GitHub issue.
```
The package.json `build` script uses subshells with stdout redirection (`( … ) > file`), which Bun's shell on Windows refuses. Result: git pull succeeded but the pre-built binaries (browse, design, make-pdf, gstack-global-discover) didn't rebuild. Core scripts still worked, but the user has no idea their build is stale.
**Suggested fix:** rewrite the build script to avoid `( … ) > file` patterns, or detect Windows and fall back to a plain sequential build.
---
### 2. `gstack-gbrain-install` exits 3 on Windows but install actually succeeded
```
gstack-gbrain-install: cannot read version from /c/Users/2supe/gbrain/package.json (install may be broken)
```
Right after that, `gbrain --version` printed `0.18.2` and worked perfectly. The installer's version check uses a path format that fails on Windows, but the bun install + link both succeeded. False-failure UX caused the skill to halt.
**Suggested fix:** version-check fallback that tries multiple path formats, or only fail-loud if a subsequent `gbrain --version` invocation fails.
---
### 3. `jq` is an undocumented hard prereq, suggested fix is macOS-only
`gstack-gbrain-supabase-provision` requires `jq` but it's not in any documented prereq list, not bundled, and not auto-installed. On failure it prints:
```
gstack-gbrain-supabase-provision: jq is required. Install with: brew install jq
```
On Windows there's no brew. Had to manually download the jq Windows binary from GitHub releases.
**Suggested fix:** either (a) bundle jq detection in `./setup` and install via the right pkg manager per OS, or (b) rewrite the Supabase provision script's jq calls in pure bash / Python (already a dependency since the install scripts use it elsewhere).
---
### 4. `gstack-artifacts-init` hardcodes SSH for git push, no HTTPS fallback
The script verifies remote connectivity via SSH (`git@github.com:…`) and refuses to continue if SSH auth isn't set up:
```
Verifying remote connectivity: git@github.com:ElliotDrel/gstack-artifacts-elliotdrel.git
Remote not reachable via SSH: git@github.com:ElliotDrel/gstack-artifacts-elliotdrel.git
```
The user uses GitHub CLI's HTTPS auth via Git Credential Manager (which is the gh default on Windows). No SSH key. Worked around by adding global `git config url.https://github.com/.insteadOf git@github.com:` redirects.
**Suggested fix:** detect the user's git auth protocol (gh has `gh auth status` for this) and pick HTTPS vs SSH accordingly. Or honor `gh auth setup-git` if it's already run.
---
### 5. Setup-gbrain skill references a renamed binary (`gstack-brain-init`)
Skill says "Run `gstack-brain-init`" but that was renamed to `gstack-artifacts-init` in v1.27.0.0. The migration shim was hard-deleted, so calling the old name just errors:
```
/c/Users/2supe/.claude/skills/gstack/bin/gstack-brain-init: No such file or directory
```
Found the new name by grepping `bin/`. The skill file under `setup-gbrain/SKILL.md` should be updated to reference `gstack-artifacts-init` everywhere.
---
### 6. Smoke test step uses `< file.md` which fails on Windows
The skill's Step 9 smoke test runs:
```bash
echo "..." | gbrain put "$SLUG"
```
On Windows this errors:
```
ENOENT: no such file or directory, open '/dev/stdin'
```
The gbrain CLI tries to read from `/dev/stdin` which doesn't exist on Windows. `gbrain put --content "…"` works fine.
This is partly a gbrain bug but the gstack skill should at minimum (a) detect Windows and use `--content`, or (b) document the workaround.
---
### Other minor observations
- The installer pins gbrain to v0.18.2 but latest is v0.40.8.0 (released today). The pin is ~22 versions behind. Major features missing (ZeroEntropy default embedder + reranker came in v0.36.2.0). Worth either bumping the pin or making it configurable via `gstack-config set gbrain_pin `.
- `gstack-config` has no `unset` subcommand even though skill workflows reference it conceptually. Have to `set ` instead, which requires knowing the default.
---
### Net effect
Skill completed and a working brain was produced. But a Windows user without an agent stepping through workarounds in real-time would have bounced at issue #1 or #3. Of the six, #4 (SSH-only) and #3 (jq) are the highest-leverage to fix — they block the happy path completely. #2 (false-failure exit code) is the most misleading.
Happy to PR fixes for any subset if useful — let me know which you'd want first.
Contributor guide
Assessment
This issue has not been assessed yet.