OpenCode Plugin: OpenAI Instructions Injector

An OpenCode plugin that ensures instructions are always injected for the OpenAI provider, regardless of authentication type.

Problem

In OpenCode's packages/opencode/src/session/llm.ts, there's a conditional that only sets options.instructions when:

const isOpenaiOauth = provider.id === "openai" && auth?.type === "oauth"

if (isOpenaiOauth) {
  options.instructions = system.join("\n")
}

The Issue: When using OpenAI with API key authentication (not OAuth), isOpenaiOauth is false, so options.instructions is never set. This causes your agent to not receive system instructions properly.

Solution

This plugin hooks into OpenCode's plugin system and injects options.instructions for all OpenAI requests, regardless of auth type.

Installation

Option 1: Via npm (Recommended)

# Install globally
npm install -g @angdrew/opencode-openai-instructions

# Or install locally in your project
npm install @angdrew/opencode-openai-instructions

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

{
  "plugins": [
    "@angdrew/opencode-openai-instructions"
  ]
}

Option 2: Manual Installation

1. Build the plugin:

cd openai-instructions-injector
npm install
npm run build

2. Copy the plugin to your OpenCode plugins directory:

# On macOS/Linux
cp -r dist ~/.config/opencode/plugins/@angdrew/opencode-openai-instructions

# On Windows (PowerShell)
Copy-Item -Recurse -Path dist -Destination "$env:USERPROFILE\.config\opencode\plugins\@angdrew\opencode-openai-instructions"

3. Enable the plugin in your OpenCode config:

{
  "plugins": [
    "@angdrew/opencode-openai-instructions"
  ]
}

How It Works

The plugin uses two hooks:

1. experimental.chat.system.transform: Captures the system prompt array as it's being built by OpenCode

2. chat.params: When the provider is OpenAI, injects the cached system prompt into data.options.instructions

This ensures that OpenAI always receives instructions, regardless of whether you're using OAuth or API key authentication.

Compatibility

• OpenCode: >= 0.1.0
• OpenAI Models: GPT-4, GPT-4o, GPT-3.5-turbo, etc.
• Auth Types: OAuth, API Key, Custom endpoints
• Node.js: >= 18.0.0

Plugin Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT - See LICENSE for details.

Related

• OpenCode - The AI editor
• OpenCode Plugins - Plugin documentation