# Openrouter Free

> 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.

- Skill: `shihabshahrier/openrouter-free` (Agent Skill, multi-file: 35 files)
- Install (CLI): `npx skillmds@latest add shihabshahrier/openrouter-free`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shihabshahrier/openrouter-free/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: shihabshahrier (https://skillmd.com/u/shihabshahrier)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shihabshahrier/openrouter-free

---


# 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

```bash
# 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
```