@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/v1"
      }
    }
  }
}

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. Note: OpenCode's Anthropic client appends only /messages (not /v1/messages) to the base URL, which is why /v1 must be included in the baseURL. 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 (no /v1 — the Anthropic SDK appends /v1/messages)
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# Codex CLI — add to ~/.codex/config.toml:
# 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

| Mode | Behavior | |------|----------| | performance | Minimal transforms. Only enforce hard provider limits. | | balanced | Moderate optimization. Resize oversized images, recompress bloated files. Default. | | economy | Aggressive optimization. Downscale to 1024px, minimize token usage. |

Proxy routes

| Route | Provider | |-------|----------| | POST /v1/messages | Anthropic | | POST /messages | Anthropic (fallback — rewrites to /v1/messages) | | POST /v1/chat/completions | OpenAI | | POST /v1beta/models/* | Google (passthrough only — no image optimization yet) |

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

Upgrading

OpenCode caches npm plugins at ~/.cache/opencode/packages/ and does not automatically check for newer versions. Running shift-ai setup will detect and clear stale caches automatically.

To force an upgrade manually:

# Remove the cached plugin and let OpenCode re-install on next launch
rm -rf ~/.cache/opencode/packages/@shift-preflight*

Then restart OpenCode — it will fetch the latest version from npm.

Version mismatch behavior

When the plugin starts, it probes the running proxy and compares versions:

| Running proxy | Plugin version | Action | |---------------|---------------|--------| | Same version | — | Skip (already running) | | Newer version | — | Skip (don't downgrade) | | Older version | — | Stop old proxy, start new one | | No version reported | — | Treat as stale, restart | | Not running | — | Start proxy |

This means multiple OpenCode sessions with different plugin versions can coexist safely — the newest proxy always wins.

Troubleshooting

| Problem | Fix | |---------|-----| | Plugin not loading | Verify "plugin": ["@shift-preflight/opencode-plugin"] is in your opencode.json | | Proxy not starting | Check that shift-ai is installed: which shift-ai | | Requests failing | Ensure provider.anthropic.options.baseURL is set to http://localhost:8787/v1 and the proxy is running | | Plugin not updating | OpenCode caches plugins and doesn't auto-update. Run shift-ai setup to detect and clear stale caches, or manually: rm -rf ~/.cache/opencode/packages/@shift-preflight* | | Port 8787 in use | Another process is using the port. Check with lsof -i :8787 | | "Unknown route" error | Your baseURL is likely missing the /v1 suffix. The correct value for OpenCode is http://localhost:8787/v1. OpenCode's Anthropic client appends only /messages to the base URL, so /v1 must be included. | | Want to bypass proxy | Remove the baseURL from your provider config, or stop the proxy |

License

Apache-2.0 — see LICENSE.