opencode-session-header

OpenCode plugin that injects the current session ID into customizable request headers, enabling LLM providers to leverage session-based caching.

Why

Some LLM providers (e.g. caching proxies, semantic cache services) require a specific header like session_id to identify a conversation session and serve cached responses. OpenCode already sends x-session-affinity by default, but if your provider expects a different header name, this plugin lets you configure it without modifying OpenCode source code.

Install

Via npm

Add to your opencode.json:

{
  "plugin": ["opencode-session-header"]
}

Via local file

{
  "plugin": ["./path/to/opencode-session-header"]
}

Configuration

By default, the plugin injects session_id with the value of the current OpenCode session ID.

You can customize the header name(s) via plugin options:

Single header

{
  "plugin": [["opencode-session-header", { "headers": "session_id" }]]
}

Multiple headers

{
  "plugin": [
    [
      "opencode-session-header",
      { "headers": ["session_id", "X-Cache-Session"] }
    ]
  ]
}

All specified headers will be set to the same value — the current OpenCode session ID.

How It Works

The plugin uses OpenCode's chat.headers hook, which is called on every LLM request. It receives the current sessionID and injects it into the specified header(s) in the outgoing HTTP request.

License

MIT