hai/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-21 20:28:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: setup-gbrain Path 4 (remote MCP) + artifacts rename

Browse Source 
Path 4 lets users paste an HTTPS MCP URL + bearer token and registers it
as an HTTP-transport MCP without needing a local gbrain CLI install. The
flow:

- Step 2 gains a fourth option (Remote gbrain MCP)
- Step 4 adds Path 4 sub-flow: collect URL, secret-read bearer, verify
  via gstack-gbrain-mcp-verify (NETWORK / AUTH / MALFORMED classifier)
- Step 5 (local doctor), Step 7.5 (transcript ingest), Step 5a's stdio
  branch all skip on Path 4
- Step 5a adds an HTTP+bearer registration form: claude mcp add
  --transport http --header "Authorization: Bearer ..."
- Step 7 renamed "session memory sync" → "artifacts sync" and now calls
  gstack-artifacts-init (which always prints the brain-admin hookup
  command — no auto-execute, codex Finding #3)
- Step 8 CLAUDE.md block branches: remote-http includes URL + server
  version (never the token); local-stdio keeps engine + config-file
- Step 9 smoke test on Path 4 prints the curl-equivalent for
  post-restart verification (MCP tools aren't visible mid-session)
- Step 10 verdict block has separate templates per mode

Idempotency: re-running with gbrain_mcp_mode=remote-http already in
detect output skips Step 2 entirely and goes to verification.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-05-06 09:24:52 -07:00
parent b06184e097
commit 7b9c2f68d4
2 changed files with 472 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
setup-gbrain/SKILL.md
View File

@@ -758,7 +758,12 @@ invocation flags here and skip to the matching step.
## Step 2: Pick a path (AskUserQuestion) ## Step 2: Pick a path (AskUserQuestion)
Only fire this if Step 1 shows no existing working config AND no shortcut Only fire this if Step 1 shows no existing working config AND no shortcut
flag was passed. The question title: "Where should your brain live?" flag was passed. **Special case:** if `gbrain_mcp_mode=remote-http` in the
detect output, an HTTP MCP is already registered — skip directly to Step 5a
verification (re-test the registration) and Step 6 onward, treating this run
as idempotent. Don't ask Step 2 again.
The question title: "Where should your brain live?"
Options (present based on detected state): Options (present based on detected state):
@@ -775,6 +780,11 @@ Options (present based on detected state):
yourself; paste the URL back when ready. yourself; paste the URL back when ready.
- **3 — PGLite local.** Zero accounts, ~30 seconds. Isolated brain on this - **3 — PGLite local.** Zero accounts, ~30 seconds. Isolated brain on this
Mac only. Best for try-first. Mac only. Best for try-first.
- **4 — Remote gbrain MCP.** Someone else (or another machine of yours) is
already running `gbrain serve` with HTTP transport. You paste the MCP URL
+ a bearer token; this skill registers it as your MCP. No local brain DB,
no local install needed. Recommended when the brain is shared across
machines or run by a teammate.
- **Switch** (only if Step 1 detected an existing engine): "You already have - **Switch** (only if Step 1 detected an existing engine): "You already have
a `<engine>` brain. Migrate it to the other engine?" → runs a `<engine>` brain. Migrate it to the other engine?" → runs
`gbrain migrate --to <other>` wrapped in `timeout 180s` (D9). `gbrain migrate --to <other>` wrapped in `timeout 180s` (D9).
@@ -785,7 +795,11 @@ Do NOT silently pick; fire the AskUserQuestion.
## Step 3: Install gbrain CLI (if missing) ## Step 3: Install gbrain CLI (if missing)
Only if `gbrain_on_path=false`: **SKIP entirely on Path 4 (Remote MCP).** Path 4 doesn't need a local gbrain
binary — all calls go through MCP to the remote server. Jump to Step 4 (the
Path 4 subsection).
For Paths 1, 2a, 2b, 3, switch — only if `gbrain_on_path=false`:
```bash ```bash
~/.claude/skills/gstack/bin/gstack-gbrain-install ~/.claude/skills/gstack/bin/gstack-gbrain-install
@@ -930,6 +944,64 @@ gbrain init --pglite --json
Done. No network, no secrets. Done. No network, no secrets.
### Path 4 (Remote gbrain MCP — HTTP transport with bearer token)
For users whose brain runs on another machine (Tailscale, ngrok, internal
LAN, or a teammate's server). No local gbrain CLI install, no local DB.
This skill registers the remote MCP and stops; ingestion + indexing happens
on the brain host.
**4a. Collect MCP URL.** Prompt the user:
```
Paste your gbrain MCP URL (e.g. https://wintermute.tail554574.ts.net:3131/mcp):
```
Read with plain `read -r` (no secret hygiene needed — the URL alone isn't
a credential). Validate it starts with `https://` (require TLS for any
non-loopback host); refuse `http://` for non-localhost.
**4b. Collect bearer token via the secret-read helper (D10, never argv).**
```bash
. ~/.claude/skills/gstack/bin/gstack-gbrain-lib.sh
read_secret_to_env GBRAIN_MCP_TOKEN "Paste bearer token: " \
--echo-redacted 's/.\{6\}$/***REDACTED***/'
```
**4c. Verify via gstack-gbrain-mcp-verify.** Run the helper; capture the
classified JSON output:
```bash
verify_json=$(GBRAIN_MCP_TOKEN="$GBRAIN_MCP_TOKEN" \
~/.claude/skills/gstack/bin/gstack-gbrain-mcp-verify "$MCP_URL")
status=$(echo "$verify_json" | jq -r .status)
```
If `status != "success"`, the helper has already classified the failure
into NETWORK / AUTH / MALFORMED and emitted a one-line remediation hint.
Surface the hint above the raw error from `error_text` and **STOP** with
a clear "fix and re-run /setup-gbrain" message. Do NOT continue to Step 5a
on a failed verify — partial registration would leave the user with a
half-broken state.
Capture two values from the verify output for downstream steps:
- `SERVER_VERSION` (e.g., `0.27.1`) — written to the CLAUDE.md block in Step 8.
- `URL_FORM_SUPPORTED` (`true|false`) — passed to `gstack-artifacts-init` in
Step 7 to control which form of the brain-admin hookup command is printed.
**4d. Skip Steps 3, 4 (other paths), 5 (local doctor), 7.5 (transcript ingest).**
All four require a working local `gbrain` CLI that Path 4 does not install.
The skill jumps straight to Step 5a (HTTP+bearer registration) → Step 6
(per-remote policy) → Step 7 (artifacts repo) → Step 8 (CLAUDE.md) → Step 9
(remote smoke test) → Step 10 (verdict).
The bearer token (`GBRAIN_MCP_TOKEN`) stays in process env until Step 5a's
`claude mcp add --header` consumes it; then `unset GBRAIN_MCP_TOKEN`
immediately. Token security trade-off documented in
`setup-gbrain/memory.md`: brief argv exposure during `claude mcp add`,
resting state in `~/.claude.json` mode 0600.
### Switch (from detect's existing-engine state) ### Switch (from detect's existing-engine state)
```bash ```bash
@@ -948,6 +1020,13 @@ holding a lock on the source brain. Close other workspaces and re-run
## Step 5: Verify gbrain doctor ## Step 5: Verify gbrain doctor
**SKIP entirely on Path 4 (Remote MCP).** The brain host runs its own
doctor; we don't have local DB access to introspect. Step 4c's verify
round-trip already proved the server is reachable, authed, and on a
compatible MCP version.
For Paths 1, 2a, 2b, 3, switch:
```bash ```bash
doctor=$(gbrain doctor --json) doctor=$(gbrain doctor --json)
status=$(echo "$doctor" | jq -r .status) status=$(echo "$doctor" | jq -r .status)
@@ -963,7 +1042,33 @@ doctor output and STOP.
Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface
for gbrain? (recommended yes)" for gbrain? (recommended yes)"
If yes, register at **user scope** with an **absolute path** to the gbrain The registration form depends on the path picked in Step 2:
### Path 4 (Remote MCP — HTTP transport with bearer)
Tear down any prior registration (could be local-stdio from an old setup,
or stale remote-http with a rotated token), then register with HTTP +
bearer at user scope:
```bash
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user --transport http gbrain "$MCP_URL" \
--header "Authorization: Bearer $GBRAIN_MCP_TOKEN"
unset GBRAIN_MCP_TOKEN # zero from process env after registration
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
**Token-storage note:** `claude mcp add --header "Authorization: Bearer ..."`
puts the bearer on argv during process startup, briefly visible to `ps` for
~10ms. The token's resting state is `~/.claude.json` (mode 0600 — Claude
Code's own credential surface for every MCP server). This trade-off is
documented in `setup-gbrain/memory.md`. If a future Claude Code release adds
a stdin or env-var input form for headers, switch to that.
### Paths 1, 2a, 2b, 3 (Local stdio)
Register at **user scope** with an **absolute path** to the gbrain
binary. User scope makes the MCP available in every Claude Code session on binary. User scope makes the MCP available in every Claude Code session on
this machine, not just the current workspace. Absolute path avoids PATH this machine, not just the current workspace. Absolute path avoids PATH
resolution issues when Claude Code spawns `gbrain serve` as a subprocess. resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
@@ -971,19 +1076,17 @@ resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
```bash ```bash
GBRAIN_BIN=$(command -v gbrain) GBRAIN_BIN=$(command -v gbrain)
[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain" [ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain"
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
claude mcp list | grep gbrain # verify: should show "✓ Connected" claude mcp list | grep gbrain # verify: should show "✓ Connected"
``` ```
If the user already had a local-scope registration from an earlier run, ### Both paths
remove it first so both scopes don't conflict:
```bash
claude mcp remove gbrain 2>/dev/null || true
```
If `claude` is not on PATH: emit "MCP registration skipped — this skill is If `claude` is not on PATH: emit "MCP registration skipped — this skill is
Claude-Code-targeted; register `gbrain serve` in your agent's MCP config Claude-Code-targeted; register `gbrain serve` (or your remote MCP URL) in
manually." Continue to step 6. your agent's MCP config manually." Continue to step 6.
**Heads-up for the user:** an already-open Claude Code session will not **Heads-up for the user:** an already-open Claude Code session will not
pick up the new MCP tools until restart. Tell them: "Restart any open pick up the new MCP tools until restart. Tell them: "Restart any open
@@ -1025,30 +1128,53 @@ For `/setup-gbrain --repo` invocations, execute ONLY Step 6 and exit.
--- ---
## Step 7: Offer gstack-brain-sync + wire it into gbrain ## Step 7: Offer artifacts sync + wire it into gbrain
Separate AskUserQuestion: "Also sync your gstack session memory (learnings, Renamed from "session memory sync" in v1.27.0.0 — the on-disk concept is
plans, retros) to a private git repo that gbrain can index across machines?" artifacts (CEO plans, designs, /investigate reports, retros) rather than
"session memory," which was a confusing name for what was always a
human-readable artifact bucket. Behavioral transcript ingest is its own
step (7.5) with its own option set.
Separate AskUserQuestion: "Also sync your gstack artifacts (CEO plans,
designs, reports, retros) to a private git repo that gbrain can index
across machines?"
Options: Options:
- Yes, full sync (everything allowlisted) - Yes, full sync (everything allowlisted)
- Yes, artifacts-only (plans, designs, retros — skip behavioral data) - Yes, artifacts-only (plans, designs, retros — skip behavioral data)
- No thanks - No thanks
If yes: If yes, run the artifacts-init helper. It asks the user to pick a git host
(GitHub via `gh`, GitLab via `glab`, or paste a URL manually), creates
`gstack-artifacts-$USER` (private), and writes the canonical HTTPS URL to
`~/.gstack-artifacts-remote.txt`. Pass `--url-form-supported` from Step 4c's
verify output (Path 4) or `false` (Paths 1/2/3 — local mode doesn't probe):
```bash ```bash
~/.claude/skills/gstack/bin/gstack-brain-init URL_FORM=${URL_FORM_SUPPORTED:-false}
~/.claude/skills/gstack/bin/gstack-config set gbrain_sync_mode artifacts-only ~/.claude/skills/gstack/bin/gstack-artifacts-init --url-form-supported "$URL_FORM"
~/.claude/skills/gstack/bin/gstack-config set artifacts_sync_mode artifacts-only
# or "full" if user picked yes-full # or "full" if user picked yes-full
``` ```
Then wire the brain repo into gbrain so its content is searchable from any `gstack-artifacts-init` always prints a "Send this to your brain admin" block
gbrain client (this Claude Code session, future Macs, optional cloud agents). at the end with the exact `gbrain sources add` command. Per codex Finding #3:
The helper creates a `git worktree` of `~/.gstack/`, registers it as a the skill never auto-executes server-side gbrain commands; even if the user
federated source on the user's gbrain (Supabase or PGLite), and runs an IS the brain admin, copy-pasting the printed command is the consistent UX.
initial `gbrain sync`. Local-Mac only. No cloud agent required. Subsequent
skill runs trigger incremental sync via the existing skill-end push hook. ### Path 4 (Remote MCP) — done after artifacts-init
In remote mode, the local `gstack-gbrain-source-wireup` helper does NOT run
(it shells out to a local `gbrain` CLI which Path 4 doesn't install). The
brain admin runs the printed command on the brain host instead. Skip to Step 7.5.
### Paths 1, 2a, 2b, 3 (Local stdio) — wire up the federated source
Then wire the artifacts repo into gbrain so its content is searchable from
any gbrain client. The helper creates a `git worktree` of `~/.gstack/`,
registers it as a federated source via `gbrain sources add --path
--federated`, and runs an initial `gbrain sync`. Local-Mac only.
Capture the database URL out of `~/.gbrain/config.json` first and pass it Capture the database URL out of `~/.gbrain/config.json` first and pass it
explicitly so the wireup is robust against any other process rewriting explicitly so the wireup is robust against any other process rewriting
@@ -1078,6 +1204,15 @@ the prereq is fixed.
## Step 7.5: Transcript & memory ingest gate ## Step 7.5: Transcript & memory ingest gate
**SKIP entirely on Path 4 (Remote MCP).** Transcript ingest shells out to
the local `gbrain` CLI which Path 4 doesn't install. Remote-mode users
rely on the brain server's own ingest cadence — if your brain admin wants
this machine's transcripts indexed, they pull from your `gstack-artifacts-$USER`
repo (set up in Step 7) on whatever schedule they prefer. Set
`gstack-config set transcript_ingest_mode off` and continue to Step 8.
For Paths 1, 2a, 2b, 3:
After memory sync is wired (Step 7) but before persisting the CLAUDE.md After memory sync is wired (Step 7) but before persisting the CLAUDE.md
config (Step 8), offer to bring this Mac's coding-agent transcripts + config (Step 8), offer to bring this Mac's coding-agent transcripts +
curated `~/.gstack/` artifacts into gbrain so the retrieval surface curated `~/.gstack/` artifacts into gbrain so the retrieval surface
@@ -1147,15 +1282,37 @@ Step 8).
## Step 8: Persist `## GBrain Configuration` in CLAUDE.md ## Step 8: Persist `## GBrain Configuration` in CLAUDE.md
Find-and-replace (or append) this section in CLAUDE.md: Find-and-replace (or append) the section. Block format depends on mode:
### Path 4 (Remote MCP)
```markdown ```markdown
## GBrain Configuration (configured by /setup-gbrain) ## GBrain Configuration (configured by /setup-gbrain)
- Mode: remote-http
- MCP URL: {MCP_URL}
- Server version: gbrain v{SERVER_VERSION} (from Step 4c verify)
- Setup date: {today}
- MCP registered: yes (user scope)
- Token: stored in ~/.claude.json (do not commit; never written to CLAUDE.md)
- Artifacts repo: {gstack_artifacts_remote URL or "none"}
- Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset}
```
The bearer token is **never** written to CLAUDE.md (CLAUDE.md is checked
in to git in many projects). It lives only in `~/.claude.json` where
`claude mcp add` placed it.
### Paths 1, 2a, 2b, 3 (Local stdio)
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: local-stdio
- Engine: {pglite|postgres} - Engine: {pglite|postgres}
- Config file: ~/.gbrain/config.json (mode 0600) - Config file: ~/.gbrain/config.json (mode 0600)
- Setup date: {today} - Setup date: {today}
- MCP registered: {yes/no} - MCP registered: {yes/no}
- Memory sync: {off|artifacts-only|full} - Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset} - Current repo policy: {read-write|read-only|deny|unset}
``` ```
@@ -1207,6 +1364,34 @@ the round-trip works.
## Step 9: Smoke test ## Step 9: Smoke test
### Path 4 (Remote MCP)
The `mcp__gbrain__*` tools aren't visible mid-session — they're loaded at
Claude Code session start. So the live smoke test in this same skill run is
informational: print the curl-equivalent the user can run after restarting
Claude Code. The verify round-trip in Step 4c already proved the server is
reachable + authed + on a compatible MCP version, so we don't re-test that.
Print to stdout:
```
After restarting Claude Code, the `mcp__gbrain__*` tools become callable.
Smoke test: ask the agent to run `mcp__gbrain__search` with any query
("test page" works). You should see a JSON list of pages.
To verify from the shell right now (without waiting for restart):
curl -s -X POST -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
<YOUR_MCP_URL>
```
Do NOT print the actual token in the curl command — leave the placeholder
`<YOUR_TOKEN>` so the snippet is safe to copy into chat / share.
### Paths 1, 2a, 2b, 3 (Local stdio)
```bash ```bash
SLUG="setup-gbrain-smoke-test-$(date +%s)" SLUG="setup-gbrain-smoke-test-$(date +%s)"
echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG" echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG"
@@ -1227,15 +1412,37 @@ state, repairs only what's missing, and reports here.
```bash ```bash
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null || true ~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null || true
~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || echo "off" ~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || echo "off"
~/.claude/skills/gstack/bin/gstack-config get gbrain_sync_mode 2>/dev/null || echo "off" ~/.claude/skills/gstack/bin/gstack-config get artifacts_sync_mode 2>/dev/null || echo "off"
[ -f ~/.gstack/.gbrain-sync-state.json ] && cat ~/.gstack/.gbrain-sync-state.json || echo "{}" [ -f ~/.gstack/.gbrain-sync-state.json ] && cat ~/.gstack/.gbrain-sync-state.json || echo "{}"
``` ```
Print the verdict block. Each row is `[OK]/[FIX]/[WARN]/[ERR]` — see Read `gbrain_mcp_mode` from the detect output and pick the right verdict
template below; substitute your detect outputs: template. Each row is `[OK]/[FIX]/[WARN]/[ERR]`.
### Path 4 (Remote MCP)
``` ```
gbrain status: GREEN gbrain status: GREEN (mode: remote-http)
MCP ............. OK {SERVER_NAME} v{SERVER_VERSION} at {MCP_URL}
Auth ............ OK bearer accepted (verified via /tools/list)
Engine .......... N/A remote mode
Doctor .......... N/A remote mode (brain admin runs `gbrain doctor`)
Repo policy ..... OK {read-write|read-only|deny}
Artifacts repo .. OK {gstack_artifacts_remote URL}
Artifacts sync .. OK {artifacts_sync_mode}
Transcripts ..... N/A remote mode (ingest happens on brain host)
CLAUDE.md ....... OK
Smoke test ...... INFO printed for post-restart manual verification
Restart Claude Code to pick up the `mcp__gbrain__*` tools.
Re-run `/setup-gbrain` any time the bearer rotates or the URL moves.
```
### Paths 1, 2a, 2b, 3 (Local stdio)
```
gbrain status: GREEN (mode: local-stdio)
CLI ............. OK <gbrain version> CLI ............. OK <gbrain version>
Engine .......... OK <pglite|supabase> at <path> Engine .......... OK <pglite|supabase> at <path>
@@ -1243,7 +1450,7 @@ gbrain status: GREEN
MCP ............. OK registered (user scope) MCP ............. OK registered (user scope)
Repo policy ..... OK <read-write|read-only|deny> Repo policy ..... OK <read-write|read-only|deny>
Code import ..... OK <last_imported_head> Code import ..... OK <last_imported_head>
Memory sync ..... OK <gbrain_sync_mode> to <remote> Artifacts sync .. OK <artifacts_sync_mode> to <remote>
Transcripts ..... OK <N> sessions, last ingest <when> Transcripts ..... OK <N> sessions, last ingest <when>
CLAUDE.md ....... OK CLAUDE.md ....... OK
Smoke test ...... OK put → search → delete round-trip Smoke test ...... OK put → search → delete round-trip

265
setup-gbrain/SKILL.md.tmpl
View File

@@ -80,7 +80,12 @@ invocation flags here and skip to the matching step.
## Step 2: Pick a path (AskUserQuestion) ## Step 2: Pick a path (AskUserQuestion)
Only fire this if Step 1 shows no existing working config AND no shortcut Only fire this if Step 1 shows no existing working config AND no shortcut
flag was passed. The question title: "Where should your brain live?" flag was passed. **Special case:** if `gbrain_mcp_mode=remote-http` in the
detect output, an HTTP MCP is already registered — skip directly to Step 5a
verification (re-test the registration) and Step 6 onward, treating this run
as idempotent. Don't ask Step 2 again.
The question title: "Where should your brain live?"
Options (present based on detected state): Options (present based on detected state):
@@ -97,6 +102,11 @@ Options (present based on detected state):
yourself; paste the URL back when ready. yourself; paste the URL back when ready.
- **3 — PGLite local.** Zero accounts, ~30 seconds. Isolated brain on this - **3 — PGLite local.** Zero accounts, ~30 seconds. Isolated brain on this
Mac only. Best for try-first. Mac only. Best for try-first.
- **4 — Remote gbrain MCP.** Someone else (or another machine of yours) is
already running `gbrain serve` with HTTP transport. You paste the MCP URL
+ a bearer token; this skill registers it as your MCP. No local brain DB,
no local install needed. Recommended when the brain is shared across
machines or run by a teammate.
- **Switch** (only if Step 1 detected an existing engine): "You already have - **Switch** (only if Step 1 detected an existing engine): "You already have
a `<engine>` brain. Migrate it to the other engine?" → runs a `<engine>` brain. Migrate it to the other engine?" → runs
`gbrain migrate --to <other>` wrapped in `timeout 180s` (D9). `gbrain migrate --to <other>` wrapped in `timeout 180s` (D9).
@@ -107,7 +117,11 @@ Do NOT silently pick; fire the AskUserQuestion.
## Step 3: Install gbrain CLI (if missing) ## Step 3: Install gbrain CLI (if missing)
Only if `gbrain_on_path=false`: **SKIP entirely on Path 4 (Remote MCP).** Path 4 doesn't need a local gbrain
binary — all calls go through MCP to the remote server. Jump to Step 4 (the
Path 4 subsection).
For Paths 1, 2a, 2b, 3, switch — only if `gbrain_on_path=false`:
```bash ```bash
~/.claude/skills/gstack/bin/gstack-gbrain-install ~/.claude/skills/gstack/bin/gstack-gbrain-install
@@ -252,6 +266,64 @@ gbrain init --pglite --json
Done. No network, no secrets. Done. No network, no secrets.
### Path 4 (Remote gbrain MCP — HTTP transport with bearer token)
For users whose brain runs on another machine (Tailscale, ngrok, internal
LAN, or a teammate's server). No local gbrain CLI install, no local DB.
This skill registers the remote MCP and stops; ingestion + indexing happens
on the brain host.
**4a. Collect MCP URL.** Prompt the user:
```
Paste your gbrain MCP URL (e.g. https://wintermute.tail554574.ts.net:3131/mcp):
```
Read with plain `read -r` (no secret hygiene needed — the URL alone isn't
a credential). Validate it starts with `https://` (require TLS for any
non-loopback host); refuse `http://` for non-localhost.
**4b. Collect bearer token via the secret-read helper (D10, never argv).**
```bash
. ~/.claude/skills/gstack/bin/gstack-gbrain-lib.sh
read_secret_to_env GBRAIN_MCP_TOKEN "Paste bearer token: " \
--echo-redacted 's/.\{6\}$/***REDACTED***/'
```
**4c. Verify via gstack-gbrain-mcp-verify.** Run the helper; capture the
classified JSON output:
```bash
verify_json=$(GBRAIN_MCP_TOKEN="$GBRAIN_MCP_TOKEN" \
~/.claude/skills/gstack/bin/gstack-gbrain-mcp-verify "$MCP_URL")
status=$(echo "$verify_json" | jq -r .status)
```
If `status != "success"`, the helper has already classified the failure
into NETWORK / AUTH / MALFORMED and emitted a one-line remediation hint.
Surface the hint above the raw error from `error_text` and **STOP** with
a clear "fix and re-run /setup-gbrain" message. Do NOT continue to Step 5a
on a failed verify — partial registration would leave the user with a
half-broken state.
Capture two values from the verify output for downstream steps:
- `SERVER_VERSION` (e.g., `0.27.1`) — written to the CLAUDE.md block in Step 8.
- `URL_FORM_SUPPORTED` (`true|false`) — passed to `gstack-artifacts-init` in
Step 7 to control which form of the brain-admin hookup command is printed.
**4d. Skip Steps 3, 4 (other paths), 5 (local doctor), 7.5 (transcript ingest).**
All four require a working local `gbrain` CLI that Path 4 does not install.
The skill jumps straight to Step 5a (HTTP+bearer registration) → Step 6
(per-remote policy) → Step 7 (artifacts repo) → Step 8 (CLAUDE.md) → Step 9
(remote smoke test) → Step 10 (verdict).
The bearer token (`GBRAIN_MCP_TOKEN`) stays in process env until Step 5a's
`claude mcp add --header` consumes it; then `unset GBRAIN_MCP_TOKEN`
immediately. Token security trade-off documented in
`setup-gbrain/memory.md`: brief argv exposure during `claude mcp add`,
resting state in `~/.claude.json` mode 0600.
### Switch (from detect's existing-engine state) ### Switch (from detect's existing-engine state)
```bash ```bash
@@ -270,6 +342,13 @@ holding a lock on the source brain. Close other workspaces and re-run
## Step 5: Verify gbrain doctor ## Step 5: Verify gbrain doctor
**SKIP entirely on Path 4 (Remote MCP).** The brain host runs its own
doctor; we don't have local DB access to introspect. Step 4c's verify
round-trip already proved the server is reachable, authed, and on a
compatible MCP version.
For Paths 1, 2a, 2b, 3, switch:
```bash ```bash
doctor=$(gbrain doctor --json) doctor=$(gbrain doctor --json)
status=$(echo "$doctor" | jq -r .status) status=$(echo "$doctor" | jq -r .status)
@@ -285,7 +364,33 @@ doctor output and STOP.
Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface
for gbrain? (recommended yes)" for gbrain? (recommended yes)"
If yes, register at **user scope** with an **absolute path** to the gbrain The registration form depends on the path picked in Step 2:
### Path 4 (Remote MCP — HTTP transport with bearer)
Tear down any prior registration (could be local-stdio from an old setup,
or stale remote-http with a rotated token), then register with HTTP +
bearer at user scope:
```bash
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user --transport http gbrain "$MCP_URL" \
--header "Authorization: Bearer $GBRAIN_MCP_TOKEN"
unset GBRAIN_MCP_TOKEN # zero from process env after registration
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
**Token-storage note:** `claude mcp add --header "Authorization: Bearer ..."`
puts the bearer on argv during process startup, briefly visible to `ps` for
~10ms. The token's resting state is `~/.claude.json` (mode 0600 — Claude
Code's own credential surface for every MCP server). This trade-off is
documented in `setup-gbrain/memory.md`. If a future Claude Code release adds
a stdin or env-var input form for headers, switch to that.
### Paths 1, 2a, 2b, 3 (Local stdio)
Register at **user scope** with an **absolute path** to the gbrain
binary. User scope makes the MCP available in every Claude Code session on binary. User scope makes the MCP available in every Claude Code session on
this machine, not just the current workspace. Absolute path avoids PATH this machine, not just the current workspace. Absolute path avoids PATH
resolution issues when Claude Code spawns `gbrain serve` as a subprocess. resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
@@ -293,19 +398,17 @@ resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
```bash ```bash
GBRAIN_BIN=$(command -v gbrain) GBRAIN_BIN=$(command -v gbrain)
[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain" [ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain"
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
claude mcp list | grep gbrain # verify: should show "✓ Connected" claude mcp list | grep gbrain # verify: should show "✓ Connected"
``` ```
If the user already had a local-scope registration from an earlier run, ### Both paths
remove it first so both scopes don't conflict:
```bash
claude mcp remove gbrain 2>/dev/null || true
```
If `claude` is not on PATH: emit "MCP registration skipped — this skill is If `claude` is not on PATH: emit "MCP registration skipped — this skill is
Claude-Code-targeted; register `gbrain serve` in your agent's MCP config Claude-Code-targeted; register `gbrain serve` (or your remote MCP URL) in
manually." Continue to step 6. your agent's MCP config manually." Continue to step 6.
**Heads-up for the user:** an already-open Claude Code session will not **Heads-up for the user:** an already-open Claude Code session will not
pick up the new MCP tools until restart. Tell them: "Restart any open pick up the new MCP tools until restart. Tell them: "Restart any open
@@ -347,30 +450,53 @@ For `/setup-gbrain --repo` invocations, execute ONLY Step 6 and exit.
--- ---
## Step 7: Offer gstack-brain-sync + wire it into gbrain ## Step 7: Offer artifacts sync + wire it into gbrain
Separate AskUserQuestion: "Also sync your gstack session memory (learnings, Renamed from "session memory sync" in v1.27.0.0 — the on-disk concept is
plans, retros) to a private git repo that gbrain can index across machines?" artifacts (CEO plans, designs, /investigate reports, retros) rather than
"session memory," which was a confusing name for what was always a
human-readable artifact bucket. Behavioral transcript ingest is its own
step (7.5) with its own option set.
Separate AskUserQuestion: "Also sync your gstack artifacts (CEO plans,
designs, reports, retros) to a private git repo that gbrain can index
across machines?"
Options: Options:
- Yes, full sync (everything allowlisted) - Yes, full sync (everything allowlisted)
- Yes, artifacts-only (plans, designs, retros — skip behavioral data) - Yes, artifacts-only (plans, designs, retros — skip behavioral data)
- No thanks - No thanks
If yes: If yes, run the artifacts-init helper. It asks the user to pick a git host
(GitHub via `gh`, GitLab via `glab`, or paste a URL manually), creates
`gstack-artifacts-$USER` (private), and writes the canonical HTTPS URL to
`~/.gstack-artifacts-remote.txt`. Pass `--url-form-supported` from Step 4c's
verify output (Path 4) or `false` (Paths 1/2/3 — local mode doesn't probe):
```bash ```bash
~/.claude/skills/gstack/bin/gstack-brain-init URL_FORM=${URL_FORM_SUPPORTED:-false}
~/.claude/skills/gstack/bin/gstack-config set gbrain_sync_mode artifacts-only ~/.claude/skills/gstack/bin/gstack-artifacts-init --url-form-supported "$URL_FORM"
~/.claude/skills/gstack/bin/gstack-config set artifacts_sync_mode artifacts-only
# or "full" if user picked yes-full # or "full" if user picked yes-full
``` ```
Then wire the brain repo into gbrain so its content is searchable from any `gstack-artifacts-init` always prints a "Send this to your brain admin" block
gbrain client (this Claude Code session, future Macs, optional cloud agents). at the end with the exact `gbrain sources add` command. Per codex Finding #3:
The helper creates a `git worktree` of `~/.gstack/`, registers it as a the skill never auto-executes server-side gbrain commands; even if the user
federated source on the user's gbrain (Supabase or PGLite), and runs an IS the brain admin, copy-pasting the printed command is the consistent UX.
initial `gbrain sync`. Local-Mac only. No cloud agent required. Subsequent
skill runs trigger incremental sync via the existing skill-end push hook. ### Path 4 (Remote MCP) — done after artifacts-init
In remote mode, the local `gstack-gbrain-source-wireup` helper does NOT run
(it shells out to a local `gbrain` CLI which Path 4 doesn't install). The
brain admin runs the printed command on the brain host instead. Skip to Step 7.5.
### Paths 1, 2a, 2b, 3 (Local stdio) — wire up the federated source
Then wire the artifacts repo into gbrain so its content is searchable from
any gbrain client. The helper creates a `git worktree` of `~/.gstack/`,
registers it as a federated source via `gbrain sources add --path
--federated`, and runs an initial `gbrain sync`. Local-Mac only.
Capture the database URL out of `~/.gbrain/config.json` first and pass it Capture the database URL out of `~/.gbrain/config.json` first and pass it
explicitly so the wireup is robust against any other process rewriting explicitly so the wireup is robust against any other process rewriting
@@ -400,6 +526,15 @@ the prereq is fixed.
## Step 7.5: Transcript & memory ingest gate ## Step 7.5: Transcript & memory ingest gate
**SKIP entirely on Path 4 (Remote MCP).** Transcript ingest shells out to
the local `gbrain` CLI which Path 4 doesn't install. Remote-mode users
rely on the brain server's own ingest cadence — if your brain admin wants
this machine's transcripts indexed, they pull from your `gstack-artifacts-$USER`
repo (set up in Step 7) on whatever schedule they prefer. Set
`gstack-config set transcript_ingest_mode off` and continue to Step 8.
For Paths 1, 2a, 2b, 3:
After memory sync is wired (Step 7) but before persisting the CLAUDE.md After memory sync is wired (Step 7) but before persisting the CLAUDE.md
config (Step 8), offer to bring this Mac's coding-agent transcripts + config (Step 8), offer to bring this Mac's coding-agent transcripts +
curated `~/.gstack/` artifacts into gbrain so the retrieval surface curated `~/.gstack/` artifacts into gbrain so the retrieval surface
@@ -469,15 +604,37 @@ Step 8).
## Step 8: Persist `## GBrain Configuration` in CLAUDE.md ## Step 8: Persist `## GBrain Configuration` in CLAUDE.md
Find-and-replace (or append) this section in CLAUDE.md: Find-and-replace (or append) the section. Block format depends on mode:
### Path 4 (Remote MCP)
```markdown ```markdown
## GBrain Configuration (configured by /setup-gbrain) ## GBrain Configuration (configured by /setup-gbrain)
- Mode: remote-http
- MCP URL: {MCP_URL}
- Server version: gbrain v{SERVER_VERSION} (from Step 4c verify)
- Setup date: {today}
- MCP registered: yes (user scope)
- Token: stored in ~/.claude.json (do not commit; never written to CLAUDE.md)
- Artifacts repo: {gstack_artifacts_remote URL or "none"}
- Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset}
```
The bearer token is **never** written to CLAUDE.md (CLAUDE.md is checked
in to git in many projects). It lives only in `~/.claude.json` where
`claude mcp add` placed it.
### Paths 1, 2a, 2b, 3 (Local stdio)
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: local-stdio
- Engine: {pglite|postgres} - Engine: {pglite|postgres}
- Config file: ~/.gbrain/config.json (mode 0600) - Config file: ~/.gbrain/config.json (mode 0600)
- Setup date: {today} - Setup date: {today}
- MCP registered: {yes/no} - MCP registered: {yes/no}
- Memory sync: {off|artifacts-only|full} - Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset} - Current repo policy: {read-write|read-only|deny|unset}
``` ```
@@ -529,6 +686,34 @@ the round-trip works.
## Step 9: Smoke test ## Step 9: Smoke test
### Path 4 (Remote MCP)
The `mcp__gbrain__*` tools aren't visible mid-session — they're loaded at
Claude Code session start. So the live smoke test in this same skill run is
informational: print the curl-equivalent the user can run after restarting
Claude Code. The verify round-trip in Step 4c already proved the server is
reachable + authed + on a compatible MCP version, so we don't re-test that.
Print to stdout:
```
After restarting Claude Code, the `mcp__gbrain__*` tools become callable.
Smoke test: ask the agent to run `mcp__gbrain__search` with any query
("test page" works). You should see a JSON list of pages.
To verify from the shell right now (without waiting for restart):
curl -s -X POST -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
<YOUR_MCP_URL>
```
Do NOT print the actual token in the curl command — leave the placeholder
`<YOUR_TOKEN>` so the snippet is safe to copy into chat / share.
### Paths 1, 2a, 2b, 3 (Local stdio)
```bash ```bash
SLUG="setup-gbrain-smoke-test-$(date +%s)" SLUG="setup-gbrain-smoke-test-$(date +%s)"
echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG" echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG"
@@ -549,15 +734,37 @@ state, repairs only what's missing, and reports here.
```bash ```bash
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null || true ~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null || true
~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || echo "off" ~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || echo "off"
~/.claude/skills/gstack/bin/gstack-config get gbrain_sync_mode 2>/dev/null || echo "off" ~/.claude/skills/gstack/bin/gstack-config get artifacts_sync_mode 2>/dev/null || echo "off"
[ -f ~/.gstack/.gbrain-sync-state.json ] && cat ~/.gstack/.gbrain-sync-state.json || echo "{}" [ -f ~/.gstack/.gbrain-sync-state.json ] && cat ~/.gstack/.gbrain-sync-state.json || echo "{}"
``` ```
Print the verdict block. Each row is `[OK]/[FIX]/[WARN]/[ERR]` — see Read `gbrain_mcp_mode` from the detect output and pick the right verdict
template below; substitute your detect outputs: template. Each row is `[OK]/[FIX]/[WARN]/[ERR]`.
### Path 4 (Remote MCP)
``` ```
gbrain status: GREEN gbrain status: GREEN (mode: remote-http)
MCP ............. OK {SERVER_NAME} v{SERVER_VERSION} at {MCP_URL}
Auth ............ OK bearer accepted (verified via /tools/list)
Engine .......... N/A remote mode
Doctor .......... N/A remote mode (brain admin runs `gbrain doctor`)
Repo policy ..... OK {read-write|read-only|deny}
Artifacts repo .. OK {gstack_artifacts_remote URL}
Artifacts sync .. OK {artifacts_sync_mode}
Transcripts ..... N/A remote mode (ingest happens on brain host)
CLAUDE.md ....... OK
Smoke test ...... INFO printed for post-restart manual verification
Restart Claude Code to pick up the `mcp__gbrain__*` tools.
Re-run `/setup-gbrain` any time the bearer rotates or the URL moves.
```
### Paths 1, 2a, 2b, 3 (Local stdio)
```
gbrain status: GREEN (mode: local-stdio)
CLI ............. OK <gbrain version> CLI ............. OK <gbrain version>
Engine .......... OK <pglite|supabase> at <path> Engine .......... OK <pglite|supabase> at <path>
@@ -565,7 +772,7 @@ gbrain status: GREEN
MCP ............. OK registered (user scope) MCP ............. OK registered (user scope)
Repo policy ..... OK <read-write|read-only|deny> Repo policy ..... OK <read-write|read-only|deny>
Code import ..... OK <last_imported_head> Code import ..... OK <last_imported_head>
Memory sync ..... OK <gbrain_sync_mode> to <remote> Artifacts sync .. OK <artifacts_sync_mode> to <remote>
Transcripts ..... OK <N> sessions, last ingest <when> Transcripts ..... OK <N> sessions, last ingest <when>
CLAUDE.md ....... OK CLAUDE.md ....... OK
Smoke test ...... OK put → search → delete round-trip Smoke test ...... OK put → search → delete round-trip