opencode-remote-brain

OpenCode plugin that syncs rules and skills from a public GitHub repository into OpenCode's native configuration.

How it works

On startup, the plugin clones (or pulls) the configured GitHub repo, parses index.yaml, then injects the listed rules as instructions and skills as skill paths into your OpenCode config. Everything is cached locally so subsequent startups are fast.

The remote-sync tool lets you manually trigger a re-sync mid-session. Changes take effect on the next startup.

If a sync fails for any reason, the plugin falls back to the last successful sync so you're never left without your rules and skills.

Install

npm install opencode-remote-brain

Requires git to be installed and available on your PATH.

Configuration

Create ~/.config/opencode/remote-brain.jsonc (or $XDG_CONFIG_HOME/opencode/remote-brain.jsonc):

{
  // Required: GitHub repo in "owner/repo" format
  "repo": "your-org/your-brain",
  // Optional: branch, tag, or commit (default: "main")
  "ref": "main",
  // Optional: index file path within the repo (default: "index.yaml")
  "indexFile": "index.yaml",
  // Optional: local cache directory (default: "~/.cache/opencode/remote-brain")
  "cacheDir": "~/.cache/opencode/remote-brain"
}

You can also point $schema at the bundled schema for editor validation:

{
  "$schema": "./node_modules/opencode-remote-brain/assets/remote-brain.schema.json",
  "repo": "your-org/your-brain"
}

Repository index format

Your remote repo needs an index.yaml at the root (or at the path set by indexFile):

version: 1
rules:
  - rules/my-rule.md       # relative path to a markdown rule file
skills:
  - skills/my-skill        # relative path to a skill directory (must contain SKILL.md)

All paths are relative to the repo root. Absolute paths and .. segments are rejected.

Register the plugin in OpenCode

Add the plugin to your ~/.config/opencode/config.json:

{
  "plugins": ["opencode-remote-brain"]
}

Using the remote-sync tool

Inside OpenCode, run the remote-sync tool to pull the latest changes from your remote repo. The sync updates the local cache. Restart OpenCode (or start a new session) for the changes to take effect.

Troubleshooting

Sync fails silently Check that git is installed and accessible, and that the configured repo is public.

Rules or skills not loading Verify that the paths in index.yaml are relative, exist in the repo, and that rule files end in .md. Skill directories must contain a SKILL.md file.

Path traversal rejected Paths containing .. segments or absolute paths are blocked for security. Keep all paths relative to the repo root.

Security

Every path read from index.yaml is validated before use. Paths with .. segments or absolute paths are rejected outright. A realpath check then confirms the resolved file stays within the cloned repo directory, preventing any traversal outside the cache.

Development

# Install dependencies
bun install

# Run tests
bun test

# Type-check
bun run typecheck

# Build
bun run build