opencheese-session-uuid

OpenCode plugin for OpenCheese — automatically injects the OpenCheese-Session-UUID header into LLM requests so OpenCheese can track session billing, cache accounting, and analytics.

Setup

1. Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencheese-session-uuid"]
}

2. Restart OpenCode.

That's it. OpenCode will auto-install the plugin from npm on startup.

What it does

• Listens for the active OpenCode session ID.
• Derives a deterministic UUID from the session ID using SHA-256.
• Injects it as the OpenCheese-Session-UUID HTTP header on every LLM request.
• OpenCheese uses this header for per-session billing, token accounting, and usage analytics.

Backend Integration

When OpenCode sends a prompt, it makes a standard HTTP POST request to the baseURL configured for the provider. The request looks like a standard OpenAI, Anthropic, or Google Gemini chat completions payload, but with your custom header attached.

Here is an example of what the raw HTTP request looks like arriving at your gateway:

POST /v1/chat/completions HTTP/1.1
Host: localhost:8787
Authorization: Bearer <your-api-key>
Content-Type: application/json
OpenCheese-Session-UUID: 25ab54ac-944e-4103-97cb-48f82ef8c7c9

{
  "model": "opencode-go/deepseek-v4-pro",
  "messages": [
    {"role": "system", "content": "You are a coding assistant..."},
    {"role": "user", "content": "Write a python script..."}
  ],
  "temperature": 0.2
}

Reading the header in Node.js (Fastify/Express)

Because HTTP headers are case-insensitive, most web frameworks automatically convert them to lowercase. You can read the injected header like this:

Fastify / Express:

const sessionUuid = request.headers["opencheese-session-uuid"];
if (!sessionUuid) {
    throw new Error("Missing OpenCheese session tracking UUID");
}
console.log("Tracking session:", sessionUuid);

Standard Node http or Next.js API Routes:

const sessionUuid = req.headers.get("opencheese-session-uuid");

Requirements

• OpenCode v0.15.0 or later.

License

MIT