@shift-preflight/opencode-plugin

OpenCode plugin that auto-starts the SHIFT image optimization proxy. Every image-heavy request is transparently optimized before reaching the AI provider — reducing token cost and preventing oversized-image failures.

Prerequisites

Install the shift-ai CLI:

brew install alohaninja/shift/shift-ai

The plugin silently skips if shift-ai is not installed — no errors, no breakage.

Installation

Add the plugin to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@shift-preflight/opencode-plugin"],
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "http://localhost:8787"
      }
    }
  }
}

OpenCode auto-installs npm plugins at startup via Bun. No npm install needed.

How it works

On every OpenCode launch:

1. Checks prerequisites — verifies shift-ai is on PATH. Silently skips if not installed.
2. Probes port 8787 — if the SHIFT proxy is already running (from a previous session or another agent), skips startup. Verifies the proxy identity to avoid trusting unrelated services on the same port. Fully idempotent.
3. Starts the proxy — spawns the proxy as a detached background process with a sanitized environment (API keys are not passed to the child process).
4. Verifies startup — waits briefly to confirm the proxy is healthy. Logs a warning with bypass instructions if it fails.

Startup verification adds ~6 seconds on first launch; subsequent launches detect the running proxy instantly.

The provider.anthropic.options.baseURL config routes all Anthropic requests through the proxy. The proxy optimizes images, then forwards to the real Anthropic API. Auth headers and SSE streams pass through unchanged.

Sharing with other agents

The proxy runs on localhost:8787 and can be shared with any agent that supports a custom base URL:

# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# Codex CLI
OPENAI_BASE_URL=http://localhost:8787 codex

# Gemini CLI (check Gemini CLI docs for the correct env var)
# GEMINI_API_BASE=http://localhost:8787 gemini

Once OpenCode starts the proxy, other agents piggyback on it — no need to start it separately.

Optimization modes

The default mode is balanced. To change it, start the proxy manually before OpenCode:

npx @shift-preflight/runtime proxy --port 8787 --mode economy

Proxy routes

Checking savings

View cumulative token savings across all proxied requests:

shift-ai gain              # Summary
shift-ai gain --daily      # Day-by-day breakdown
shift-ai gain --format json  # Machine-readable

Troubleshooting

License

Apache-2.0 — see LICENSE.