opencode-remote-config

An OpenCode plugin that syncs skills, agents, commands, and instructions from Git repositories, making them available to OpenCode without polluting your local configuration.

Features

• Git-based sync: Clone once, fetch updates on startup
• Local directories: Use file:// URLs for local directories (great for development)
• Skills import: Import skill definitions from skill/ directory
• Agents import: Import agent definitions from agent/ directory
• Commands import: Import slash commands from command/ directory
• Plugins import: Import OpenCode hook plugins from plugin/ directory
• Instructions import: Import AGENTS.md instructions via manifest.json
• Selective import: Use include or exclude filters for fine-grained control
• Ref pinning: Pin to branch, tag, or commit SHA
• Priority handling: User config > first repository > subsequent repositories
• Conflict handling: Local definitions take precedence, warns on conflicts
• Gitignore management: Automatically adds _plugins/ to .gitignore

---

For Humans

Installation

Option 1: npm (Recommended)

# Global installation
npm install -g @jgordijn/opencode-remote-config

# Or with bun
bun add -g @jgordijn/opencode-remote-config

Then add the plugin to your OpenCode config (~/.config/opencode/opencode.json or .opencode/opencode.json):

{
  "plugins": ["@jgordijn/opencode-remote-config"]
}

Option 2: Git clone

For development or to get the latest changes:

# Global installation
mkdir -p ~/.config/opencode/plugin
cd ~/.config/opencode/plugin
git clone https://github.com/jgordijn/opencode-remote-config.git
cd opencode-remote-config
bun install && bun run build

Or for a project-specific installation:

mkdir -p .opencode/plugin
cd .opencode/plugin
git clone https://github.com/jgordijn/opencode-remote-config.git
cd opencode-remote-config
bun install && bun run build

Configuration

Create the configuration file (~/.config/opencode/remote-config.json or .opencode/remote-config.json):

{
  "repositories": [
    {
      "url": "git@github.com:company/shared-skills.git",
      "ref": "main",
      "skills": { "include": ["code-review", "kotlin-pro"] },
      "agents": { "include": ["code-reviewer", "specialized/db-expert"] },
      "plugins": { "include": ["notify", "utils-logger"] }
    },
    {
      "url": "git@github.com:team/team-skills.git",
      "ref": "v1.2.0"
    }
  ]
}

Restart OpenCode to load the plugin.

Configuration

The plugin reads its configuration from a separate JSON file (not opencode.json):

Location	Description
.opencode/remote-config.json	Project-level config (checked first)
~/.config/opencode/remote-config.json	Global config (fallback)

Configuration Options

Option	Type	Default	Description
installMethod	"link" or "copy"	"link"	How to install skills/plugins (symlinks or copies)
repositories	Array	[]	List of repositories to sync
repositories[].url	String	Required	Git URL, HTTPS URL, or file:// path
repositories[].ref	String	Default branch	Branch, tag, or commit SHA (git only)
repositories[].skills	"*" or { include: [...] } or { exclude: [...] }	All skills	Skills to import
repositories[].agents	"*" or { include: [...] } or { exclude: [...] }	All agents	Agents to import
repositories[].commands	"*" or { include: [...] } or { exclude: [...] }	All commands	Slash commands to import
repositories[].plugins	"*" or { include: [...] } or { exclude: [...] }	All plugins	Plugins to import
repositories[].instructions	"*" or { include: [...] } or { exclude: [...] }	All instructions	Instructions from manifest to import

Installation Method

By default, skills and plugins are installed using symlinks. This is fast and efficient but may not work in all environments.

Configuration

{
  "installMethod": "link"
}

Value	Description
link	Create symlinks (default). Fast, but may not work in containers or on Windows.
copy	Copy files. Works everywhere. Uses rsync if available for efficiency.

When to Use Copy Mode

Use "installMethod": "copy" when:

• Dev Containers: Symlinks break because paths differ between host and container
• Windows: Symlinks require admin privileges or developer mode
• Network filesystems: Some NFS/CIFS mounts don't support symlinks properly

Example

{
  "$schema": "https://raw.githubusercontent.com/jgordijn/opencode-remote-config/main/remote-skills.schema.json",
  "installMethod": "copy",
  "repositories": [
    {
      "url": "git@github.com:your-org/shared-skills.git"
    }
  ]
}

When using copy mode:

• rsync is preferred if available (efficient incremental updates)
• Falls back to Node.js file copy if rsync is unavailable
• Files are kept in sync with the source repository

Local Directories

For development or local skill repositories, use file:// URLs:

{
  "repositories": [
    {
      "url": "file:///path/to/my/local-skills"
    }
  ]
}

Benefits of file:// URLs:

• No cloning or caching - symlinks directly to the source directory
• Changes are immediately visible (great for development)
• Works with any local directory containing skill/, agent/, or plugin/ folders

How It Works

Skills are cloned to a cache directory and symlinked into the OpenCode skill directory:

~/.cache/opencode/remote-config/repos/
└── github.com-company-shared-skills/
    └── <full git clone>

~/.config/opencode/skill/
├── _plugins/                          # Plugin-managed (auto-gitignored)
│   └── shared-skills/
│       └── code-review -> ~/.cache/.../skill/code-review/
└── my-local-skill/                    # Your own skills (not touched)
    └── SKILL.md

Key points:

• Your local skills in ~/.config/opencode/skill/ are never modified
• Imported skills go into _plugins/ subdirectory
• _plugins/ is automatically added to .gitignore
• Local skills always take precedence over imported ones with the same name

Agents

Agents are discovered from agent/ or agents/ directories in repositories. Each agent is defined in a markdown file with YAML frontmatter:

---
description: A specialized code reviewer agent
mode: subagent
model: anthropic/claude-3-5-sonnet
temperature: 0.7
---

You are an expert code reviewer. Focus on...

Agent names are derived from the file path:

• agent/code-reviewer.md -> code-reviewer
• agent/specialized/db-expert.md -> specialized/db-expert

Agents are injected into OpenCode's config via the config hook with this priority:

1. User's local config - highest priority (defined in opencode.json)
2. First repository - first repo in the config list wins
3. Subsequent repositories - logged and skipped if name conflicts

Plugins

Plugins are OpenCode hook files (.ts or .js) discovered from plugin/ or plugins/ directories. They are symlinked to ~/.config/opencode/plugin/ using a flat naming convention.

Discovery rules:

• Scans plugin/ directory first; falls back to plugins/ if plugin/ doesn't exist
• Recursively discovers .ts and .js files (case-insensitive extensions)
• Skips hidden files/directories (starting with .)
• Maximum depth: 10 levels
• Maximum file size: 256KB

Plugin requirements:

• Files must be self-contained (no local imports like ./utils or ../helpers)
• Must export a valid OpenCode plugin hook
• Must have .ts or .js extension

Symlink naming: All remote plugins are symlinked with the _remote_ prefix to distinguish them from local plugins:

• plugin/notify.ts in repo my-hooks → _remote_my-hooks_notify.ts
• plugin/utils/logger.ts in repo shared → _remote_shared_utils-logger.ts

Nested paths are converted to dashes: plugin/foo/bar/baz.ts becomes foo-bar-baz.

Name collision handling: If two repos have plugins that result in the same symlink name, the first repository in your config wins. Subsequent duplicates are logged and skipped.

Why self-contained? OpenCode loads plugins as individual files. If your plugin imports ./helper.ts, that file won't be symlinked and the import will fail. Bundle your dependencies or use npm packages instead.

Plugin changes require restart: Unlike skills, plugins are loaded at OpenCode startup. When plugin changes are detected, you'll see:

[remote-config] Plugin changes detected. Restart OpenCode to apply.

Example Output

[remote-config] Syncing 2 repositories...
[remote-config] ✓ company/shared-skills (main) - 5 skills
[remote-config] ✓ team/team-skills (v1.2.0) - 3 skills
[remote-config] ⚠ Conflict: 'git-commit' exists locally, skipping
[remote-config] Discovered 4 remote agents
[remote-config] Discovered 2 remote plugins
[remote-config] 7 skills, 2 plugins available
[remote-config] Injected 4 remote agents into config

Authentication

The plugin uses your system's Git configuration for authentication:

• SSH keys: Ensure your SSH key is configured for the repository host
• HTTPS: Use credential helpers or tokens configured in Git

Requirements

• OpenCode v1.0.0 or later
• Bun runtime (used by OpenCode)
• Git installed and accessible in PATH

---

For OpenCode (LLM Agents)

This section contains instructions for LLM agents helping users set up the opencode-remote-config plugin.

Installation Steps

1. Check if the user has OpenCode installed:

   opencode --version

2. Install the plugin via npm:

   npm install -g @jgordijn/opencode-remote-config

   Then add to OpenCode config (~/.config/opencode/opencode.json):

   {
     "plugins": ["@jgordijn/opencode-remote-config"]
   }

   Alternative: Git clone installation

   mkdir -p ~/.config/opencode/plugin
   cd ~/.config/opencode/plugin
   git clone https://github.com/jgordijn/opencode-remote-config.git
   cd opencode-remote-config
   bun install && bun run build

3. Create the configuration file:

   Create ~/.config/opencode/remote-config.json:

   {
     "repositories": [
       {
         "url": "<git-url-from-user>",
         "ref": "<branch-or-tag-optional>"
       }
     ]
   }

4. Verify authentication:

   Test that the user can clone the repository:

   git ls-remote <git-url>

   If this fails, help them set up SSH keys or HTTPS credentials.

5. Restart OpenCode:

   The plugin will sync on next startup. Instruct the user to restart OpenCode.

Troubleshooting Guide

Problem: "Failed to clone" error

• Check Git authentication (SSH keys, tokens)
• Verify the URL is correct
• Ensure the user has access to the repository

Problem: Skills not appearing

• Verify the repository has a skill/ directory with SKILL.md files
• Check if there's a naming conflict with local skills
• Look for warnings in the startup output

Problem: Updates not reflected

• In background mode, restart OpenCode to apply updates
• Check that the ref (branch/tag) is correct
• Try removing the cached repo: rm -rf ~/.cache/opencode/remote-config/repos/<repo-id>

Repository Structure Requirements

For a repository to provide skills, agents, and/or plugins, use this structure:

<repo-root>/
├── skill/                          # Skills directory
│   ├── code-review/
│   │   └── SKILL.md
│   └── testing/
│       └── SKILL.md
├── agent/                          # Agents directory
│   ├── code-reviewer.md
│   └── specialized/
│       └── db-expert.md
└── plugin/                         # Plugins directory
    ├── notify.ts
    └── utils/
        └── logger.ts

Skill format - Each SKILL.md must have YAML frontmatter:

---
name: skill-name
description: Brief description of what this skill does
---

# Skill Content

Instructions and content for the skill...

Agent format - Each agent markdown file has YAML frontmatter:

---
description: When to use this agent
mode: subagent           # subagent | primary | all
model: anthropic/claude-3-5-sonnet
temperature: 0.7
color: "#FF5733"
---

You are an expert assistant. Your role is to...

Available agent configuration fields:

• description - When to use this agent (shown in agent list)
• mode - Agent mode: subagent, primary, or all
• model - Model to use (e.g., anthropic/claude-3-5-sonnet)
• temperature, top_p - Sampling parameters
• color - Hex color code (e.g., #FF5733)
• steps, maxSteps - Maximum agentic iterations
• tools - Tool enable/disable map (e.g., { bash: true, edit: false })
• permission - Permission rules for tools
• disable - Disable the agent

Plugin format - Each plugin file must be a self-contained TypeScript or JavaScript file:

// plugin/notify.ts
import type { Plugin } from "@opencode-ai/plugin"

export const NotifyPlugin: Plugin = async (ctx) => {
  return {
    event: async ({ event }) => {
      if (event.type === "session.completed") {
        // Send notification...
      }
    }
  }
}

export default NotifyPlugin

Important: Plugins must be self-contained. Do NOT use local imports:

// ❌ BAD - local import will fail
import { helper } from "./utils/helper"

// ✅ GOOD - npm package imports work
import { z } from "zod"

// ✅ GOOD - Node.js built-ins work
import * as fs from "fs"

Example Configurations

Single repository, all skills and agents:

{
  "repositories": [
    { "url": "git@github.com:company/skills.git" }
  ]
}

Multiple repositories, selective import:

{
  "repositories": [
    {
      "url": "git@github.com:company/shared-skills.git",
      "ref": "main",
      "skills": { "include": ["code-review", "testing"] },
      "agents": { "include": ["code-reviewer"] }
    },
    {
      "url": "git@github.com:team/team-skills.git",
      "ref": "v2.0.0",
      "agents": "*"  // Import all agents from this repo
    }
  ]
}

Skills only (exclude all agents):

{
  "repositories": [
    {
      "url": "git@github.com:company/skills.git",
      "agents": { "include": ["__none__"] }  // Include a non-existent name to import no agents
    }
  ]
}

Note: To effectively import nothing, include a name that doesn't exist in the repository. The include/exclude arrays require at least one item.

Exclude specific items:

{
  "repositories": [
    {
      "url": "git@github.com:company/skills.git",
      "skills": { "exclude": ["deprecated-skill", "experimental"] }
    }
  ]
}

With plugins:

{
  "repositories": [
    {
      "url": "git@github.com:company/shared-skills.git",
      "skills": "*",
      "agents": { "include": ["code-reviewer"] },
      "plugins": { "include": ["notify", "analytics"] }
    }
  ]
}

Uninstalling

To cleanly remove imported skills, agents, and plugins:

1. Remove repositories from config - Set repositories to empty array or remove the file:

   {
     "repositories": []
   }

2. Restart OpenCode - This triggers cleanup of stale symlinks

3. Remove the plugin (optional):

   If installed via npm:

   npm uninstall -g @jgordijn/opencode-remote-config

   Then remove from opencode.json:

   {
     "plugins": []
   }

   If installed via git clone (global):

   rm -rf ~/.config/opencode/plugin/opencode-remote-config

   If installed via git clone (project-local):

   rm -rf .opencode/plugin/opencode-remote-config

Important: Always empty the config and restart OpenCode first before removing the plugin. This ensures all symlinks are properly cleaned up.

If you skip this step, orphaned symlinks may remain:

• Skills: ~/.config/opencode/skill/_plugins/<repo-name>/
• Plugins: ~/.config/opencode/plugin/_remote_*

To manually clean up orphaned symlinks:

# Remove skill symlinks
rm -rf ~/.config/opencode/skill/_plugins

# Remove remote plugin symlinks
rm ~/.config/opencode/plugin/_remote_*

---

Development

Building

bun install
bun run build

Testing

bun test

Local Development

The plugin is loaded from the plugin/ directory:

# Build and the plugin will be available in ~/.config/opencode/plugin/opencode-remote-config/
bun run build

---

License

MIT