Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.2 KB
Raw Blame

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 original opencode CLI 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 opencode registers the brain for you (and gbrain connect --agent opencode handles 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). --env is repeatable, one KEY=VALUE per 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 project opencode.json directly (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-pickle at 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 run opencode 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 models lists what your credentials can reach.
  • Updates: opencode self-updates by default. For pinned/reproducible environments, set BOTH "autoupdate": false in config AND OPENCODE_DISABLE_AUTOUPDATE=1 in 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 opencode on PATH — the name has prior claimants (the original opencode project was renamed Crush). The SST CLI answers opencode --version with a bare semver (1.18.18) and has opencode mcp
    • opencode debug paths subcommands. Install it via npm install -g opencode-ai or curl -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_CONFIG seems ignored — observed inert in v1.18.18: only HOME/XDG_CONFIG_HOME move the config location. Don't rely on it.
  • Which config won? — opencode debug config prints the resolved merge; opencode debug paths prints every directory opencode uses.
  • Rules files — opencode loads the project AGENTS.md (a sibling CLAUDE.md is 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.