{"id":50525486,"url":"https://github.com/sidrat2612/routesmith","last_synced_at":"2026-06-03T07:31:02.243Z","repository":{"id":356240856,"uuid":"1231596975","full_name":"sidrat2612/routesmith","owner":"sidrat2612","description":"Host-aware model routing for coding agents. Python library + MCP server for Claude Code, Codex, Gemini CLI, Copilot, Cursor, and Aider.","archived":false,"fork":false,"pushed_at":"2026-05-07T08:06:21.000Z","size":118,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T08:39:04.017Z","etag":null,"topics":["agentic-workflows","ai-agents","aider","capability-routing","claude-code","codex","coding-agents","copilot","cursor","gemini-cli","host-aware","host-detection","llm","mcp","mcp-server","model-context-protocol","model-routing","prompt-routing","python","task-routing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/routesmith/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sidrat2612.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T05:34:18.000Z","updated_at":"2026-05-07T08:35:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sidrat2612/routesmith","commit_stats":null,"previous_names":["sidrat2612/routesmith"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sidrat2612/routesmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Froutesmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Froutesmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Froutesmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Froutesmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sidrat2612","download_url":"https://codeload.github.com/sidrat2612/routesmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidrat2612%2Froutesmith/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33853983,"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-06-03T02:00:06.370Z","response_time":59,"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":["agentic-workflows","ai-agents","aider","capability-routing","claude-code","codex","coding-agents","copilot","cursor","gemini-cli","host-aware","host-detection","llm","mcp","mcp-server","model-context-protocol","model-routing","prompt-routing","python","task-routing"],"created_at":"2026-06-03T07:31:01.683Z","updated_at":"2026-06-03T07:31:02.234Z","avatar_url":"https://github.com/sidrat2612.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eRouteSmith\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eHost-aware auto-routing for coding agents\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/routesmith/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/routesmith?color=blue\u0026label=PyPI\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sidrat2612/routesmith/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/sidrat2612/routesmith?display_name=tag\u0026label=GitHub%20Release\" alt=\"GitHub Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sidrat2612/routesmith/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/sidrat2612/routesmith/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/routesmith/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/routesmith\" alt=\"Python versions\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sidrat2612/routesmith/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/sidrat2612/routesmith\" alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sidrat2612/routesmith/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/sidrat2612/routesmith?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n**routesmith** automatically routes coding agent tasks to the best available model in your IDE — no manual model picking, no cross-provider hacks.\n\n\u003e Give it a mixed prompt like *\"Plan this feature, implement it, add tests, write docs\"* and it decomposes, routes each step to the right capability class, and executes using your host's native model switching.\n\n![RouteSmith hero — one prompt branches into multiple task-specific workstreams](https://raw.githubusercontent.com/sidrat2612/routesmith/main/assets/hero.png)\n\n## Why?\n\nMost coding agents are stuck on one model. Mixed tasks (plan -\u003e code -\u003e test -\u003e document) benefit from different model strengths. But each IDE host (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Aider) has different model families and switching capabilities.\n\n**routesmith solves this** by being host-aware:\n\n| Host | Models | Strategy |\n|------|--------|----------|\n| Claude Code | Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5 | Dynamic model switching |\n| Codex | GPT-5.5 / GPT-5.4 / GPT-5.3-Codex | Dynamic model switching |\n| Gemini CLI | Gemini 3.1 Pro / Flash / Flash-Lite | Dynamic model switching |\n| Copilot | Claude 4.7 / GPT-5.5 / Gemini 3.1 Pro (plan-dependent) | Prompt optimization |\n| Cursor | Claude 4.7 / GPT-5.5 / GPT-5.3-Codex / Gemini 3.1 Pro | Prompt optimization |\n| Aider | Claude 4.7 / GPT-5.5 / Gemini 3.1 Pro | Dynamic model switching |\n\n![Where RouteSmith fits — agent products, routing layer, API gateway infrastructure](https://raw.githubusercontent.com/sidrat2612/routesmith/main/assets/positioning.png)\n\n## Quickstart\n\nInstall from PyPI with `pip install routesmith`.\n\nIf PyPI is unavailable or you want to install from the GitHub-hosted release artifacts instead, use the latest release source archive:\n\nUse `pip install https://github.com/sidrat2612/routesmith/releases/latest/download/routesmith-latest.tar.gz`.\n\nDirect downloads:\n\n- [Latest GitHub release page](https://github.com/sidrat2612/routesmith/releases/latest)\n- [Latest wheel asset](https://github.com/sidrat2612/routesmith/releases/latest/download/routesmith-latest-py3-none-any.whl)\n- [Latest source asset](https://github.com/sidrat2612/routesmith/releases/latest/download/routesmith-latest.tar.gz)\n\nCore Python entry points:\n\n- `routesmith.run(...)` auto-detects the host, decomposes the prompt, and executes the route.\n- `routesmith.explain_route(...)` shows the route plan without execution.\n- `routesmith.detect_host()` and `routesmith.get_host_capabilities()` expose the detected environment.\n\n### CLI\n\nCommon CLI commands:\n\n- Route a mixed task prompt with `routesmith run \"Plan this feature, implement it, add tests, and write docs\"`.\n- Preview the route plan with `routesmith explain \"Refactor auth module and add integration tests\"`.\n- Inspect the environment with `routesmith detect-host`, `routesmith capabilities`, and `routesmith doctor`.\n- View performance stats with `routesmith stats`, filter with `--host`, `--capability`, `--source`, or export with `--format json`.\n- Show top/bottom performers with `routesmith stats --top 5 --bottom 3`.\n- Prune old telemetry with `routesmith stats --prune --max-age-days 30`.\n\n## How It Works\n\nroutesmith is an **advisory routing layer** — it plans and recommends, it does not replace your host's execution engine.\n\nExecution flow:\n\n1. Detect the active host, such as Claude Code or Copilot.\n2. Decompose the prompt into typed subtasks.\n3. Map each task to a capability class.\n4. Resolve those capabilities to host-native models.\n5. Switch models when possible, or optimize prompts when not.\n6. Report metrics, advisory messages, and effectiveness.\n\n![RouteSmith routing flow — detect host, classify prompt, map capability, route, execute, telemetry feedback](https://raw.githubusercontent.com/sidrat2612/routesmith/main/assets/flow.png)\n\n### What it does\n\n- **Decomposes** mixed prompts into discrete, typed subtasks\n- **Routes** each subtask to the best capability class (`deep_reasoning`, `coding`, `balanced`, `fast`)\n- **Switches models** when the host supports it (Claude Code, Codex, Gemini CLI, Aider)\n- **Applies routing preferences** such as `cost` or `quality` on the same router path\n- **Runs Python policy plugins** when you need logic beyond static remaps\n- **Falls back to prompt optimization** when the host controls model selection\n- **Reports** timing, token estimates, effectiveness scores\n\n### What it does NOT do\n\n- Does **not** make LLM API calls — the host handles execution\n- Does **not** bypass host constraints — works within your IDE's limits\n- Does **not** fake model switches — tells you honestly what happened\n\n### Design Philosophy\n\nCoding agents run inside a host that owns the LLM connection. routesmith sits *alongside* the host as a skill layer that makes smarter routing decisions. It's the routing brain, not the execution muscle.\n\n## Capability Classes\n\nInstead of hardcoding model names, routesmith uses abstract capability classes:\n\n| Class | Use Case | Example Models |\n|-------|----------|----------------|\n| `deep_reasoning` | Planning, architecture, review | Claude Opus 4.7, GPT-5.5 |\n| `coding` | Implementation, testing, refactoring | Claude Sonnet 4.6, GPT-5.3-Codex |\n| `balanced` | Documentation, general tasks | Claude Sonnet 4.6, GPT-5.4 |\n| `fast` | Formatting, simple transforms | Claude Haiku 4.5, GPT-5.4-mini |\n\nEach host adapter maps these to actual available models.\n\n## Task Types\n\nroutesmith classifies prompts into: `planning`, `analysis`, `coding`, `testing`, `refactor`, `documentation`, `formatting`, `review`\n\nDependencies are resolved automatically — tests wait for code, docs wait for implementation.\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `ROUTESMITH_DEFAULT_MODE` | Execution mode | `auto` |\n| `ROUTESMITH_ALLOW_MODEL_SWITCH` | Allow model switching | `true` |\n| `ROUTESMITH_FORCE_HOST` | Force a specific host | — |\n| `ROUTESMITH_DEBUG` | Enable debug output | `false` |\n| `ROUTESMITH_PERFORMANCE_ROUTING` | Enable performance-aware model selection | `true` |\n| `ROUTESMITH_PERFORMANCE_FILE` | Performance telemetry store path | `.routesmith/performance.json` |\n| `ROUTESMITH_PERFORMANCE_MAX_RECORDS` | Max stored telemetry records | `500` |\n| `ROUTESMITH_PERFORMANCE_MAX_AGE_DAYS` | Optional age-based pruning window | — |\n| `ROUTESMITH_CONTEXT_WINDOW_LIMIT` | Prefer leaner context defaults for supported hosts | `true` |\n| `ROUTESMITH_AUTOCOMPACT_THRESHOLD` | Auto-compaction threshold percentage for supported hosts | `80` |\n| `ROUTESMITH_MAX_SPAWN_DEPTH` | Advisory max subagent nesting depth written into host configs | `2` |\n\n### Config File\n\nCreate `.routesmith.toml` in your project root:\n\nExample:\n\n```toml\n[routesmith]\ndefault_mode = \"auto\"\nallow_model_switch = true\nrouting_preference = \"cost\"\n\n# Performance-aware routing\nperformance_routing_enabled = true\nperformance_store_file = \".routesmith/performance.json\"\nperformance_max_records = 500\nperformance_max_age_days = 30\n\n# Token-efficiency knobs\ncontext_window_limit = true\nautocompact_threshold = 80\nmax_spawn_depth = 2\n\n# Optional Python hooks\npolicy_plugins = [\n  \"my_project.routing:plugin\",\n  \"my_project.routing:CustomPlugin\",\n]\n\n[routesmith.policy_overrides]\nplanning = \"balanced\"\ndocumentation = \"fast\"\n```\n\nWhat the new knobs do:\n\n- `context_window_limit = true` tells install adapters to prefer leaner context defaults when the host exposes a real setting. Today this produces concrete settings for Claude Code and advisory guidance for the other hosts.\n- `autocompact_threshold = 80` lowers the context usage percentage at which auto-compaction should kick in for hosts that support it. Today Claude Code uses this to write `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`.\n- `max_spawn_depth = 2` controls the advisory spawn-depth limit written into generated host instruction files so subagents do not recurse into wasteful coordination trees.\n\nRecommended config shape:\n\n- Add a `[routesmith]` section with values such as `default_mode = \"auto\"`, `allow_model_switch = true`, and `routing_preference = \"cost\"` when you want cheaper model selection.\n- Add token-efficiency settings such as `context_window_limit`, `autocompact_threshold`, and `max_spawn_depth` when you want generated host configs to bias toward smaller contexts and shallower delegation.\n- Add a `[routesmith.policy_overrides]` section when you want static remaps such as `planning = \"balanced\"` or `documentation = \"fast\"`.\n- Add a `policy_plugins` list when you want importable Python hooks such as `my_project.routing:plugin` or `my_project.routing:CustomPlugin` to participate in route resolution.\n- Add performance settings such as `performance_routing_enabled = true`, `performance_store_file = \".routesmith/performance.json\"`, `performance_max_records = 500`, and `performance_max_age_days = 30` when you want tighter telemetry control.\n\nBuilt-in routing preferences are `balanced`, `cost`, and `quality`. `policy_overrides` handles static remaps, while `policy_plugins` lets you run real Python logic that can adjust capability classes, force explicit models, and attach advisory messages.\n\n## MCP / Stdio Server\n\nroutesmith exposes an MCP-compatible JSON-RPC 2.0 server for tool integration:\n\nStart it with `routesmith serve-stdio`.\n\nThis lets IDE extensions and agents call routesmith as a tool.\n\nThe MCP surface now includes `routesmith.performance`, which returns filtered performance summaries for CLI and agent consumers.\n\n## Performance Tracking\n\nroutesmith records per-model task outcomes across runs, including duration, success or failure, capability class, host, and telemetry source. Data is stored in `.routesmith/performance.json`, uses schema versioning with migration support, and separates runtime telemetry from synthetic test data.\n\nPerformance-aware routing now promotes tracker data from passive advisory to an active routing signal. When a default model shows weak success or latency for a capability and a better host-available alternative has enough evidence, routesmith will switch to the stronger performer.\n\nView stats with `routesmith stats`. You can filter by model, host, capability, and telemetry source; show top and bottom performers; export JSON summaries; and prune old records with max-record or max-age controls.\n\nWhen a model's historical success rate drops below 70% or average latency exceeds 5 seconds, routesmith still injects performance advisory messages into run results automatically.\n\n## Install Configs for Hosts\n\nGenerate host-specific configuration files:\n\n- `routesmith install claude` writes `CLAUDE.md` and merges token-saving settings into `.claude/settings.json`.\n- `routesmith install codex` writes `AGENTS.md`.\n- `routesmith install gemini` writes `GEMINI.md`.\n- `routesmith install copilot` writes `.github/copilot-instructions.md`.\n- `routesmith install cursor` writes `.cursorules`.\n- `routesmith install aider` writes `.aider.conf.yml`, or `.aider.routesmith.yml` if an existing Aider config is already present.\n\n## Auto Mode (Default)\n\nAuto mode is the default. For a single mixed prompt, routesmith:\n\n1. Detects the host environment\n2. Classifies the prompt into task types\n3. Splits into ordered subtasks with dependency resolution\n4. Chooses the best host-compatible model per subtask\n5. Executes (or recommends) the route\n6. Returns metrics and advisory messages\n\n### Truthful Switching\n\n- If the host supports dynamic switching → routesmith switches\n- If the host does NOT support switching → routesmith uses prompt strategy\n- The result always tells you exactly what happened — no black boxes\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nDevelopment setup:\n\n1. Clone the repository from `https://github.com/sidrat2612/routesmith.git`.\n2. Change into the `routesmith` directory.\n3. Create and activate a virtual environment with `python -m venv .venv` and `source .venv/bin/activate`.\n4. Install dev dependencies with `pip install -e \".[dev]\"`.\n5. Run the test suite with `pytest`.\n\n## Roadmap\n\n- [x] Host detection and capability mapping\n- [x] Weighted task decomposition planner\n- [x] Dependency-aware execution loop\n- [x] Persistent route state\n- [x] MCP stdio server\n- [x] Structured observability\n- [x] Config-driven policy overrides\n- [x] Cost-aware routing\n- [x] Python policy plugins\n- [x] Gemini CLI host adapter\n- [x] Real-time model performance tracking\n- [x] Performance-aware routing (active model switching based on tracked data)\n- [x] Expanded stats UX (host/capability/source filters, JSON export, ranked performers)\n- [x] Data store hardening (schema v2, migration, source-aware pruning)\n- [x] Release workflow hardening (concurrency, idempotent publish)\n- [ ] Additional host adapters\n\n## License\n\n[MIT](LICENSE) — use it anywhere.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt for the multi-model future of coding agents.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidrat2612%2Froutesmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsidrat2612%2Froutesmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidrat2612%2Froutesmith/lists"}