Eklentiler

opencode'u genişletmek için kendi eklentilerinizi yazın.

Eklentiler, çeşitli olaylara bağlanarak ve davranışı özelleştirerek opencode’u genişletmenize olanak tanır. Yeni özellikler eklemek, harici hizmetlerle entegrasyon sağlamak veya opencode’un varsayılan davranışını değiştirmek için eklentiler oluşturabilirsiniz.

Örnekler için topluluk tarafından oluşturulan plugins’a göz atın.

Bir eklenti kullanın

There are two ways to load plugins.

Yerel dosyalardan

JavaScript veya TypeScript dosyalarını eklenti dizinine yerleştirin.

.opencode/plugins/ - Proje düzeyinde eklentiler
~/.config/opencode/plugins/ - Genel eklentiler

Bu dizinlerdeki dosyalar başlangıçta otomatik olarak yüklenir.

npm’den

Yapılandırma dosyanızda npm paketlerini belirtin.

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

Hem normal hem de kapsamlı npm paketleri desteklenir.

ecosystem’daki mevcut eklentilere göz atın.

Eklentiler nasıl kurulur?

npm eklentileri başlangıçta Bun kullanılarak otomatik olarak yüklenir. Paketler ve bağımlılıkları ~/.cache/opencode/node_modules/’da önbelleğe alınır.

Yerel eklentiler doğrudan eklenti dizininden yüklenir. Harici paketleri kullanmak için, sisteminizin dizininde bir package.json oluşturmanız (bkz. Dependencies) veya eklentiyi npm ve add it to your config’de yayınlamanız gerekir.

Load order

Eklentiler tüm kaynaklardan yüklenir ve tüm kancalar sırayla çalışır. Yükleme sırası şöyledir:

Global config (~/.config/opencode/opencode.json)
Project config (opencode.json)
Global eklenti dizini (~/.config/opencode/plugins/)
Proje eklenti dizini (.opencode/plugins/)

Aynı ad ve sürüme sahip yinelenen npm paketleri bir kez yüklenir. Ancak benzer adlara sahip bir yerel eklenti ve bir npm eklentisinin her ikisi de ayrı ayrı yüklenir.

Eklenti oluştur

Eklenti, bir veya daha fazla eklentiyi dışa aktaran bir JavaScript/TypeScript modülüdür işlevler. Her işlev bir bağlam nesnesi alır ve bir kanca nesnesi döndürür.

Dependencies

Yerel eklentiler ve özel araçlar harici npm paketlerini kullanabilir. İhtiyacınız olan bağımlılıkları içeren config dizininize bir package.json ekleyin.

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

opencode bunları yüklemek için başlangıçta bun install komutunu çalıştırır. Eklentileriniz ve araçlarınız daha sonra bunları içe aktarabilir.

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)
      }
    },
  }
}

Temel yapı

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")

  return {
    // Hook implementations go here
  }
}

Eklenti işlevi şunları alır:

project: Mevcut proje bilgisi.
directory: güncel çalışma dizini.
worktree: Git çalışma ağacı yolu.
client: Yapay zeka ile etkileşime geçmek için opencode’lu bir SDK istemcisi.
$: Bun’un komutları yürütmek için kullandığı shell API.

TypeScript desteği

TypeScript eklentileri için türleri eklenti paketinden içe aktarabilirsiniz:

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

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

Olaylar

Eklentiler aşağıdaki Örnekler bölümünde görüldüğü gibi etkinliklere abone olabilirler. Burada mevcut farklı etkinliklerin bir listesi bulunmaktadır.

Komut Olayları

command.executed

Dosya Olayları

file.edited
file.watcher.updated

Kurulum Etkinlikleri

installation.updated

LSP Etkinlikler

lsp.client.diagnostics
lsp.updated

Mesaj Etkinlikleri

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

İzin Etkinlikleri

permission.asked
permission.replied

Sunucu Etkinlikleri

server.connected

Oturum Etkinlikleri

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

Yapılacak Etkinlikler

todo.updated

Kabuk Etkinlikleri

shell.env

Araç Olayları

tool.execute.after
tool.execute.before

TUI Etkinlikler

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

Examples

opencode’u genişletmek için kullanabileceğiniz bazı eklenti örneklerini burada bulabilirsiniz.

Bildirim gönder

Belirli olaylar meydana geldiğinde bildirim gönderin:

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’ta AppleScript’i çalıştırmak için osascript kullanıyoruz. Burada bildirim göndermek için kullanıyoruz.

.env protection

opencode’un .env dosyalarını okumasını önleyin:

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")
      }
    },
  }
}

Ortam değişkenlerini enjekte etme

Ortam değişkenlerini tüm kabuk yürütmeye (AI araçları ve kullanıcı terminalleri) enjekte edin:

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

Custom tools

Eklentiler ayrıca opencode’a özel araçlar da ekleyebilir:

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 yardımcısı, opencode’un çağırabileceği özel bir araç oluşturur. Bir Zod şeması işlevini alır ve aşağıdakileri içeren bir araç tanımı döndürür:

description: Araç ne yapar?
args: Aracın argümanları için Zod şeması
execute: Araç çağrıldığında çalışan fonksiyon

Özel araçlarınız, yerleşik araçların yanı sıra kod açmaya da hazır olacaktır.

Günlüğe kaydetme

Yapılandırılmış günlük kaydı için client.app.log() yerine console.log kullanın:

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

Seviyeler: debug, info, warn, error. Ayrıntılar için SDK documentation’e bakın.

Compaction hooks

Bir oturum sıkıştırıldığında içerilen bağlamı özelleştirin:

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 kancası, LLM bir devam özeti oluşturmadan önce tetiklenir. Varsayılan sıkıştırma isteminin kaçıracağı etki alanına özgü bağlamı enjekte etmek için bunu kullanın.

Ayrıca output.prompt ayarını yaparak sıkıştırma istemini tamamen değiştirebilirsiniz:

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 ayarlandığında, varsayılan sıkıştırma isteminin tamamen yerini alır. Bu durumda output.context dizisi dikkate alınmaz.