Title: Customizable model-mapping config with CLI-managed defaults and user overrides · Issue #987 · github/squad · GitHub
Open Graph Title: Customizable model-mapping config with CLI-managed defaults and user overrides · Issue #987 · github/squad
X Title: Customizable model-mapping config with CLI-managed defaults and user overrides · Issue #987 · github/squad
Description: Squad already has model-selection concepts such as defaultModel, agentModelOverrides, economy mode, and session alignment, but it still lacks an explicit user-facing config for task-to-model mapping. Right now, users who want a policy su...
Open Graph Description: Squad already has model-selection concepts such as defaultModel, agentModelOverrides, economy mode, and session alignment, but it still lacks an explicit user-facing config for task-to-model mappin...
X Description: Squad already has model-selection concepts such as defaultModel, agentModelOverrides, economy mode, and session alignment, but it still lacks an explicit user-facing config for task-to-model mappin...
Opengraph URL: https://github.com/github/squad/issues/987
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Customizable model-mapping config with CLI-managed defaults and user overrides","articleBody":"Squad already has model-selection concepts such as `defaultModel`, `agentModelOverrides`, economy mode, and session alignment, but it still lacks an explicit user-facing config for task-to-model mapping.\r\n\r\nRight now, users who want a policy such as:\r\n\r\n- coding -> `gpt-5.4`\r\n- heavy coding -> `gpt-5.3-codex`\r\n- architecture -> `gpt-5.4`\r\n- review -> `gemini-3-pro-preview`\r\n- docs -> `gpt-5.4-mini`\r\n- ui / vision -> `claude-opus-4.6`\r\n\r\nhave to edit generated docs, prompts, or internal routing rules instead of using a stable config surface.\r\n\r\nThis makes upgrades fragile, because the upgrade process can overwrite or reintroduce upstream model mappings that do not match the user's preferred routing strategy.\r\n\r\n## Problem\r\n\r\nThe missing piece is a first-class config file for task-category model mapping.\r\n\r\nCurrent pain points:\r\n\r\n1. There is no durable config for mapping task categories to preferred models.\r\n2. Users can set a single default model, but not an explicit routing table such as coding vs heavy coding vs review vs docs.\r\n3. Upgrades can reapply upstream defaults that conflict with local user preferences.\r\n4. Users end up patching generated files manually after upgrades.\r\n5. The current behavior mixes three concerns that should be separated:\r\n - Squad-maintained default routing\r\n - user-specific overrides\r\n - runtime session model alignment\r\n\r\n## Proposal\r\n\r\nAdd a dedicated model-mapping config file that supports:\r\n\r\n1. a `default` section managed by Squad CLI\r\n2. an `override` section managed by the user\r\n3. upgrade behavior that refreshes `default` but preserves `override`\r\n4. runtime resolution that merges `override` over `default`\r\n\r\n### Example config shape\r\n\r\n```json\r\n{\r\n \"version\": 1,\r\n \"modelMappings\": {\r\n \"default\": {\r\n \"coding-model\": \"gpt-5.4\",\r\n \"heavy-coding-model\": \"gpt-5.3-codex\",\r\n \"architecture-model\": \"gpt-5.4\",\r\n \"review-model\": \"gemini-3-pro-preview\",\r\n \"docs-model\": \"gpt-5.4-mini\",\r\n \"fast-model\": \"gpt-5.4-mini\",\r\n \"ui-model\": \"claude-opus-4.6\"\r\n },\r\n \"override\": {}\r\n }\r\n}\r\n```\r\n\r\n### Expected resolution rules\r\n\r\nAt runtime, Squad should resolve mappings in this order:\r\n\r\n1. explicit per-agent override if present\r\n2. `modelMappings.override.\u003ckey>`\r\n3. `modelMappings.default.\u003ckey>`\r\n4. platform/session fallback behavior\r\n\r\nThis would allow the CLI to ship sane defaults while still giving the user a stable, upgrade-safe place to customize routing.\r\n\r\n## Why `agentModelOverrides` is not enough\r\n\r\nThis proposal is intentionally different from the existing `agentModelOverrides` setting.\r\n\r\n`agentModelOverrides` is useful for pinning a specific named agent to a specific model, but it does not solve task-category routing.\r\n\r\nFor example, it can express:\r\n\r\n- `fenster -> gpt-5.4`\r\n- `mcmanus -> gpt-5.4-mini`\r\n\r\nBut it cannot express:\r\n\r\n- all coding tasks -> `gpt-5.4`\r\n- all heavy coding tasks -> `gpt-5.3-codex`\r\n- all review tasks -> `gemini-3-pro-preview`\r\n- all docs tasks -> `gpt-5.4-mini`\r\n\r\nThat distinction matters because agents can do different kinds of work over time, and the desired model choice is often based on task type rather than agent identity.\r\n\r\nSo the request here is not to replace `agentModelOverrides`, but to complement it:\r\n\r\n- `agentModelOverrides` for per-agent pinning\r\n- `modelMappings.default` for Squad-managed task routing defaults\r\n- `modelMappings.override` for user-managed task routing overrides\r\n\r\n## Upgrade behavior\r\n\r\nThe `squad upgrade` command should:\r\n\r\n1. create the config file if it does not exist\r\n2. update only the `default` section when upstream defaults change\r\n3. preserve the `override` section exactly as authored by the user\r\n4. optionally report when an override references a model not present in the current catalog\r\n5. avoid rewriting generated docs or prompt templates in a way that silently conflicts with user overrides\r\n\r\n## Suggested mapping keys\r\n\r\nThe exact names are negotiable, but the system should support keys like:\r\n\r\n- `coding-model`\r\n- `heavy-coding-model`\r\n- `architecture-model`\r\n- `review-model`\r\n- `docs-model`\r\n- `fast-model`\r\n- `ui-model`\r\n- `scribe-model`\r\n\r\nIf preferred, these could also be normalized to a nested structure such as:\r\n\r\n```json\r\n{\r\n \"modelMappings\": {\r\n \"default\": {\r\n \"coding\": \"gpt-5.4\",\r\n \"heavyCoding\": \"gpt-5.3-codex\",\r\n \"architecture\": \"gpt-5.4\",\r\n \"review\": \"gemini-3-pro-preview\",\r\n \"docs\": \"gpt-5.4-mini\",\r\n \"ui\": \"claude-opus-4.6\"\r\n },\r\n \"override\": {}\r\n }\r\n}\r\n```\r\n\r\n## Acceptance criteria\r\n\r\n1. Squad supports a dedicated config surface for task-category model mappings.\r\n2. Squad CLI installs a default mapping table.\r\n3. The user has a separate override section that starts empty.\r\n4. `squad upgrade` updates defaults without clobbering user overrides.\r\n5. Runtime model selection respects overrides before defaults.\r\n6. Documentation clearly explains which keys map to which task classes.\r\n7. The config is compatible with existing `defaultModel` and `agentModelOverrides` behavior, or a migration path is documented.\r\n\r\n## Related existing work\r\n\r\nThese look related and suggest the feature area already exists but is not yet exposed as a stable mapping config:\r\n\r\n- [#618](https://github.com/bradygaster/squad/issues/618) explicit model picker - aligned to sesson model\r\n- [#588](https://github.com/bradygaster/squad/issues/588) Update default AI model list to match current Copilot offerings\r\n- [#585](https://github.com/bradygaster/squad/issues/585) Economy Mode: Honest E2E Validation, Reliable Activation, and Cost Measurement\r\n- [#500](https://github.com/bradygaster/squad/issues/500) feat: Economy mode for cost-conscious model selection\r\n- [#491](https://github.com/bradygaster/squad/pull/491) fix: persist user model preference across sessions\r\n\r\n## Why this matters\r\n\r\nThis is primarily a request for a stable contract between:\r\n\r\n- upstream Squad defaults\r\n- local user preferences\r\n- the upgrade process\r\n\r\nWithout that contract, users end up maintaining downstream patches to generated model-selection content after every upgrade.\r\n","author":{"url":"https://github.com/iskandersierra","@type":"Person","name":"iskandersierra"},"datePublished":"2026-04-16T09:01:58Z","url":"https://github.com/github/squad/issues/987"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:b44e420d-ff9a-b246-40a0-ff2da25ec1a9 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B4FA:2E7EBB:2429C3D:2DB43AE:6B017D84 |
| html-safe-nonce | 4a84d184b521911080559c9531c59276e7ccf141845b3d67dd7236143a267dc3 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCNEZBOjJFN0VCQjoyNDI5QzNEOjJEQjQzQUU6NkIwMTdEODQiLCJ2aXNpdG9yX2lkIjoiODUzMzYxMDEwMDYxNzczOTY1MiIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 327e5078c007bd9ff6da85bbd73f4d169cb2b53354c1eab83468922a12de06d1 |
| hovercard-subject-tag | issue:4274464665 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/987/issue_layout |
| twitter:image | https://opengraph.githubassets.com/08bcfcf30a60710a9b73bfe73a67cc9863598df9d3e529a2925ea580859f401c/github/squad/issues/987 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/08bcfcf30a60710a9b73bfe73a67cc9863598df9d3e529a2925ea580859f401c/github/squad/issues/987 |
| og:image:alt | Squad already has model-selection concepts such as defaultModel, agentModelOverrides, economy mode, and session alignment, but it still lacks an explicit user-facing config for task-to-model mappin... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | iskandersierra |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/github/squad git https://github.com/github/squad.git |
| octolytics-dimension-user_id | 9919 |
| octolytics-dimension-user_login | github |
| octolytics-dimension-repository_id | 1151205052 |
| octolytics-dimension-repository_nwo | github/squad |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1151205052 |
| octolytics-dimension-repository_network_root_nwo | github/squad |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width