opencode-cost-guard

An OpenCode plugin that monitors session cost in real time and fires a warning or stop message when a configurable spending threshold is reached.

Why? OpenCode has no built-in per-session cost limit. This plugin fills that gap while a native feature is still pending.

---

Features

• ⚠️ Early warning at a configurable percentage of the budget (e.g. 80%)
• ⛔ Limit alert when the session cost exceeds the threshold
• 🔇 No spam — each message fires at most once per session
• 🗂️ Per-project config — override the global limit for individual repositories
• 🔌 Zero friction — install via npm, one line in opencode.json

---

Installation

Add the package name to the plugins array in your OpenCode config:

// ~/.config/opencode/opencode.json  (global)
// or .opencode/opencode.json        (per-project)
{
  "plugins": ["opencode-cost-guard"]
}

OpenCode resolves and installs the plugin from npm on startup.

---

Configuration

Create a config file — loaded once at plugin initialisation, no restart required.

Global config

~/.config/opencode/cost-guard.config.json

Per-project override (takes priority over global)

<project-root>/.opencode/cost-guard.config.json

Config reference

The file must be valid JSON — comments are stripped before parsing so // and /* */ comments are accepted, but trailing commas are not.

Key	Type	Default	Description
maxCostUsd	number	20.0	Cost limit in USD. Alert fires when this is exceeded.
warnAtPercent	number (0 – 100)	80	Early warning threshold as a % of maxCostUsd. 0 to disable.
mode	"warn" | "block"	"warn"	warn — injects a message. block — marks the session stopped.

{
  "maxCostUsd": 20.0,
  "warnAtPercent": 80,
  "mode": "warn"
}

If no config file is found, the built-in defaults above apply.

---

How it works

The plugin hooks into the session.idle event, which fires after every model response. It then:

1. Reads the session ID from the event payload
2. Fetches the current cumulative cost via the OpenCode SDK
3. Compares it against the configured thresholds
4. Injects a formatted warning or stop message into the chat if needed

Because it acts after each response (not before), it cannot intercept a request mid-flight — the limit is enforced reactively.

User prompt → Model response → session.idle → cost-guard checks → ⚠️ or ⛔ if needed

Deduplication

Two in-memory Set objects track which sessions have already received a warning or been blocked. Each message fires at most once per session, regardless of how many subsequent responses occur.

---

Startup log

The plugin always prints one line at startup confirming the active configuration:

[cost-guard] Active — limit: $20.0000 | warn at: 80% | mode: warn

That is the only log line produced during normal operation. Warnings and errors always print regardless.

Debug logging

Set COST_GUARD_DEBUG=1 to enable verbose per-event logs — useful when diagnosing why a threshold isn't firing:

[cost-guard] Active — limit: $2.0000 | warn at: 80% | mode: warn | debug: on
[cost-guard] Config loaded from: /Users/you/.config/opencode/cost-guard.config.json
[cost-guard] session.idle received — sessionId: abc123
[cost-guard] session abc123 — messages: 4, cost: $1.6400, limit: $2.0000

To set the variable for an OpenCode session launched from the terminal:

COST_GUARD_DEBUG=1 opencode

---

Example messages

Early warning (at 80% of budget)

⚠️  **COST WARNING** — 82% of budget used.
Cost: $16.4000 — Limit: $20.0000 — Remaining: $3.6000

Limit reached — warn mode

⛔ **COST LIMIT REACHED** — Cost: $20.0031 / $20.0000 (100%)

Configured limit reached. Consider starting a new session or
update "maxCostUsd" in cost-guard.config.json.

Limit reached — block mode

⛔ **COST LIMIT REACHED** — Session automatically stopped.
Cost: $20.0031 / Limit: $20.0000 (100%)

This session will no longer respond to new requests.
Start a new session to continue working.

---

Development

git clone https://github.com/jjmartres/opencode-cost-guard.git
cd opencode-cost-guard

make env      # install pinned Node (via asdf) + npm deps
make check    # type-check without emitting files
make build    # compile TypeScript → dist/
make dev      # watch mode — recompiles on save
make clean    # remove dist/

Run make with no arguments to see all available targets, including bump for version management and release-* for publishing. See CONTRIBUTING.md for the full workflow.

Testing locally

Point OpenCode at your local build instead of the npm package:

// .opencode/opencode.json  (in a test project)
{
  "plugins": ["file:///absolute/path/to/opencode-cost-guard/dist/index.js"]
}

Then open OpenCode in that project and verify the startup log appears.

---

Known limitations

• The limit is reactive, not preventive. A single expensive response can push the cost over the threshold before the plugin fires.
• The in-memory session state is reset when OpenCode restarts. A session that was already warned or blocked will be treated as fresh after a restart.
• For a hard preventive limit, consider routing through a gateway like Portkey which supports budget enforcement at the API level.

---

License

MIT