openrouter-free

Integrate OpenRouter's free AI models with dynamic discovery, local caching, and fallback routing.

Trigger

User invokes /openrouter-free [command] [args] or asks to "list free models", "chat with a free model", or "check OpenRouter status".

Process

1. Environment Check: Ensure OPENROUTERAPIKEY is set. If missing, show setup instructions and stop.
2. Initialization: If first run or init command, fetch all models from GET https://openrouter.ai/api/v1/models.
3. Caching:

- Store models in ~/.opencode/openrouter-model-cache.json. - Use 0o600 permissions. - Respect CACHETTLMS (default 1h).

1. Filtering & Discovery:

- Filter for models containing :free or specific capability tags. - Map short aliases (e.g., r1, qwen, gemma) to full IDs from references/discovery.md.

1. Execution:

- Discovery: List models with models [filter]. - Interactive: Start REPL with use <model|alias>. - One-shot: Execute single message with chat "<msg>" [--model <id>]. - Health: Ping models with health [model] to report latency.

1. Resilience:

- On 429/5xx, retry with exponential backoff (1s, 2s, 4s). - On model failure during use or chat, fallback to the next best model using fallback-router.ts.

Output

• CLI Listings: Tabular or list format for models and health status.
• Chat: Streaming SSE response for interactive and one-shot modes.
• Cache File: Updated openrouter-model-cache.json on refresh or TTL expiry.
• Errors: Graceful exit messages with fix suggestions for common API/Config errors.

Error Handling

Token Efficiency Rules

• Use openrouter-free models free to list available models before suggesting one.
• Prefer openrouter-free health over individual pings for bulk status.
• Cache results locally to avoid redundant API calls.
• Limit model display to OPENROUTERMAXDISPLAY (default 30).

Open-Weight Model Rules

• Strict Command Syntax: Always use the defined CLI commands; do not hallucinate flags.
• Model IDs: Use full provider/model strings (e.g., google/gemma-2-9b-it:free) unless an alias is confirmed.
• Streaming: Ensure --stream (if applicable) or default streaming behavior is respected for long outputs.
• Environment: Do not modify .env files directly unless instructed; guide the user to set variables.

Boundaries

• Does not manage paid OpenRouter models unless explicitly requested.
• Does not store user chat history beyond the current REPL session.
• Does not modify any project files outside of ~/.opencode/ cache.

Usage Examples

# Discover all free models with vision support
openrouter-free models vision

# Chat with the longest-context free model
openrouter-free use best-free

# One-shot with a specific alias
openrouter-free chat "Write a Python HTTP server" --model r1

# Check which free models are responsive
openrouter-free health