{"id":51351283,"url":"https://github.com/farhanic017/auto-model-switcher","last_synced_at":"2026-07-02T16:06:39.426Z","repository":{"id":359356852,"uuid":"1245327283","full_name":"farhanic017/auto-model-switcher","owner":"farhanic017","description":"Parallel model rotation across any CLI. Auto-discovers models, health-checks in \u003c2s, scores by capability+cost, picks the best for every task.","archived":false,"fork":false,"pushed_at":"2026-06-07T17:34:00.000Z","size":4347,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T19:15:06.997Z","etag":null,"topics":["ai","ai-agents","ai-cli","aider","claude-code","cursor","gemini-cli","llm","local-llm","mcp","model-fallback","model-router","model-switcher","ollama","opencode","openrouter","python","quota-management","qwen","token-limit"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/farhanic017.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T05:56:50.000Z","updated_at":"2026-06-07T17:46:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/farhanic017/auto-model-switcher","commit_stats":null,"previous_names":["farhanic017/auto-model-switcher"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/farhanic017/auto-model-switcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farhanic017%2Fauto-model-switcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farhanic017%2Fauto-model-switcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farhanic017%2Fauto-model-switcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farhanic017%2Fauto-model-switcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/farhanic017","download_url":"https://codeload.github.com/farhanic017/auto-model-switcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farhanic017%2Fauto-model-switcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35053603,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-cli","aider","claude-code","cursor","gemini-cli","llm","local-llm","mcp","model-fallback","model-router","model-switcher","ollama","opencode","openrouter","python","quota-management","qwen","token-limit"],"created_at":"2026-07-02T16:06:38.317Z","updated_at":"2026-07-02T16:06:39.415Z","avatar_url":"https://github.com/farhanic017.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto Model Switcher - AI CLI Fallback for OpenCode, Claude Code, Aider, Cursor\n\n**Never get blocked by \"out of credits\" again.** Auto Model Switcher is an\nalways-on AI model fallback engine for OpenCode, Claude Code, Aider, Cursor,\nWindsurf, Qwen, Gemini CLI, OpenRouter, OpenAI-compatible APIs, and local LLMs.\nIt discovers your models, learns which ones you use, detects quota/token/usage\nfailures at runtime, switches to the next best healthy model, and retries the\noriginal command once.\n\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)]()\n[![Python](https://img.shields.io/badge/python-3.10%2B-green)]()\n[![License](https://img.shields.io/badge/license-GPLv3-purple)](LICENSE)\n[![Author](https://img.shields.io/badge/author-Farhan%20Dhrubo-red)](https://github.com/farhanic017)\n\n## Live Demo\n\nThis preview shows the full model fallback flow: active AI CLI\nsession, quota failure detection, depleted-model cooldown, provider routing,\ntask-aware scoring, learned usage preferences, config update, retry, and final\nverification without a manual restart.\n\n![Auto Model Switcher live demo preview](assets/auto-model-switcher-live-demo.gif)\n\n## Why Developers Star It\n\n- **Fixes the most annoying AI CLI failure:** `429`, `402`, quota exceeded, no credits, token exhausted, free-tier limit.\n- **Works across agents and IDEs:** OpenCode, Claude Code, Cursor, VS Code, Windsurf, Aider, Gemini CLI, Qwen CLI, Codex-style agents, and MCP configs.\n- **Supports every configured provider:** OpenRouter, OpenAI, Anthropic, Google AI, Azure OpenAI, Groq, Mistral, DeepSeek, xAI, Perplexity, Together, Fireworks, Cerebras, SambaNova, NVIDIA, Hugging Face, local OpenAI-compatible servers, Ollama, LM Studio, vLLM, LocalAI, Jan, llama.cpp, text-generation-webui.\n- **Learns your model habits:** healthy models you use successfully get a small preference boost.\n- **No manual restart:** the wrapper marks the failed model depleted, switches, and retries the original command once.\n\n**Search keywords:** AI model switcher, OpenRouter quota fallback, Claude Code fallback model, OpenCode model switcher, Aider model fallback, Cursor AI model router, local LLM fallback, MCP model discovery, OpenAI-compatible model router, auto switch AI models.\n\n---\n\n## Drop-in Install\n\nGive this repo URL to **any AI agent** and say \"install\":\n\n```\nhttps://github.com/farhanic017/auto-model-switcher\n```\n\nThe AI reads `SKILL.md`, clones, installs, and configures everything.\nZero manual steps.\n\n### Manual Install\n\n```bash\ngit clone https://github.com/farhanic017/auto-model-switcher.git\ncd auto-model-switcher\npython install.py\n```\n\n---\n\n## The Problem\n\nYou're in the middle of work and suddenly get rate-limited or hit 0 credits.\nNow you have to: stop, check which models have credits, dig into config files,\nmanually switch, and restart. **Every. Single. Time.**\n\n## The Solution\n\n```\npython switcher.py watch\n```\n\nScans your CLI configs (OpenCode, Claude Code, Cursor, Windsurf, Aider, etc.),\ndiscovers every model you have access to, checks their health in parallel, and\nwhen one fails - automatically rotates to the next working model.\n\n**Free models get priority.** Paid models are fallbacks. Zero config needed.\n\n---\n\n## Supported Providers (all configured models auto-discovered)\n\n| Provider | Models | Detection | Priority |\n|----------|--------|-----------|----------|\n| Google AI (free) | 4 Gemini models | Config + env | 1st - free |\n| OpenRouter (free) | 30+ free models | `:free` suffix | 2nd - free |\n| OpenRouter (paid) | 4+ paid models | No `:free` | 3rd - paid |\n| Azure OpenAI | 10+ deployments | `azure-openai` provider | 4th - paid |\n| OpenAI | Any GPT model | `OPENAI_API_KEY` env | Fallback |\n| Anthropic | Claude models | `ANTHROPIC_API_KEY` env | Fallback |\n| OpenAI-compatible APIs | Any configured model | `*_API_KEY` + `*_MODEL(S)` + optional `*_BASE_URL` | Fallback |\n| Groq, Mistral, DeepSeek, xAI, Perplexity, Together, Fireworks, Cerebras, SambaNova, NVIDIA, Hugging Face | Any configured model | Provider env vars or agent/IDE configs | Fallback |\n\n### Local Models (auto-detected)\n\n| Runtime | Endpoint | Detection |\n|---------|----------|-----------|\n| **Ollama** | `http://localhost:11434` | Auto-scans, lists all models |\n| **LM Studio** | `http://localhost:1234` | Auto-scans `/v1/models` |\n| **vLLM** | `http://localhost:8000` | Auto-scans `/v1/models` |\n| **LocalAI / Jan / llama.cpp / text-generation-webui** | Common local OpenAI-compatible ports | Auto-scans `/v1/models` |\n\n---\n\n## Commands\n\n| Command | What it does |\n|---------|-------------|\n| `python switcher.py discover` | Scans all configs + env, lists every model found |\n| `python switcher.py status` | Shows active model, health, depletion ETAs |\n| `python switcher.py switch --task coding` | Picks best model for a task (coding/chat/reasoning/general) |\n| `python switcher.py run opencode -- opencode ...` | Runs a CLI with failure detection, auto-switch, and one retry |\n| `python switcher.py doctor` | Runs local diagnostics for state, configs, wrappers, and CLIs |\n| `python switcher.py watch` | Background daemon - checks every 2min, auto-rotates |\n\n### Or use the `ams` command after install:\n\n```bash\nams status      # Same as above\nams switch      # Rotate to best model\nams watch       # Background daemon\nams discover    # List all models\n```\n\n---\n\n## Task-Aware Model Selection\n\nThe switcher doesn't just pick a random model - it picks the **best model for\nwhat you're doing**:\n\n| Task | Models preferred | Example scores |\n|------|-----------------|---------------|\n| **coding** | qwen3-coder, gpt-4.1, deepseek-coder | 55 bonus |\n| **reasoning** | o4, o3, deepseek-r1, kimi, qwen3-next | 50 bonus |\n| **chat** | gemma-4, nemotron, gpt-5.4, llama-3.3 | 40 bonus |\n| **general** | Falls back to capability tiers | 15-25 bonus |\n\nAuto-detects task from project files (`package.json`, `*.py`, `requirements.txt`,\n`Cargo.toml`, etc.) or use `--task` to override.\n\n---\n\n## How It Works\n\n### 1. Auto-Discovery\n\nReads your existing CLI configs - no extra setup:\n\n- **OpenCode**: `opencode.jsonc` - extracts all `provider` sections\n- **Claude Code**: `CLAUDE.md` - extracts `model:` line\n- **Cursor / VS Code / Windsurf**: workspace and user `settings.json`, `.cursor/mcp.json`, `.vscode/mcp.json`\n- **Continue.dev / Aider / Codex / other agents**: JSON/JSONC/TOML configs with `model`, `models`, `provider`, `baseURL`, or `apiKey`\n- **MCP local configs**: `mcp.json`, `.mcp.json`, `.claude/mcp.json`, `.cursor/mcp.json` and `mcpServers[*].env`\n- **Environment**: known provider keys plus generic `FOO_API_KEY`, `FOO_MODEL(S)`, optional `FOO_BASE_URL`\n\n### 2. Parallel Health Checking (\u003c5s)\n\nAll discovered models checked simultaneously via connection-pooled session:\n\n| Optimization | Impact |\n|-------------|--------|\n| Connection pooling (keep-alive) | Eliminates TCP handshake per check |\n| Cache for ALL healthy models (120s TTL) | Subsequent calls near-instant |\n| Reduced timeouts (4s-5s) | Worst case bound at 5s |\n| Deduplication by API key | One check per provider, not per model |\n\nBefore optimization: **~19s**. After: **~5s first call, ~0.1s cached calls**.\n\n### 3. Smart Scoring (0-250)\n\nEach model scored on: health (base 100) + free tier bonus (+50) + specialty\nstrength (+up to 55) + reliability (+15 Azure, -5 free OpenRouter).\n\n### 4. Rotation \u0026 Recovery\n\n- Failed models marked **depleted** with cooldown (respects `Retry-After` header)\n- CLI config updated automatically (`opencode.jsonc` `model` field)\n- Runtime CLI failures are classified for quota/usage/rate-limit errors, then the active model is marked depleted, the next best model is selected, and the command is retried once\n- The switcher learns which models the user has discovered and which ones they use successfully most often; those models get a small preference bonus when healthy\n- After cooldown, model is re-checked and re-enters pool if healthy\n- When ALL models depleted: shows **per-model recovery ETA** sorted fastest-first\n\n---\n\n## Context Passing (MCP Handoff)\n\nWhen switching models mid-session, the switcher preserves:\n\n- Which tools already executed (so new model doesn't repeat)\n- Which files were modified\n- Last 5 terminal commands\n- Conversation summary\n\nSaved to `~/.auto-model-switcher/context.json` for the next model to read.\n\n---\n\n## Always-On Integration\n\n| Method | What it does |\n|--------|-------------|\n| **PowerShell Profile Hook** | Checks health on every shell start (\u003c2s) |\n| **PATH Wrappers** | `.bat` files intercept `opencode`/`claude`/`cursor`/`aider`/`windsurf` calls |\n| **Watch Mode** | Background daemon checks every 2min, auto-rotates on failure |\n| **Startup Task** | Windows Task Scheduler launches watch on boot |\n| **WMI Watchdog** | Invisible background process, starts/stops with opencode.exe |\n| **Desktop Shortcuts** | One-click status, switch, watch |\n\n### Adding a new CLI\n\nThe auto-switch wrapper system is **future-proof**. To add support for any new\nCLI or agent:\n\n1. Add its path to `install.py` -\u003e `clis` dict (around line 119)\n2. Re-run `python install.py`\n3. Or manually create a `.bat` wrapper in `~/.auto-model-switcher/bin/`\n\nThe architecture is designed so **any future CLI, agent, or MCP server** can\nbe added by simply registering its path.\n\n---\n\n## For AI Agents (Drop-in Install)\n\nGive this repo URL to **any AI assistant**:\n\n```\nhttps://github.com/farhanic017/auto-model-switcher\n```\n\nThe AI reads `SKILL.md` and handles everything: cloning, installing, configuring.\n\n---\n\n## Project Structure\n\n```\nauto-model-switcher/\n|-- switcher.py          # Core engine (2,076 lines)\n|-- install.py           # Universal installer\n|-- restore.ps1          # Windows restore script\n|-- SKILL.md             # AI agent instructions\n|-- README.md            # This file\n|-- LICENSE              # GPL-3.0\n|-- NOTICE               # Copyright and legal notices\n|-- .gitignore\n|-- data/                # Runtime state templates\n|-- hooks/               # CLI integration hooks\n`-- tests/\n    |-- test_switcher.py # 39 test cases, all passing\n    `-- debug_speed.py   # Performance profiler\n```\n\n---\n\n## Versions \u0026 Release History\n\n| Version | Date | What shipped |\n|---------|------|--------------|\n| v3 current | June 7, 2026 | Runtime model-switching brain, quota/token/usage failure detection, depleted-model cooldown, learned usage preferences, task-aware scoring, provider fallback, config update, command retry, doctor diagnostics, README SEO refresh, and the 14-second 60 fps demo video. |\n| v2 | June 6, 2026 | Parallel health checks, shared HTTP session reuse, model health caching, sub-5-second timeout target, future-proof wrapper scripts, Windows shell integration, copyright headers, and defensive lock/edge-case fixes. |\n| v1 baseline | May 20, 2026 | Core always-on model rotation engine, provider discovery, local model discovery, CLI wrappers, installer, restore script, AI-agent install skill, state template, and test coverage for switching behavior. |\n\n| Component | Current version |\n|-----------|-----------------|\n| Auto Model Switcher engine | v3 current |\n| Python runtime | 3.10+ |\n| Demo video | 14 seconds, 60 fps, 1280x720 MP4 plus GitHub-safe animated preview |\n| Tested CLI matrix | Updated June 7, 2026 |\n| Target platforms | Windows, macOS, Linux |\n\n### Validated local CLI versions\n\nTested on June 7, 2026:\n\n| Tool | Version |\n|------|---------|\n| OpenCode | 1.16.0 |\n| Claude Code | 2.1.142 |\n| Gemini CLI | 0.45.1 |\n| Qwen CLI | 0.17.1 |\n| Cursor | 3.5.33 |\n| VS Code | 1.121.0 |\n| Aider | 0.86.2 |\n| Windsurf | 1.110.1 |\n| FFmpeg | 8.1.1 |\n\n---\n\n## Copyright \u0026 License\n\n**Copyright (c) 2026 Farhan Dhrubo** - All rights reserved.\n\nThis project is licensed under the **GNU General Public License v3.0**.\nSee [LICENSE](LICENSE) and [NOTICE](NOTICE) for full details.\n\n**You may NOT:**\n- Remove or alter any copyright notice in any file\n- Re-distribute this software or any derivative as your own work\n  without clear attribution to the original author\n- Sell this software or any derivative without explicit permission\n\n**Required attribution:** Any use, distribution, or derivative work MUST include:\n\"Originally created by Farhan Dhrubo (github.com/farhanic017)\"\n\nEvery source file in this repository contains an embedded copyright notice\nmaking the origin unambiguous. The GPL-3.0 license ensures all derivative\nworks remain open-source and properly attributed.\n\n---\n\n*Built with Python, caffeine, and the frustration of getting 402 errors\nmid-session.*\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarhanic017%2Fauto-model-switcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarhanic017%2Fauto-model-switcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarhanic017%2Fauto-model-switcher/lists"}