T TelemHQ

OpenCode

Track OpenCode With Plugins

OpenCode is an open-source local coding agentagentAn AI application that uses a model, instructions, state, and tools to work toward a goal. Agents are useful to monitor because they can run for a while and make multiple tool calls.View glossary entrySource: Google Cloud Generative AI glossary, not an APIAPIA software interface that lets programs interact through defined rules, URLs, methods, and data formats.View glossary entrySource: MDN API glossary. Track it by adding an OpenCode plugin that sends TelemHQ metadatametadataData about a run rather than the private content of the run itself, such as model name, duration, branch, item counts, or token totals.View glossary entrySource: MDN API glossary when sessionssessionServer-side or cookie-backed state that remembers a signed-in user between requests.View glossary entrySource: MDN glossary go idle or fail.

When To Use This

Use the OpenCode plugin setup when you want to understand local coding-agent activity across projects or teams: how often sessions run, which projects they touch, and where failures happen.

Create an ad hocad hoc jobA task that runs whenever needed instead of on a fixed schedule. TelemHQ records each run but does not fail the tracker just because no scheduled ping arrived.View glossary entrySource: AWS EventBridge Scheduler docs trackertrackerA monitored job, AI pipeline, worker, script, or automation in TelemHQ. Each tracker has its own ping URL and run history.View glossary entrySource: TelemHQ docs with no schedule for normal OpenCode usage. Add a schedule only if the plugin runs from a predictable automation, such as a nightly OpenCode job.

1. Save Your PingpingA request sent to TelemHQ after a job runs. A ping can be a simple heartbeat or include JSON payload data about what happened.View glossary entrySource: TelemHQ docs URL

Copy the ping URL from a TelemHQ tracker and make it available to the OpenCode process. 

mkdir -p ~/.config/opencode/plugins
export TELEMHQ_OPENCODE_PING_URL="https://telemhq.com/ping/YOUR_TRACKING_TOKEN"

If OpenCode starts outside this shell, put the environment variable in the shell profile or process manager that launches OpenCode.

2. Add The Plugin

Save this as ~/.config/opencode/plugins/telemhq.js to track every project, or as .opencode/plugins/telemhq.js inside one repo to track a single project. It listens for session.idle and session.error events and sends metadata only: tool name, status, event name, project, session id, and a hashed directory. It does not send prompts, commands, file contents, or modelmodelThe AI system that processes input and returns output. For monitoring, the model name helps explain which tool or provider produced a run and how its token usage should be priced.View glossary entrySource: Anthropic model docs output. 

import { createHash } from "node:crypto";

export const TelemHQPlugin = async ({ directory }) => {
  const pingUrl = process.env.TELEMHQ_OPENCODE_PING_URL;
  const project = directory ? directory.split("/").pop() : undefined;

  const shortHash = (value) => {
    if (!value) return undefined;
    return createHash("sha256").update(value).digest("hex").slice(0, 12);
  };

  const sendPing = async (payload) => {
    if (!pingUrl) return;
    const body = {};
    for (const [key, value] of Object.entries(payload)) {
      if (value !== undefined) body[key] = value;
    }
    try {
      const res = await fetch(pingUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
      });
      if (!res.ok) throw new Error(`TelemHQ returned HTTP ${res.status}`);
    } catch (err) {
      if (process.env.TELEMHQ_HOOK_DEBUG === "1") console.error(`TelemHQ ping skipped: ${err}`);
    }
  };

  return {
    event: async ({ event }) => {
      if (event.type === "session.idle") {
        await sendPing({
          tool: "opencode",
          status: "success",
          event: "session.idle",
          project: project || "unknown",
          session_id: event.properties ? event.properties.sessionID : undefined,
          directory_hash: shortHash(directory),
          timestamp: new Date().toISOString(),
        });
      }
      if (event.type === "session.error") {
        await sendPing({
          tool: "opencode",
          status: "failed",
          event: "session.error",
          project: project || "unknown",
          session_id: event.properties ? event.properties.sessionID : undefined,
          directory_hash: shortHash(directory),
          timestamp: new Date().toISOString(),
        });
      }
    },
  };
};

OpenCode loads plugins automatically at startup, so no config change is needed. A missing ping URL silently skips sending, so the plugin never breaks your sessions.

3. Verify It Works

Restart OpenCode so it picks up the new plugin, complete one task, then open the tracker in TelemHQ and check Ping Historyrun historyThe stored record of previous job runs. TelemHQ uses run history to show payloads, failures, timing, token totals, and trends over time.View glossary entrySource: TelemHQ docs. You should see a payloadpayloadThe structured data sent with a request. In TelemHQ, payloads should contain safe operational metadata, not prompts, completions, secrets, customer data, or private paths.View glossary entrySource: MDN API glossary like this: 

{
  "tool": "opencode",
  "status": "success",
  "event": "session.idle",
  "project": "api",
  "session_id": "ses_abc123",
  "directory_hash": "d7a8fbb307d7",
  "timestamp": "2026-09-27T12:00:00.000Z"
}

OpenCode session events do not expose exact tokentokensThe pieces of text an AI model processes. Token counts are often used to measure usage and calculate model cost.View glossary entrySource: OpenAI token guide and costcostThe money associated with a run, often estimated from token usage and provider pricing. TelemHQ can store cost fields when your job sends them.View glossary entrySource: OpenAI token guide totals. For exact API usage, add token fields from your own wrapper when available.

Privacy And Troubleshooting

The plugin sends usage metadata only. It does not send prompts, generated code, command arguments, file contents, model output, or raw local directory paths.

If no pings arrive, set TELEMHQ_HOOK_DEBUG="1" in the environment that launches OpenCode and watch its output for TelemHQ ping skipped messages.

Official reference: OpenCode plugins reference.