openrouter-free

name	openrouter-free
description	Dynamic OpenRouter free-model integration. Provides CLI for discovery, health checks, and chat. Automatically fetches, caches, and refreshes models. Supports fallback routing and capability detection.
license	MIT
user-invocable	true
argument-hint	[command] [args]
arguments	[{"name":"command","description":"The command to run (init, models, use, chat, refresh, health, aliases, config)","required":false},{"name":"args","description":"Arguments for the command (e.g., model name, filter, or chat message)","required":false}]
when_to_use	Use when user wants to use free LLMs, check OpenRouter model status, start a chat with a free model, or manage OpenRouter aliases.

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 OPENROUTER_API_KEY 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 CACHE_TTL_MS (default 1h).
4. 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.
5. 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.
6. 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

Error	Fix
Missing API key	export OPENROUTER_API_KEY="sk-or-v1-..."
429 Rate Limit	Exponential backoff, then notify user.
Model 404/503	Fallback to next best model in registry.
Cache Expired	Auto-refresh from API.

---

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 OPENROUTER_MAX_DISPLAY (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