Garry's Opinionated OpenClaw/Hermes Agent Brain
Connect GBrain to opencode
This page is the MCP-registration reference for opencode — the SST terminal coding agent (opencode.ai, npm
opencode-ai; not OpenClaw, and not the originalopencodeCLI that was renamed Crush — see Troubleshooting). For the full brain install — CLI, engine, skills, dream cycle — follow INSTALL_FOR_AGENTS.md first; this page wires the finished brain into opencode over stdio MCP. opencode is a bootstrap-supported harness:gbrain bootstrap hooks --harness opencoderegisters the brain for you (andgbrain connect --agent opencodehandles remote brains — see below) — the commands on this page are the standalone manual recipe. Bootstrap's own registration additionally pins the workspace source (GBRAIN_SOURCE) and the full op surface, so the two are not byte-identical.
opencode spawns gbrain serve as a local stdio subprocess. No server, no
tunnel, no token needed. Works with both PGLite and Supabase engines — and
because opencode natively reads AGENTS.md, a gbrain workspace's rendered
brain contract loads with zero extra configuration.
Register (recommended)
opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- "$(command -v gbrain)" serve --surface starter --advertise verbs
--surface starter lists the daily-driver tools: the seven memory verbs
(MEMORY_VERBS v1), search, query,
get_page, put_page, capture, graph reads and skills. It is the surface every
new registration gbrain writes pins. A parameter it leaves out is still accepted,
and request_tools returns full schemas or widens the session to a left-out tool. --surface full lists every
operation (put_pages, admin and tuning ops) and is the opt-in; --surface verbs
lists only the seven verbs.
Three facts about opencode mcp add, all observed:
- The local-command form is
-- <command> [args...]after the flags — it's real but missing from--help(which shows only--url/--env/--header).--envis repeatable, oneKEY=VALUEper flag. - Registration is lazy. The add writes config and exits 0 without
connecting — even for a nonexistent command. Verify with
opencode mcp list(below), never with the add's exit code. - It always writes the USER-GLOBAL config
(
~/.config/opencode/opencode.jsonc) — there is no scope flag. For a project-scoped entry, write the projectopencode.jsondirectly (next section) — but read the sharing warning first.
Brain-first instructions
Registering the MCP server only makes the tools available. Agents seldom call a brain nobody told them about, so finish the install with:
gbrain setup opencode --instructions-only
It writes one short marked block into ~/.config/opencode/AGENTS.md (opencode's global rules): search the brain before reading
sources one by one, read the best hit, fill gaps with other tools, apply your own
access rules, then finish the task. Text outside the markers is never touched, a
re-run upgrades the block in place, --dry-run previews it,
--no-instructions opts out (and is remembered) and --remove takes it out.
gbrain connect --agent opencode --install writes it for you.
gbrain doctor warns when the block is missing or out of date.
Direct config (equally supported)
Global (~/.config/opencode/opencode.jsonc) or project (opencode.json in
the repo root — opencode's lookup traverses up to the git root):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"gbrain": {
"type": "local",
"command": ["gbrain", "serve", "--surface", "verbs"],
"environment": { "GBRAIN_HOME": "/home/alice-example" },
"enabled": true
}
}
}
Comments are fine — opencode parses JSONC in both .json and .jsonc files,
and both filenames are read (merged) when both exist. To remove gbrain,
delete the entry, or set "enabled": false to disable without losing it.
Sharing warning for project config: opencode spawns project-defined local
MCP servers with no trust prompt — a committed opencode.json carrying a
gbrain entry executes on every collaborator's machine. Teammates without
gbrain get a failing spawn each session; teammates WITH gbrain attach their
own host brain to your repo's context. Prefer the user-global config (the
gbrain bootstrap default); if you do commit a project entry, use the
PATH-resolved "gbrain" command form (never an absolute path) and tell
collaborators "enabled": false is the opt-out.
Verify
opencode mcp list # the real probe: SPAWNS the server
opencode mcp list performs the actual spawn + handshake for every
configured server — expect ✓ gbrain connected. A broken registration shows
✗ gbrain failed with the reason (e.g. Executable not found in $PATH).
Because it spawns everything — including any project opencode.json entries
in your cwd, with no trust prompt — run it from a directory you trust
(gbrain's own bootstrap verification probe runs from an empty temp directory
for exactly this reason, and skips the live probe entirely for project-scoped
registrations).
Two caveats: the exit code is 0 even when servers fail (read the output, not
$?), and opencode mcp debug is OAuth-only diagnostics — it is NOT a
handshake probe for local servers. Then one real round-trip:
opencode run "use the gbrain recall tool to answer: what did I import most recently?"
opencode run (headless one-shot) prints the final answer alone on stdout
(UI goes to stderr). MCP tools work in run mode without any permission flags.
Remote brains (gbrain connect)
For a brain served over HTTP on another machine:
gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install]
Without --install it prints the config block to add; with --install it
writes the entry directly into the user-global config (no opencode binary
required — the JSONC write IS the registration) and smoke-tests the token.
Either way the config stores only the {env:GBRAIN_REMOTE_TOKEN}
interpolation — opencode resolves the env var at read time, so the token
never lands in the file. Export GBRAIN_REMOTE_TOKEN in your shell profile.
--force replaces a gbrain-managed entry whose endpoint moved (a rotated
serve); an entry gbrain didn't write is never replaced — pick another
--name. (Framework-spawned opencode inherits no shell profile;
gbrain bootstrap harness --harness opencode covers that case with an
inline-bearer entry written 0600.)
Auth + model pin
- Keyless works. opencode ships an anonymous free tier (default model
opencode/big-pickleat observation time) — headless runs and MCP tool calls work with zero credentials. For paid providers, export the provider key (e.g.ANTHROPIC_API_KEY) or runopencode auth login(credentials land in~/.local/share/opencode/auth.json). - Model pin: pass
-m <provider/model>per call, or set"model"in the config.opencode modelslists what your credentials can reach. - Updates: opencode self-updates by default. For pinned/reproducible
environments, set BOTH
"autoupdate": falsein config ANDOPENCODE_DISABLE_AUTOUPDATE=1in the environment.
Pair with cron
opencode has no built-in cron; schedule headless one-shots with your system scheduler:
# crontab: brain maintenance every 4 hours
0 */4 * * * opencode run "Run gbrain sync and report anything unusual"
See docs/guides/cron-schedule.md for the full brain maintenance protocol (sync, embed, dream cycle).
Troubleshooting
- Wrong
opencodeon PATH — the name has prior claimants (the originalopencodeproject was renamed Crush). The SST CLI answersopencode --versionwith a bare semver (1.18.18) and hasopencode mcpopencode debug pathssubcommands. Install it vianpm install -g opencode-aiorcurl -fsSL https://opencode.ai/install | bash.
- opencode ≠ OpenClaw — opencode (opencode.ai / SST) is the terminal agent this page covers; OpenClaw is the agent platform with its own gbrain runner and docs (OPENCLAW.md).
✗ gbrain failed — Executable not found in $PATH— the registered command was the bare"gbrain"name and opencode's PATH doesn't carry it. Use the absolute binary path in the user-global config, or fix PATH.- Registered but nothing changed mid-session — opencode reads config at session start; restart opencode (or start a new session) after registering.
OPENCODE_CONFIGseems ignored — observed inert in v1.18.18: onlyHOME/XDG_CONFIG_HOMEmove the config location. Don't rely on it.- Which config won? —
opencode debug configprints the resolved merge;opencode debug pathsprints every directory opencode uses. - Rules files — opencode loads the project
AGENTS.md(a siblingCLAUDE.mdis NOT double-loaded; AGENTS.md wins). gbrain's rendered workspace contract rides this natively.
Verified against opencode v1.18.18 (fast-moving project — the pin is enforced in CI, with a latest-version canary leg watching for drift). Dev-facing observed-behavior notes (exact flag semantics, exit-code caveats, config schema, CI pin values) live in OPENCODE-CLI-PIN.md.