opencode-oneshot

An OpenCode plugin that reduces GitHub Copilot API request usage through ONE-SHOT prompt injection, response deduplication, retry limiting, and request batching.

What It Does

| Feature | How it works | |---------|-------------| | ONE-SHOT prompt injection | Appends a system instruction to make the model return complete answers in a single request, avoiding follow-up round-trips | | Hash-based deduplication | Hashes incoming message arrays; logs cache hits when duplicate conversations are detected | | Retry limiting | Tracks per-session retry counts and prevents runaway retry loops (default: 1 retry max) | | Request batching | Coalesces concurrent requests within a configurable time window (default: 75ms) | | Periodic metrics | Logs request counts, cache hit rates, and uptime at a configurable interval |

Installation

opencode plugin -g opencode-oneshot

The plugin is registered automatically — no manual changes to opencode.json required.

Compatibility with oh-my-opencode-slim

This plugin is fully compatible with oh-my-opencode-slim. Both plugins use experimental.chat.system.transform and experimental.chat.messages.transform hooks — OpenCode calls all registered plugins for each hook.

The ONE-SHOT injection is idempotent: it checks for the ONE-SHOT mode marker before pushing to the system array, so even if both plugins fire in the same request, the prompt is only injected once.

Configuration

Configuration is loaded from multiple sources and merged in priority order (lowest → highest):

1. Hardcoded defaults
2. User global config — ~/.config/opencode/opencode-oneshot.json
3. XDG config — $XDG_CONFIG_HOME/opencode/opencode-oneshot.json (if XDG_CONFIG_HOME is set)
4. Project config — .opencode/opencode-oneshot.json (in the project root)
5. Environment variables — override specific numeric fields, highest priority

Config file format

{
  "maxRetries": 1,
  "batchWindowMs": 75,
  "maxBatchSize": 10,
  "cacheMaxSize": 1000,
  "cacheTtlMs": 3600000,
  "periodicMetricsIntervalMs": 60000,
  "oneShotAgents": ["*"],
  "excludeAgents": []
}

All fields are optional. Missing fields fall back to the next lower-priority source or the default.

All available fields

| Field | Type | Default | Description | |-------|------|---------|-------------| | maxRetries | number | 1 | Maximum retries allowed per session | | batchWindowMs | number | 75 | Batch window in ms for coalescing concurrent requests | | maxBatchSize | number | 10 | Maximum requests per batch window | | cacheMaxSize | number | 1000 | Maximum LRU cache entries | | cacheTtlMs | number | 3600000 | Cache entry TTL in ms (default: 1 hour) | | periodicMetricsIntervalMs | number | 60000 | Metrics logging interval in ms | | oneShotAgents | string[] | undefined | If set, only these agents receive the ONE-SHOT prompt. Use ["*"] for all agents (same as undefined). | | excludeAgents | string[] | [] | Agents that never receive the ONE-SHOT prompt. Takes precedence over oneShotAgents. |

Environment variable overrides

Numeric fields can be overridden at any time via environment variables:

| Variable | Field | |----------|-------| | ONESHOT_MAX_RETRIES | maxRetries | | ONESHOT_BATCH_WINDOW_MS | batchWindowMs | | ONESHOT_MAX_BATCH_SIZE | maxBatchSize | | ONESHOT_CACHE_MAX_SIZE | cacheMaxSize | | ONESHOT_CACHE_TTL_MS | cacheTtlMs | | ONESHOT_PERIODIC_METRICS_MS | periodicMetricsIntervalMs |

ONESHOT_MAX_RETRIES=2 ONESHOT_CACHE_MAX_SIZE=500 opencode

Agent filtering: oneShotAgents and excludeAgents

These fields let you control which agents receive the ONE-SHOT system prompt.

excludeAgents — always takes precedence. Agents named here never receive the prompt, regardless of oneShotAgents:

{ "excludeAgents": ["oracle", "designer"] }

oneShotAgents — if set, acts as an allowlist. Only named agents receive the prompt:

{ "oneShotAgents": ["coder", "reviewer"] }

Use ["*"] (or omit the field entirely) to apply ONE-SHOT to all agents:

{ "oneShotAgents": ["*"] }

If agentName is not known (e.g., the hook fires without an agent identifier), the agent is treated as allowed unless it matches excludeAgents.

Recommended config for use with oh-my-opencode-slim

Exclude agents that benefit from iterative, conversational dialogue:

{
  "maxRetries": 1,
  "excludeAgents": ["oracle", "designer", "councillor"]
}

A ready-made preset is available at examples/opencode-oneshot-slim-compat.json.

How Deduplication Works

1. Before each LLM call, the experimental.chat.messages.transform hook fires with the full message array.
2. The plugin normalizes messages (trim whitespace, lowercase roles, filter empty) and computes a SHA-256 hash (truncated to 16 hex chars).
3. If the hash is in the LRU cache, a cache hit is logged and metrics are incremented.
4. After sessions complete (session.idle / session.updated events), the assistant's response is stored in the cache under that hash.

Limitations

• Cannot cancel in-flight requests from transform hooks. The experimental.chat.messages.transform hook mutates the message array in-place but cannot return early or short-circuit the request. Cache hits are logged for metrics, but the LLM call still proceeds. If/when OpenCode exposes a cancellation mechanism in transform hooks, this plugin will be updated to use it.
• experimental.session.compacting output shape may vary across OpenCode versions. The plugin pushes a ONE-SHOT reminder into output.context but this is best-effort.

Metrics

Metrics are displayed live in the right sidebar of the OpenCode TUI (the sidebar_content slot). You'll see a panel like this:

┌─────────────────────────────┐
│ OneShot              v0.2.2 │
│                             │
│ Status    ● ONE-SHOT active │
│                             │
│ Requests               42   │
│ Cache hits              7   │
│ Hit rate            16.7%   │
│ Retries blocked         1   │
│ Batches merged          3   │
│                             │
│ Uptime                300s  │
│ Idle: a1b2c3d4              │
└─────────────────────────────┘

The sidebar updates every second. If the sidebar is not visible, press the key to toggle the right panel in OpenCode (default: ] or check your keybinds).

The plugin also logs periodic metrics to stdout (useful when running headlessly):

{
  "requests": 42,
  "preventedRequests": 7,
  "retriesPrevented": 1,
  "batchesMerged": 3,
  "cacheHitRate": "16.7%",
  "uptimeSeconds": 300
}

Development

npm install
npm run build    # compile TypeScript
npm run dev      # watch mode
npm test         # run Jest tests

License

MIT