प्लगइन

OpenCode का विस्तार करने के लिए अपने स्वयं के प्लगइन लिखें।

प्लगइन आपको विभिन्न घटनाओं में हुक करके और व्यवहार को कस्टमाइज़ करके OpenCode का विस्तार करने देते हैं। आप नई सुविधाएँ जोड़ने, बाहरी सेवाओं के साथ एकीकृत करने, या OpenCode के डिफ़ॉल्ट व्यवहार को संशोधित करने के लिए प्लगइन बना सकते हैं।

उदाहरणों के लिए, कम्युनिटी द्वारा बनाए गए plugins देखें।

एक प्लगइन का उपयोग करें

प्लगइन लोड करने के दो तरीके हैं।

स्थानीय फ़ाइलों से

JavaScript या TypeScript फ़ाइलों को प्लगइन डायरेक्टरी में रखें।

.opencode/plugins/ - प्रोजेक्ट-स्तर के प्लगइन
~/.config/opencode/plugins/ - ग्लोबल प्लगइन

इन डायरेक्टरी की फ़ाइलें स्टार्टअप पर स्वचालित रूप से लोड हो जाती हैं।

npm से

अपनी कॉन्फ़िग फ़ाइल में npm पैकेज निर्दिष्ट करें।

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

नियमित और scoped दोनों npm पैकेज समर्थित हैं।

ecosystem में उपलब्ध प्लगइन ब्राउज़ करें।

प्लगइन कैसे इंस्टॉल होते हैं

npm प्लगइन स्टार्टअप पर Bun का उपयोग करके स्वचालित रूप से इंस्टॉल होते हैं। पैकेज और उनकी निर्भरताएँ ~/.cache/opencode/node_modules/ में कैश की जाती हैं।

स्थानीय प्लगइन सीधे प्लगइन डायरेक्टरी से लोड होते हैं। बाहरी पैकेज का उपयोग करने के लिए, आपको अपनी कॉन्फ़िग डायरेक्टरी के भीतर एक package.json बनाना होगा (Dependencies देखें), या प्लगइन को npm पर प्रकाशित करना होगा और इसे अपनी कॉन्फ़िग में जोड़ना होगा।

लोड क्रम

प्लगइन सभी स्रोतों से लोड होते हैं और सभी हुक क्रम में चलते हैं। लोड क्रम है:

ग्लोबल कॉन्फ़िग (~/.config/opencode/opencode.json)
प्रोजेक्ट कॉन्फ़िग (opencode.json)
ग्लोबल प्लगइन डायरेक्टरी (~/.config/opencode/plugins/)
प्रोजेक्ट प्लगइन डायरेक्टरी (.opencode/plugins/)

समान नाम और संस्करण वाले डुप्लिकेट npm पैकेज एक बार लोड होते हैं। हालाँकि, समान नामों वाले एक स्थानीय प्लगइन और एक npm प्लगइन दोनों अलग-अलग लोड होते हैं।

एक प्लगइन बनाएँ

एक प्लगइन एक JavaScript/TypeScript मॉड्यूल है जो एक या अधिक प्लगइन फ़ंक्शन एक्सपोर्ट करता है। प्रत्येक फ़ंक्शन एक context ऑब्जेक्ट प्राप्त करता है और एक hooks ऑब्जेक्ट लौटाता है।

निर्भरताएँ

स्थानीय प्लगइन और कस्टम टूल बाहरी npm पैकेज का उपयोग कर सकते हैं। अपनी आवश्यक निर्भरताओं के साथ अपनी कॉन्फ़िग डायरेक्टरी में एक package.json जोड़ें।

.opencode/package.json

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

OpenCode इन्हें इंस्टॉल करने के लिए स्टार्टअप पर bun install चलाता है। आपके प्लगइन और टूल तब उन्हें इम्पोर्ट कर सकते हैं।

.opencode/plugins/my-plugin.ts

import { escape } from "shescape"
 
export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

मूल संरचना

.opencode/plugins/example.js

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
 
  return {
    // Hook implementations go here
  }
}

प्लगइन फ़ंक्शन प्राप्त करता है:

project : वर्तमान प्रोजेक्ट जानकारी।
directory : वर्तमान कार्यशील डायरेक्टरी।
worktree : git worktree पथ।
client : AI के साथ इंटरैक्ट करने के लिए एक opencode SDK क्लाइंट।
$ : कमांड निष्पादित करने के लिए Bun का shell API (opens in a new tab)।

TypeScript सपोर्ट

TypeScript प्लगइन के लिए, आप प्लगइन पैकेज से टाइप इम्पोर्ट कर सकते हैं:

my-plugin.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

घटनाएँ

प्लगइन घटनाओं की सदस्यता ले सकते हैं जैसा कि नीचे उदाहरण अनुभाग में देखा गया है। यहाँ उपलब्ध विभिन्न घटनाओं की सूची दी गई है।

Command घटनाएँ

command.executed

File घटनाएँ

file.edited
file.watcher.updated

Installation घटनाएँ

installation.updated

LSP घटनाएँ

lsp.client.diagnostics
lsp.updated

Message घटनाएँ

message.part.removed
message.part.updated
message.removed
message.updated

Permission घटनाएँ

permission.asked
permission.replied

Server घटनाएँ

server.connected

Session घटनाएँ

session.created
session.compacted
session.deleted
session.diff
session.error
session.idle
session.status
session.updated

Todo घटनाएँ

todo.updated

Shell घटनाएँ

shell.env

Tool घटनाएँ

tool.execute.after
tool.execute.before

TUI घटनाएँ

tui.prompt.append
tui.command.execute
tui.toast.show

उदाहरण

यहाँ कुछ प्लगइन के उदाहरण दिए गए हैं जिनका उपयोग आप opencode का विस्तार करने के लिए कर सकते हैं।

सूचनाएँ भेजें

कुछ घटनाओं के घटित होने पर सूचनाएँ भेजें:

.opencode/plugins/notification.js

export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
      }
    },
  }
}

हम macOS पर AppleScript चलाने के लिए osascript का उपयोग कर रहे हैं। यहाँ हम इसका उपयोग सूचनाएँ भेजने के लिए कर रहे हैं।

Note: यदि आप OpenCode डेस्कटॉप ऐप का उपयोग कर रहे हैं, तो यह प्रतिक्रिया तैयार होने पर या सत्र में त्रुटि होने पर स्वचालित रूप से सिस्टम सूचनाएँ भेज सकता है।

.env सुरक्षा

opencode को .env फ़ाइलें पढ़ने से रोकें:

.opencode/plugins/env-protection.js

export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

एनवायरनमेंट वेरिएबल इंजेक्ट करें

सभी शेल निष्पादन (AI टूल और उपयोगकर्ता टर्मिनल) में एनवायरनमेंट वेरिएबल इंजेक्ट करें:

.opencode/plugins/inject-env.js

export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

कस्टम टूल

प्लगइन opencode में कस्टम टूल भी जोड़ सकते हैं:

.opencode/plugins/custom-tools.ts

import { type Plugin, tool } from "@opencode-ai/plugin"
 
export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

tool हेल्पर एक कस्टम टूल बनाता है जिसे opencode कॉल कर सकता है। यह एक Zod schema फ़ंक्शन लेता है और निम्नलिखित के साथ एक टूल परिभाषा लौटाता है:

description : टूल क्या करता है
args : टूल के तर्कों के लिए Zod schema
execute : फ़ंक्शन जो टूल कॉल होने पर चलता है

आपके कस्टम टूल बिल्ट-इन टूल के साथ-साथ opencode के लिए उपलब्ध होंगे।

Note: यदि कोई प्लगइन टूल बिल्ट-इन टूल के समान नाम का उपयोग करता है, तो प्लगइन टूल को प्राथमिकता मिलती है।

लॉगिंग

संरचित लॉगिंग के लिए console.log के बजाय client.app.log() का उपयोग करें:

.opencode/plugins/my-plugin.ts

export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

स्तर: debug, info, warn, error। विवरण के लिए SDK documentation (opens in a new tab) देखें।

Compaction हुक

सत्र के compact होने पर शामिल किए गए संदर्भ को कस्टमाइज़ करें:

.opencode/plugins/compaction.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`
## Custom Context
 
Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

experimental.session.compacting हुक LLM द्वारा एक continuation सारांश उत्पन्न करने से पहले फ़ायर होता है। इसका उपयोग डोमेन-विशिष्ट संदर्भ इंजेक्ट करने के लिए करें जिसे डिफ़ॉल्ट compaction प्रॉम्प्ट चूक जाएगा।

आप output.prompt सेट करके compaction प्रॉम्प्ट को पूरी तरह से बदल भी सकते हैं:

.opencode/plugins/custom-compaction.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Replace the entire compaction prompt
      output.prompt = `
You are generating a continuation prompt for a multi-agent swarm session.
 
Summarize:
1. The current task and its status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work
 
Format as a structured prompt that a new agent can use to resume work.
`
    },
  }
}

जब output.prompt सेट होता है, तो यह डिफ़ॉल्ट compaction प्रॉम्प्ट को पूरी तरह से बदल देता है। इस मामले में output.context array को अनदेखा कर दिया जाता है।

सर्वर इकोसिस्टम