Candela | Blog

Building an OpenCode Plugin from Scratch — Hooks, Tools, and the AI Event Loop

Sun, 09 Aug 2026 00:00:00 GMT

OpenCode is an open-source AI coding agent that runs in your terminal. It has a plugin SDK that lets you hook into the AI lifecycle — intercept requests, inject context, define custom tools, and listen to session events.

I built an OpenCode plugin for Candela (an LLM cost tracking proxy). This post walks through the SDK patterns I used, with real code from the open-source plugin.

The Plugin Contract

An OpenCode plugin is a function that receives a context object and returns hooks:

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

export const myPlugin: Plugin = async ({ client, $, directory }) => {
  // client — log messages, read/write config
  // $ — Bun shell for subprocess execution
  // directory — current working directory

  return {
    // hooks go here
  };
};

The PluginInput gives you:

client — OpenCode’s API client (logging, config read/write)
$ — Bun shell for running commands
directory / worktree — filesystem context
serverUrl — OpenCode’s server URL

What you return is a Hooks object. This is where the interesting stuff happens.

Hook #1: Custom Tools

The most powerful hook. You define tools that the AI agent can call conversationally — the user says “how much have I spent today?” and the AI calls your tool to find out.

import { tool } from "@opencode-ai/plugin";

const costSummary = tool({
  description: "Get a summary of LLM costs for the current session or time period",
  args: {
    scope: tool.schema
      .enum(["session", "1h", "24h", "7d"])
      .default("24h")
      .describe("Time scope for the cost query"),
    model_filter: tool.schema
      .string()
      .optional()
      .describe("Filter results to a specific model"),
  },
  async execute(args, context) {
    // context gives you: sessionID, messageID, abort signal, directory
    const data = await fetchCostData(args.scope);
    return `You've spent ${data.totalCost} across ${data.requestCount} requests.`;
  },
});

Key details:

tool.schema is built on Zod — you get type-safe argument parsing
.describe() annotations help the LLM choose the right arguments
The return value is a string that goes back into the AI’s context
context.abort gives you an AbortSignal for cancellation

To register tools, return them from your plugin:

return {
  tool: {
    my_cost_tool: costSummary,
    my_config_tool: configTool,
  },
};

The AI discovers these tools automatically and can call them when relevant.

Hook #2: Events

OpenCode emits lifecycle events. You listen with the event hook:

return {
  event: async ({ event }) => {
    if (event.type === "session.created") {
      // A new chat session started
      // Good for: capturing baseline metrics, resetting state
    }

    if (event.type === "session.idle") {
      // The AI finished responding, waiting for user input
      // Good for: showing summaries, logging analytics
    }

    if (event.type === "file.watcher.updated") {
      // A file in the project changed
      const filePath = event.properties?.file;
    }

    if (event.type === "todo.updated") {
      // A task/subtask was created or completed
      const { id, title, active } = event.properties;
    }
  },
};

In the Candela plugin, I use session.created to capture a baseline of spend metrics, and session.idle to compute the delta — giving you exact per-session costs without any server-side session indexing.

Hook #3: System Prompt Injection

This is the hook that makes AI tools “cost-aware.” You can dynamically inject context into the system prompt:

return {
  "experimental.chat.system.transform": async (input, output) => {
    const budget = await getBudgetStatus();

    output.system.push(
      `[Cost Context] Budget: ${budget.percentUsed}% used. ` +
      `Remaining: $${budget.remaining}. ` +
      `Resets in ${budget.resetLabel}.`
    );
  },
};

Now when the user asks “am I over budget?”, the AI already knows — it’s in the system prompt.

Design decision I learned the hard way: Don’t inject on every message. System prompt tokens add up. In Candela, I only inject on the first prompt of each session when budget is healthy (<80%). When budget hits ≥80%, I inject on every prompt so the AI can proactively warn the user.

Hook #4: Request Headers

You can attach custom headers to every LLM API request:

return {
  "chat.headers": (input, output) => {
    if (sessionId) {
      output.headers["X-Session-Id"] = sessionId;
    }
    if (activeTaskId) {
      output.headers["X-Task-Id"] = activeTaskId;
    }
  },
};

This is how Candela traces requests back to specific sessions and tasks — the proxy reads these headers and includes them in the cost log.

Hook #5: Shell Environment

Inject environment variables into every subprocess OpenCode runs:

return {
  "shell.env": (input, output) => {
    output.env["CANDELA_PROXY_URL"] = "http://localhost:8181";
    output.env["OPENAI_BASE_URL"] = "http://localhost:8181/proxy/openai/v1";
  },
};

This means when the AI runs a test suite or a build script, those subprocesses automatically route through the proxy too. Transparent instrumentation.

Hook #6: TUI (Slash Commands)

OpenCode plugins can also export a TUI module for terminal UI features:

import type { TuiPlugin } from "@opencode-ai/plugin/tui";

export const tui: TuiPlugin = async (api) => {
  api.command.register(() => [
    {
      title: "Candela: Cost Summary",
      value: "candela.cost",
      slash: { name: "cost", aliases: ["spend"] },
      onSelect: async () => {
        const data = await fetchCosts();
        api.ui.toast({
          title: "💰 Cost Summary",
          message: `Today: $${data.today} · This week: $${data.week}`,
          variant: "info",
        });
      },
    },
  ]);
};

Slash commands show up when users type / in the chat. Toasts are non-blocking notifications.

Architecture note: OpenCode separates server hooks and TUI hooks into different execution contexts. Your package.json exports both from the same package, but they run on different threads.

Putting It Together

Here’s the minimal skeleton of a real plugin:

src/index.ts

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

export const server: Plugin = async ({ client }) => {
  const alive = await checkMyService();

  if (!alive) {
    await client.app.log({
      body: {
        service: "my-plugin",
        level: "warn",
        message: "Service not running. Start it with: my-service start",
      },
    });
  }

  return {
    tool: alive ? {
      my_tool: tool({
        description: "Query my service",
        args: { query: tool.schema.string() },
        async execute(args) {
          return await queryService(args.query);
        },
      }),
    } : {},

    event: async ({ event }) => {
      if (event.type === "session.created") {
        // setup
      }
      if (event.type === "session.idle") {
        // teardown / summary
      }
    },
  };
};

// Re-export TUI
export { tui } from "./tui.js";

Install with:

opencode plugin my-plugin-name

What I’d Do Differently

Start with one tool, not seven. I built 10 tools before any user tried the plugin. Consolidated to 7 after realizing the AI gets confused with too many similar options.
Test with fake timers. Every time-dependent feature (cache TTL, session duration, budget resets) needs vi.useFakeTimers() in tests. I learned this after flaky CI runs.
Graceful degradation matters. When the external service is down, the plugin should still load — just with reduced functionality. Returning undefined for hooks is fine.

Resources

OpenCode — the AI coding agent
@opencode-ai/plugin — the SDK
opencode-candela — the full plugin source (MIT)
Candela docs — the observability platform

Building an OpenCode plugin? I’d love to see what you make. Drop a link in the comments.

The AI Cost Problem Nobody's Tracking

Sun, 09 Aug 2026 00:00:00 GMT

Open Claude Code. Open Cursor. Open Windsurf. Open Copilot.

Now tell me: how much did your last coding session cost?

You can’t. None of them show you.

The Visibility Gap

AI coding tools have a strange relationship with money. They charge you — sometimes per-seat, sometimes per-token, sometimes through your API key — but they never show you what individual sessions, requests, or tasks actually cost.

Here’s what the pricing pages tell you:

Model	Input (per 1M tokens)	Output (per 1M tokens)
Claude Sonnet 4	$3.00	$15.00
GPT-4.1	$2.00	$8.00
Gemini 2.5 Pro	$1.25	$10.00

Here’s what they don’t tell you: how many tokens a typical coding session actually uses. A file read is ~1K tokens. A grep across a codebase is ~5K. A 10-round debug loop with full context replay can hit 200K+. You’re multiplying these prices by numbers you can’t see.

The result: monthly invoices that are either a relief or a surprise, with no way to understand what drove them.

Why This Matters

For solo developers, it’s an annoyance. For teams, it’s a budget problem.

Consider:

No per-session attribution. You can’t tell which task or feature drove a cost spike.
No per-user visibility. Engineering managers see a total bill, not per-engineer spend.
No budget enforcement. There’s no way to set a daily limit and have the tool respect it.
No model efficiency data. Are you using Opus for tasks where Haiku would suffice? You’ll never know.

Cloud computing went through this exact phase. Early AWS bills were a mystery. Then tools like CloudWatch, Cost Explorer, and third-party observability platforms matured. Teams got visibility, set budgets, and optimized.

LLM spend is where cloud spend was in 2010. The tools don’t exist yet.

Building the Missing Layer

That’s why we’re building Candela — an open-source LLM observability proxy.

The idea is simple: Candela sits between your AI tool and your LLM provider. Every request passes through, gets logged with cost/latency/token data, and continues to its destination. No code changes, no SDK integration, no vendor lock-in.

AI Tool  →  Candela Proxy  →  LLM Provider
                 ↓
          Cost per request
          Token counts
          Cache hit rates
          Model breakdown
          Budget enforcement

It works with anything that speaks the OpenAI-compatible API format — which is most AI coding tools today.

What You Get

Per-request cost tracking. Every API call is logged with input tokens, output tokens, model, latency, and computed cost. Not estimated — computed from the actual token counts × the model’s pricing.

Budget enforcement. Set a daily spending limit. When you hit it, Candela can warn you or block requests. No more surprise invoices.

Model analytics. See which models you’re using, how often, and what they cost. Spot the $15/day Claude Opus habit when Sonnet would work.

Cache monitoring. Prompt caching can cut costs 50-90% — but only if you know your hit rate. Candela tracks cache read/write tokens per request.

The OpenCode Plugin

We built a plugin that surfaces Candela data directly in OpenCode:

opencode plugin @candelahq/opencode

It gives you 7 AI tools (so you can ask “how much have I spent today?” in natural language) and 13 slash commands (/cost, /budget, /export, etc.).

The plugin is open source: @candelahq/opencode on npm.

Get Involved

If you’re using AI coding tools professionally, you should know what they cost. Candela is early, open source, and free.

⭐ Star the repo
📖 Read the docs
💬 Open an issue if you want support for your tool/workflow