openrouter-free
Dynamic OpenRouter free-model integration layer
Open source Open in the app JSON README (API)
About
Dynamic OpenRouter free-model integration layer
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- shihabshahrier
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-06-12T23:45:02Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
shihabshahrier/openrouter-free-infer
README
# 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
bash install.sh
```
### Option 2: Manual — Claude Code
```bash
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
```bash
mkdir -p ~/.agents/skills/openrouter-free
cp -r skills/openrouter-free/. ~/.agents/skills/openrouter-free/
```
### Option 4: Manual — opencode
```bash
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
```bash
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