garrytan / garrytan/gstack

Windows MSYS install: 3 quirks in /setup-gbrain skill (gbrain v0.18.2)

Open
#1,271 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
133k
Forks
19.9k
Avg merge
18h 46m
Merged PRs (30d)
26

Description

## Summary

Ran `/setup-gbrain` on Windows 11 / MSYS (MINGW64) bash with gbrain v0.18.2. PGLite-local path completed successfully but hit three quirks the SKILL.md docs don't cover. Filing so the next Windows user doesn't have to re-debug.

## Environment

- OS: Windows 11 (10.0.26200), MINGW64_NT-10.0-26200
- Shell: bash via MSYS / Git for Windows
- bun: 1.1.2
- gstack: v1.17.0.0
- gbrain: 0.18.2 (pinned commit `08b3698e`)
- claude-code: present on PATH

## Quirk 1 — `bun install` postinstall script fails non-fatally

The installer (`gstack-gbrain-install`) aborts with exit 1 at:

```
bun install v1.1.2 (c8d072c2)
$ command -v gbrain >/dev/null 2>&1 && gbrain apply-migrations --yes --non-interactive || echo '[gbrain] postinstall skipped...' 1>&2
error: Failed to run script C:\Users\xhiri\gbrain\[eval] due to error expected a command or assignment but got: "Redirect"
error: postinstall script from "gbrain" exited with 1
```

Cause: bun-on-Windows's `[eval]` subprocess can't parse `>/dev/null 2>&1` in package.json's postinstall. Deps actually install fine; the failing command is graceful-degradation code that probes for a not-yet-linked `gbrain` binary. The `||` fallback path is what fires on Mac/Linux when `gbrain` isn't on PATH yet. On Windows bun, parsing dies before the `||` ever evaluates.

**Workaround that works:** ignore the installer's exit, then manually:

```bash
( cd ~/gbrain && bun link --silent )
gbrain --version # should print 0.18.2
```

**Suggested upstream fix:** rewrite the postinstall in package.json to a `.js` script (`node -e '...'` or a small `scripts/postinstall.js`) so it doesn't depend on shell-redirect parsing. Or detect the failure mode in `gstack-gbrain-install` and continue past it.

## Quirk 2 — `claude mcp list` reports `✗ Failed to connect` while in-session MCP works

After successful `claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve`, running `claude mcp list` shows:

```
gbrain: C:/Users/xhiri/.bun/bin/gbrain serve - ✗ Failed to connect
```

But `mcp__gbrain__get_stats` and other MCP tools called from the same Claude Code session work perfectly.

Cause: PGLite is single-writer. Claude Code's session has its own `gbrain serve` running and connected. `claude mcp list` spawns an independent test connection that can't acquire the lock — looks like "Failed to connect" but really means "another writer holds the lock."

**Suggested fix:** either soften the diagnostic (`Connected (lock held by peer)` for PGLite when another instance has the lock and is responsive), or note this in the SKILL.md's "Important Rules" section so users don't think the registration failed.

## Quirk 3 — `gbrain put` v0.18.2 doesn't accept stdin; SKILL.md smoke-test syntax is broken

`/setup-gbrain` SKILL.md, Step 9:

```bash
echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG"
gbrain search "smoke test" | grep -i "$SLUG"
```

`gbrain put` v0.18.2 does NOT read stdin. It requires the `--content` flag (per `gbrain put --help`). The `echo |` form fails with `No such file or directory`. The smoke test fires the doctor's NEEDS_CONTEXT escalation when it shouldn't.

**Workaround:**

```bash
gbrain put "$SLUG" --content "Set up on $(date). Smoke test for /setup-gbrain."
```

Or, better, use the MCP tool path which is the production route:

```bash
# in Claude Code: mcp__gbrain__put_page + mcp__gbrain__search
```

**Suggested fix:** update the SKILL.md Step 9 smoke-test command to use `--content` (or `--content -` for stdin convention if `gbrain put` will start accepting stdin in a future version).

## Other minor Windows notes (FYI, not blockers)

- `gbrain` on Windows installs to `C:/Users//.bun/bin/gbrain.exe`, not `~/.bun/bin/gbrain`. The skill's MCP-registration absolute-path fallback (`GBRAIN_BIN="$HOME/.bun/bin/gbrain"`) won't find it without the `.exe`; `command -v gbrain` worked correctly so this didn't matter on this install, but might bite users without bun-bin on PATH.
- `~/.gbrain/config.json` writes `database_path` (not `path` as the skill's prose mentions); minor discrepancy.
- MCP tools surfaced **mid-session** after `claude mcp add` — SKILL.md says "restart required." On this Claude Code version (Windows, late April 2026), MCP discovery is dynamic. Worth softening the wording.

## Repro environment

- gbrain.exe at `C:/Users/xhiri/.bun/bin/gbrain.exe`
- PGLite brain at `C:\Users\xhiri\.gbrain\brain.pglite\`
- gbrain doctor: status warnings, score 70 (fresh install, expected)
- Smoke test: PASS via `mcp__gbrain__put_page` + `mcp__gbrain__search` (score 0.999), FAIL via CLI `echo | gbrain put`

Happy to test fixes if they ship.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.