1 line
15 KiB
JSON
1 line
15 KiB
JSON
{"repo": "404kidwiz/claude-openrouter-router", "files": {"README.md": {"16d9565e5ef33de6c7c6eae3944451c36a830a27": {"t": 1785674339.6261115, "n": 14409, "h": "1b08c2951ab38048", "c": "# Claude OpenRouter Router\n\n\n\n\n\nSmall shell launchers for running Claude Code through OpenRouter's Anthropic-compatible endpoint.\n\nThe goal is simple: keep Claude Code's environment clean, make provider switching obvious, and offer a safe default that follows OpenRouter's Claude Code documentation.\n\n> **Note:** Shortcut commands (`claude-ring`, `claude-owl`, etc.) do **not** replace your existing `claude` command. The original Claude Code binary stays untouched. Use `claude-openrouter` or a shortcut when you want OpenRouter routing.\n\n**Compatibility:** macOS and Linux. Requires bash 4+. Not tested on Windows (WSL may work).\n\n## What This Does\n\n`claude-openrouter` starts Claude Code with the OpenRouter environment variables that Claude Code expects:\n\n```bash\nANTHROPIC_BASE_URL=https://openrouter.ai/api\nANTHROPIC_AUTH_TOKEN=$OPENROUTER_API_KEY\nANTHROPIC_API_KEY=\n```\n\nThe empty `ANTHROPIC_API_KEY` is intentional. OpenRouter's Claude Code guide says it must be explicitly blank so Claude Code does not try to authenticate against Anthropic directly.\n\n## Install\n\nHomebrew (macOS/Linux):\n\n```bash\nbrew tap 404kidwiz/tap\nbrew install claude-openrouter\n```\n\nOne-line install:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/404kidwiz/claude-openrouter-router/main/bootstrap.sh | bash\n```\n\nThen run:\n\n```bash\nclaude-openrouter --setup\n```\n\nClone and install:\n\n```bash\ngit clone https://github.com/404kidwiz/claude-openrouter-router.git\ncd claude-openrouter-router\n./install.sh\n```\n\nMake sure `~/.local/bin` is on your `PATH`:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\nCreate an OpenRouter API key from the [OpenRouter API keys page](https://openrouter.ai/settings/keys), then save it locally.\n\nFastest setup:\n\n```bash\nclaude-openrouter --setup\n```\n\nRecommended, avoids putting the key directly in shell history:\n\n```bash\nprintf '%s' 'sk-or-v1-...' | claude-openrouter --set-key-stdin\n```\n\nConvenient, but may be saved in shell history:\n\n```bash\nclaude-openrouter --set-key \"sk-or-v1-...\"\n```\n\nCheck your config:\n\n```bash\nclaude-openrouter --show-config\n```\n\nThen run:\n\n```bash\nclaude-openrouter claude\n```\n\nIf you prefer shell environment variables instead of saved config, add your OpenRouter key to your shell profile:\n\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"\n```\n\nRestart your shell, or run:\n\n```bash\nsource ~/.zshrc\n```\n\n## AI Agent Install\n\nIf you want another AI coding agent or LLM to install this for you, give it this link:\n\n```text\nhttps://raw.githubusercontent.com/404kidwiz/claude-openrouter-router/main/AGENT_INSTALL.md\n```\n\nThat page tells the agent exactly what to run, how to verify the install, and how to handle the OpenRouter API key safely.\n\n## Commands\n\nConfiguration:\n\n```bash\nclaude-openrouter --setup\nclaude-openrouter --set-key \"sk-or-v1-...\"\nprintf '%s' 'sk-or-v1-...' | claude-openrouter --set-key-stdin\nclaude-openrouter --unset-key\nclaude-openrouter --set-default-profile free\nclaude-openrouter --set-main-model sonnet\nclaude-openrouter --set-opus-model anthropic/claude-opus-4-7\nclaude-openrouter --set-sonnet-model anthropic/claude-sonnet-4-6\nclaude-openrouter --set-haiku-model anthropic/claude-haiku-4-5-20251001\nclaude-openrouter --set-base-url https://openrouter.ai/api\nclaude-openrouter --set-timeout 3000000\nclaude-openrouter --show-config\nclaude-openrouter --update\nclaude-openrouter --uninstall\nclaude-openrouter install-commands\nclaude-openrouter list-commands\nclaude-openrouter commands-dir\nclaude-openrouter --config-path\n```\n\n## Setup Wizard\n\nRun the guided setup flow:\n\n```bash\nclaude-openrouter --setup\n```\n\nIt walks through:\n\n- Saving an OpenRouter API key.\n- Choosing a default profile such as `claude` or `free`.\n- Choosing the strict Claude-mode main model, usually `sonnet`.\n- Confirming the OpenRouter base URL.\n- Setting the API timeout.\n- Optionally adding custom OpenRouter model profiles.\n- Creating shortcut commands such as `claude-ring` and `claude-qwen`.\n- Running a dry-run verification.\n\nImportant: bare `claude` still launches the original Claude Code binary. Use `claude-openrouter`, `claude-ring`, `claude-qwen`, or another shortcut command to route through OpenRouter.\n\nStrict Claude compatibility:\n\n```bash\nclaude-openrouter claude\n```\n\nLowest-cost/free OpenRouter routing:\n\n```bash\nclaude-openrouter free\nclaude-or-free\nclaude-or-auto-free\n```\n\nNamed OpenRouter model profiles:\n\n```bash\nclaude-openrouter-claude\nclaude-nemotron\nclaude-ring\nclaude-owl\nclaude-pareto-code\nclaude-hunyuan\n```\n\nGeneric model switcher:\n\n```bash\nclaude-or-model nemotron\nclaude-or-model ring\nclaude-or-model owl\nclaude-or-model free\nclaude-or-model pareto-code\nclaude-or-model openrouter/owl-alpha\n```\n\nUser-defined model profiles:\n\n```bash\nclaude-openrouter add-model qwen/qwen3-coder:free\nclaude-openrouter --add-profile moonshotai/kimi-k2:free\nclaude-openrouter --add-profile qwen/qwen3-coder:free\nclaude-openrouter --add-profile my-qwen qwen/qwen3-coder:free\nclaude-openrouter --list-profiles\nclaude-openrouter install-commands\nclaude-qwen3-coder\nclaude-openrouter kimi-k2\n```\n\nYou can pass normal Claude Code arguments after the profile:\n\n```bash\nclaude-openrouter claude -p \"Reply with exactly OK\"\nclaude-or-model nemotron -p \"Reply with exactly OK\"\n```\n\n## Profiles\n\n| Profile | Model | Compatibility |\n| --- | --- | --- |\n| `claude` | Anthropic first-party Claude models through OpenRouter | Best / strict |\n| `free` | `openrouter/free` | Best-effort |\n| `nemotron` | `nvidia/nemotron-3-super-120b-a12b:free` | Best-effort |\n| `ring` | `inclusionai/ring-2.6-1t` | Best-effort |\n| `owl` | `openrouter/owl-alpha` | Best-effort |\n| `pareto-code` | `openrouter/pareto-code` | Best-effort |\n| `hunyuan` | `tencent/hy3-preview` | Best-effort |\n\nClaude Code is optimized for Anthropic models. The `claude` profile is the reliable default. Non-Claude OpenRouter models can work through OpenRouter's Anthropic-compatible surface, but tool use, context features, speed, and formatting may vary by model/provider.\n\n## Custom Profiles\n\nYou can add your own OpenRouter model aliases without editing the script.\n\nFastest path:\n\n```bash\nclaude-openrouter add-model qwen/qwen3-coder:free\nclaude-qwen3-coder\n```\n\n`add-model` does the whole setup for that model:\n\n- Adds the custom profile.\n- Auto-generates a friendly profile name.\n- Creates the matching shortcut command.\n- Prints the exact command to run next.\n\nIf you provide only a model ID, the router auto-generates a profile name from the model slug:\n\n```bash\nclaude-openrouter --add-profile qwen/qwen3-coder:free\nclaude-openrouter install-commands\nclaude-qwen3-coder\n```\n\nIn that example:\n\n- Model ID: `qwen/qwen3-coder:free`\n- Auto-generated profile: `qwen3-coder`\n- Auto-generated shortcut command: `claude-qwen3-coder`\n\nAdd a profile:\n\n```bash\nclaude-openrouter --add-profile kimi moonshotai/kimi-k2:free\n```\n\nOr choose the profile name yourself:\n\n```bash\nclaude-openrouter add-model qwen qwen/qwen3-coder:free\nclaude-qwen\n```\n\nLower-level equivalent:\n\n```bash\nclaude-openrouter --add-profile qwen qwen/qwen3-coder:free\nclaude-openrouter install-commands\nclaude-qwen\n```\n\nUse it:\n\n```bash\nclaude-openrouter kimi\nclaude-or-model kimi -p \"Reply with exactly OK\"\n```\n\nList profiles:\n\n```bash\nclaude-openrouter --list-profiles\n```\n\nRemove a profile:\n\n```bash\nclaude-openrouter --remove-profile kimi\n```\n\nCustom profiles are stored here by default:\n\n```bash\n~/.config/claude-openrouter-router/profiles\n```\n\nThe file format is intentionally boring:\n\n```text\nprofile-name=provider/model-id\n```\n\nExample:\n\n```text\nkimi=moonshotai/kimi-k2:free\nqwen=qwen/qwen3-coder:free\n```\n\nTo store profiles somewhere else:\n\n```bash\nexport CLAUDE_OPENROUTER_CONFIG_DIR=\"$HOME/.config/my-openrouter-profiles\"\n```\n\n## Shortcut Commands\n\nShortcut commands are the friendly commands you run every day.\n\n`claude-openrouter install-commands` creates one small launcher per model profile, so you can type `claude-ring` instead of remembering `claude-openrouter ring`.\n\nFor custom models, the command name comes from the profile name. If the user added a model without choosing a name, the profile name is auto-generated from the model ID.\n\n```bash\nclaude-openrouter install-commands\n```\n\nWhat it means:\n\n- `claude-openrouter` is the router.\n- `install-commands` means “create the shortcut commands.”\n- It writes commands like `claude-ring` and `claude-qwen` into `~/.local/bin`.\n\nExamples:\n\n```bash\nclaude-ring\nclaude-owl\nclaude-nemotron\nclaude-pareto-code\nclaude-qwen\n```\n\nList what would be available:\n\n```bash\nclaude-openrouter list-commands\n```\n\nBy default commands are written to:\n\n```bash\n~/.local/bin\n```\n\nChange that with:\n\n```bash\nexport CLAUDE_OPENROUTER_COMMANDS_DIR=\"$HOME/bin\"\n```\n\nThe shortcut commands intentionally do not replace `claude`. That keeps the original Claude Code command untouched and avoids confusing recursion. If you want OpenRouter routing, call `claude-openrouter` or a shortcut command such as `claude-ring`.\n\n## Dry Run\n\nPreview what will be launched without starting Claude Code:\n\n```bash\nclaude-openrouter --dry-run claude\nclaude-openrouter --dry-run nemotron\n```\n\nPrint the environment mapping:\n\n```bash\nclaude-openrouter --print-env free\n```\n\nSecrets are redacted from dry-run output.\n\n## Configuration\n\nEasy path:\n\n```bash\nclaude-openrouter --setup\n```\n\nWhen setup finishes, it prints the command to run next, plus a safe dry-run command for checking the selected profile.\n\nThe setup UI uses dependency-free terminal colors, ASCII cards, and command blocks. Disable color with:\n\n```bash\nNO_COLOR=1 claude-openrouter --setup\n```\n\nManual path:\n\n```bash\nclaude-openrouter --set-key \"sk-or-v1-...\"\nprintf '%s' 'sk-or-v1-...' | claude-openrouter --set-key-stdin\nclaude-openrouter --set-default-profile claude\nclaude-openrouter --show-config\n```\n\nSaved configuration lives here:\n\n```bash\n~/.config/claude-openrouter-router/config\n```\n\nThe file is written with `0600` permissions and uses simple `KEY=value` lines:\n\n```text\nOPENROUTER_API_KEY=sk-or-v1-...\nCLAUDE_OPENROUTER_DEFAULT_PROFILE=claude\nCLAUDE_OPENROUTER_MAIN_MODEL=sonnet\nCLAUDE_OPUS_MODEL=anthropic/claude-opus-4-7\nCLAUDE_SONNET_MODEL=anthropic/claude-sonnet-4-6\nCLAUDE_HAIKU_MODEL=anthropic/claude-haiku-4-5-20251001\nCLAUDE_OPENROUTER_BASE_URL=https://openrouter.ai/api\nAPI_TIMEOUT_MS=3000000\n```\n\nAdvanced environment-variable path:\n\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"\n```\n\nOptional environment variables:\n\n```bash\nexport CLAUDE_OPENROUTER_DEFAULT_PROFILE=claude\nexport CLAUDE_OPENROUTER_COMMANDS_DIR=\"$HOME/.local/bin\"\nexport CLAUDE_OPENROUTER_MAIN_MODEL=sonnet\nexport CLAUDE_OPUS_MODEL=anthropic/claude-opus-4-7\nexport CLAUDE_SONNET_MODEL=anthropic/claude-sonnet-4-6\nexport CLAUDE_HAIKU_MODEL=anthropic/claude-haiku-4-5-20251001\nexport CLAUDE_OPENROUTER_BASE_URL=https://openrouter.ai/api\nexport CLAUDE_OPENROUTER_CONFIG_DIR=\"$HOME/.config/claude-openrouter-router\"\nexport API_TIMEOUT_MS=3000000\n```\n\nEnvironment variables override saved config. Saved config overrides built-in defaults.\n\nConfiguration command reference:\n\n```bash\nclaude-openrouter --setup # Guided first-run setup\nclaude-openrouter --set-key \"sk-or-v1-...\" # Save OpenRouter API key\nclaude-openrouter --set-key-stdin # Read OpenRouter API key from stdin\nclaude-openrouter --unset-key # Remove saved API key\nclaude-openrouter --set-default-profile free # Change default profile\nclaude-openrouter --set-main-model sonnet # Main Claude Code model for strict Claude mode\nclaude-openrouter --set-opus-model anthropic/claude-opus-4-7\nclaude-openrouter --set-sonnet-model anthropic/claude-sonnet-4-6\nclaude-openrouter --set-haiku-model anthropic/claude-haiku-4-5-20251001\nclaude-openrouter --set-base-url https://openrouter.ai/api\nclaude-openrouter --set-timeout 3000000\nclaude-openrouter --show-config # Redacts secrets\nclaude-openrouter --update # Pull latest from git and reinstall\nclaude-openrouter --uninstall # Preview what will be removed\nclaude-openrouter --uninstall --yes # Remove all installed files\nclaude-openrouter add-model qwen/qwen3-coder:free # Add model and create claude-qwen3-coder\nclaude-openrouter install-commands # Create shortcuts like claude-ring and claude-qwen\nclaude-openrouter list-commands # Preview shortcut command names\nclaude-openrouter commands-dir # Print shortcut command install directory\nclaude-openrouter --config-path # Prints config file path\n```\n\n## Recommended Usage\n\nUse this when you care most about Claude Code compatibility:\n\n```bash\nclaude-openrouter claude\n```\n\nUse this when you care most about lowest-cost/free routing and accept best-effort compatibility:\n\n```bash\nclaude-openrouter free\n```\n\nUse named wrappers when you are experimenting with specific OpenRouter models:\n\n```bash\nclaude-nemotron\nclaude-ring\nclaude-owl\nclaude-pareto-code\n```\n\n## Suggested Improvements\n\nGood next enhancements:\n\n- Add `claude-openrouter doctor` to check `claude`, `PATH`, config permissions, OpenRouter connectivity, and selected model availability.\n- Add shell completions for profiles and config commands.\n- Add model metadata caching from OpenRouter so users can search models from the terminal.\n- Add signed release archives or Homebrew packaging once the CLI stabilizes.\n- Add CI with shellcheck, install smoke tests, and scripted setup tests.\n\n## Troubleshooting\n\nIf a command is not found:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\nrehash\n```\n\nIf Claude Code authenticates against Anthropic instead of OpenRouter, check:\n\n```bash\nclaude-openrouter --print-env claude\n```\n\nYou should see:\n\n```bash\nANTHROPIC_BASE_URL=https://openrouter.ai/api\nANTHROPIC_API_KEY=\nANTHROPIC_AUTH_TOKEN=<redacted>\n```\n\nIf a non-Claude profile behaves strangely, retry with:\n\n```bash\nclaude-openrouter claude\n```\n\nThat profile uses Anthropic first-party Claude models through OpenRouter and is the intended compatibility path.\n\n## References\n\n- [OpenRouter Claude Code integration](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration)\n- [OpenRouter models](https://openrouter.ai/models)\n- [Claude Code](https://code.claude.com)\n"}}}} |