open-copilot-bridge

An OpenCode plugin that bridges GitHub Copilot Enterprise features into OpenCode -- bringing org instructions, custom agents, path-specific instructions, MCP server configs, prompt files, skills, and lifecycle hooks to the terminal.

Use your full Copilot Enterprise customization ecosystem without being tied to VS Code.

Features

• Instruction Injection -- Aggregates and injects organization, repository, and path-specific instructions into the system prompt. Path-specific instructions activate dynamically based on which files the LLM is working with.
• Agent Sync -- Fetches Copilot Enterprise custom agents from GitHub's API and maps them to OpenCode's agent format. Safely manages plugin-owned vs. user-created files.
• MCP Server Configs -- Extracts Model Context Protocol server configurations from Copilot agent profiles and writes them to OpenCode's global config.
• Prompt Files -- Discovers .prompt.md files from local, global, and remote sources. Supports argument substitution and file reference resolution.
• Skills -- Discovers SKILL.md files and exposes them via a copilot_skill tool.
• Local Agents -- Discovers .agent.md files with per-agent hook registries and tool restrictions.
• Lifecycle Hooks -- Supports preToolUse, postToolUse, sessionStart, sessionEnd, userPromptSubmitted, agentStop, and errorOccurred hooks with bash command execution.
• Code Review -- A copilot_review tool that performs code review using your org/repo instructions.
• Hot-Reload -- File watcher integration that re-discovers resources when source files change on disk.
• Graceful Degradation -- Works without GitHub authentication. Remote features are disabled but all local features remain active.

Installation

npm install open-copilot-bridge

Add the plugin to your opencode.json:

{
  "plugin": ["open-copilot-bridge"]
}

Or from a local path during development:

{
  "plugin": ["/path/to/open-copilot-bridge"]
}

Configuration

Configure the plugin via inline options in opencode.json:

{
  "plugin": [
    [
      "open-copilot-bridge",
      {
        "org": "my-org",
        "sync": {
          "on-startup": true,
          "cache-ttl": 3600
        }
      }
    ]
  ]
}

Or via a top-level copilot-bridge key:

{
  "plugin": ["open-copilot-bridge"],
  "copilot-bridge": {
    "org": "my-org",
    "sync": {
      "on-startup": true
    }
  }
}

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | org | string \| null | Auto-detected from git remote | GitHub organization login | | enterprise | string \| null | null | GitHub Enterprise slug | | github-private-repo | string | ".github-private" | Repo name containing org-level configs | | sync.agents | boolean | true | Sync enterprise custom agents | | sync.instructions | boolean | true | Sync org/repo/path-specific instructions | | sync.mcp | boolean | true | Sync MCP server configs from agent profiles | | sync.prompts | boolean | true | Sync prompt files | | sync.skills | boolean | true | Sync skill files | | sync.hooks | boolean | true | Sync hook configurations | | sync.on-startup | boolean | true | Auto-sync when plugin loads | | sync.cache-ttl | number | 3600 | Cache TTL in seconds for remote resources | | instructions.org-file | string | "org-instructions.md" | Filename in .github-private for org instructions | | instructions.org-text | string \| null | null | Inline org instructions text (fallback) |

Authentication

The plugin resolves a GitHub token using the same precedence as the Copilot CLI:

1. COPILOT_GITHUB_TOKEN environment variable
2. gh auth token (GitHub CLI)
3. GH_TOKEN environment variable
4. GITHUB_TOKEN environment variable

For GitHub Enterprise Server, set GH_HOST to your server hostname.

If no token is found, remote features (org instructions, enterprise agents, remote prompts/skills) are disabled. All local features continue to work.

Tools

The plugin registers the following tools in OpenCode:

| Tool | Description | | --- | --- | | copilot_sync | Manually trigger a sync of enterprise agents, instructions, and MCP configs. Pass force: true to bypass cache. | | copilot_review | Review code changes using your org/repo Copilot instructions. Accepts a diff, optional files, and focus. | | copilot_status | Show diagnostic report of all plugin subsystems: auth, config, agents, instructions, prompts, skills, hooks. | | copilot_prompt | List or run Copilot prompt files. Supports argument substitution. | | copilot_skill | Load a skill by name. Only registered when skills are discovered. | | copilot_agent | Load a local agent by name. Only registered when local agents are discovered. |

Resource Discovery

The plugin discovers resources from multiple tiers, in priority order:

1. Remote -- .github-private repo via GitHub API (org instructions, enterprise agents, remote prompts/skills)
2. Local project -- .github/ directory in the current repo
3. Global -- ~/.copilot/ directory
4. VS Code user data -- VS Code Copilot customization directories

Directory Structure

.github/
  copilot-instructions.md          # Repo-level instructions
  instructions/*.instructions.md   # Path-specific instructions (with applyTo frontmatter)
  prompts/*.prompt.md              # Prompt files (slash commands)
  skills/<name>/SKILL.md           # Skills
  agents/*.agent.md                # Local agents
  hooks/*.json                     # Lifecycle hooks

Path-Specific Instructions

Instructions with an applyTo glob pattern in their frontmatter activate dynamically based on which files the LLM is working with during the session:

---
applyTo: "**/*.ts"
---
Use strict TypeScript with explicit return types.

Prompt Files

Prompt files support argument substitution and file references:

---
description: "Generate unit tests"
---
Write unit tests for the following code:

#file:src/utils.ts

Use {{framework}} as the test framework.

Hooks

Define lifecycle hooks in .github/hooks/*.json:

{
  "version": 1,
  "hooks": [
    {
      "event": "preToolUse",
      "tools": ["bash"],
      "steps": [
        {
          "command": "echo 'Tool execution requested'",
          "response": "ask"
        }
      ]
    }
  ]
}

preToolUse hooks can return allow, deny, or ask to control tool execution.

Where Resources Are Written

| Resource | Location | | --- | --- | | Synced agents | ~/.config/opencode/agents/copilot-bridge--*.md | | MCP configs | ~/.config/opencode/opencode.json (prefixed copilot-bridge/) | | Command stubs | ~/.config/opencode/commands/ | | Cache | ~/.cache/open-copilot-bridge/ |

Plugin-managed files are prefixed with copilot-bridge-- or copilot-bridge/ and include metadata comments. The plugin never overwrites user-created files.

Development

Prerequisites

• Bun runtime
• Node.js (for TypeScript tooling)

Setup

bun install

Type Check

bun run typecheck

Run Tests

bun test

Local Development

Point your opencode.json to the local plugin directory:

{
  "plugin": ["/path/to/open-copilot-bridge"]
}

The plugin supports hot-reload for instructions, agents, prompts, and skills during development. Hooks require a restart.

Tech Stack

• TypeScript -- Strict mode, ESM
• Bun -- Runtime and test runner
• @opencode-ai/plugin -- OpenCode plugin SDK
• picomatch -- Glob pattern matching for path-specific instructions
• yaml -- YAML frontmatter parsing

License

MIT