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 eklentilere göz atın.

Eklenti kullanımı

Eklentileri yüklemenin iki yolu vardır.

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.

Ekosistem’deki 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. Bağımlılıklar) veya eklentiyi npm ve add it to your config’de yayınlamanız gerekir.

Yükleme sırası

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şturma

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.

Bağımlılıklar

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 Olayları

installation.updated

LSP Olayları

lsp.client.diagnostics
lsp.updated

Mesaj Olayları

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

İzin Olayları

permission.asked
permission.replied

Sunucu Olayları

server.connected

Oturum Olayları

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

Yapılacaklar Olayları

todo.updated

Kabuk Olayları

shell.env

Araç Olayları

tool.execute.after
tool.execute.before

TUI Olayları

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

Örnekler

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

Bildirim Gönderme

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 Koruması

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

Özel araçlar

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.

Sıkıştırma kancaları

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.