openrouter-free — OpenRouter Free Model Integration for OpenCode

A production-ready skill that dynamically discovers and connects to free AI models via the OpenRouter API. Zero hardcoded model lists.

What It Does

• Dynamically fetches all available models from GET https://openrouter.ai/api/v1/models
• Auto-filters free models (tagged :free)
• Detects capabilities (vision, tool-calling, structured outputs, reasoning) from API metadata
• Caches locally at ~/.opencode/openrouter-model-cache.json with configurable TTL
• Falls back gracefully if the API is unreachable or a model fails
• Provides a clean CLI for model discovery, health checks, and interactive chat

Example Output

📋 Free Models (12 models)

ID                                    │ Name                                      │ Context │ Capabilities
──────────────────────────────────────┼───────────────────────────────────────────┼─────────┼────────────────────────
deepseek/deepseek-r1-0528:free        │ DeepSeek R1 (Free)                        │ 128K    │ 🧠 reasoning
google/gemma-3-27b-it:free            │ Gemma 3 27B Instruct (Free)               │ 128K    │ 👁️ vision 🔧 tool-calling
qwen/qwen3-32b:free                   │ Qwen3 32B (Free)                          │ 128K    │ 🔧 tool-calling 🧠 reasoning
meta-llama/llama-3.1-8b-instruct:free │ Llama 3.1 8B Instruct (Free)              │ 128K    │ 🔧 tool-calling
...

Install

Option 1: Automated (from repo root)

bash install.sh

Option 2: Manual — Claude Code

mkdir -p ~/.claude/skills/openrouter-free
cp -r skills/openrouter-free/. ~/.claude/skills/openrouter-free/
cd ~/.claude/skills/openrouter-free
npm install && npm run build

Option 3: Manual — Codex

mkdir -p ~/.agents/skills/openrouter-free
cp -r skills/openrouter-free/. ~/.agents/skills/openrouter-free/

Option 4: Manual — opencode

mkdir -p ~/.config/opencode/skills/openrouter-free
cp -r skills/openrouter-free/. ~/.config/opencode/skills/openrouter-free/

Usage

Command	Description
openrouter-free init	Bootstrap — fetch models and populate cache
openrouter-free models free	List all free models
openrouter-free models coding	Free models with tool-calling
openrouter-free models vision	Free models with vision support
openrouter-free use r1	Chat with DeepSeek R1 (alias)
openrouter-free use best-free	Chat with auto-routed free model
openrouter-free chat "hello" --model qwen	One-shot message
openrouter-free refresh	Force cache refresh
openrouter-free health	Check all free models availability
openrouter-free aliases	List all known aliases
openrouter-free interactive	Start REPL chat mode

Requirements

• Node.js ≥ 18
• OPENROUTER_API_KEY environment variable

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
# Get a free key at: https://openrouter.ai/settings/keys

Architecture

cli.ts (entry) → OpenRouterFree (facade)
                  ├─ ModelRegistry   (API fetch + filter)
                  ├─ CacheManager    (disk persistence, TTL)
                  ├─ ProviderAdapter (chat completions, retry, stream)
                  ├─ FallbackRouter  (model selection + failover)
                  ├─ CapabilityDetector (infer from params)
                  ├─ HealthChecker   (ping probes)
                  └─ AliasManager    (short names → IDs)

Caching

• Path: ~/.opencode/openrouter-model-cache.json
• TTL: 1 hour (3,600,000 ms), override with CACHE_TTL_MS
• Permissions: 0o600

Environment Variables

Variable	Default	Description
OPENROUTER_API_KEY	—	API key (required)
OPENROUTER_BASE_URL	https://openrouter.ai/api/v1	Custom endpoint
CACHE_TTL_MS	3600000	Cache TTL in ms

License

MIT

---

📖 Project page: https://shihub.online/projects/openrouter-free-infer