Locations and precedence
Zimster reads configuration from several layers. The highest-priority value wins: an explicit dispatch override, a per-run --config, Git-local project configuration, user configuration, host-native configuration, then inheritance from the parent session.
User configuration lives at $XDG_CONFIG_HOME/zimster/config.json or $HOME/.config/zimster/config.json on Linux, $HOME/Library/Application Support/Zimster/config.json on macOS, and %APPDATA%\Zimster\config.json on Windows. Project configuration is stored under the Git administrative path returned by git rev-parse --git-path zimster/config.json.
Zimster reads these files; it doesn't rewrite your active model or host settings. Each run keeps a snapshot of the configuration it actually used.
Routing modes and policies
Routing only happens after Zimster decides another agent is worth using. The mode controls what happens next:
inherit: request no model or effort override.recommend: report a mapped recommendation, but let the delegated session inherit its model.map_only: use only a candidate you explicitly mapped.auto_within_policy: choose among mapped, available candidates according to policy.
Policies are quality_first, balanced, and cost_optimized. strict_cost works only with cost_optimized. If the host cannot prove that the requested model was enforced, optional work stays with the owner. Required independent review stops until there is an explicit policy exception.
Role classes
A role and a model are separate choices. Zimster ships with four classes: economy, balanced, expert, and inherit.
| Role | Default class | Typical work |
|---|---|---|
| Scout | economy | Bounded discovery and mechanical inventory. |
| Bounded implementer | balanced | Independent implementation slices. |
| Test reviewer | balanced | One named verification command or focused test review. |
| Integration reviewer | expert | Architecture, security, compatibility, and final integration review. |
| Diagnostician | expert | Difficult failures after repeated owner attempts. |
You can override the class for any named role with routing.role_classes.
Model mappings
routing.mappings is where you choose the actual model used for each class. A candidate requires a model string and may also specify provider, effort, ranking values, allowed harnesses, minimum host version, required capabilities, and declared availability.
Use map_only when you want a mapped model to be the only eligible override. Use auto_within_policy when you want Zimster to rank multiple candidates inside the policy you selected. Ties keep declaration order.
Requested and effective model IDs remain separate. Zimster reports an effective model only when the host exposes that information.
Configuration example
This maps discovery to an economy model, most implementation and test review to a balanced model, and integration review or diagnosis to an expert model. Replace the placeholder IDs with models your host supports.
{ "schema_version": 1, "routing": { "mode": "map_only", "policy": "balanced", "strict_cost": false, "role_classes": { "scout": "economy", "bounded_implementer": "balanced", "test-reviewer": "balanced", "integration-reviewer": "expert", "diagnostician": "expert" }, "mappings": { "economy": [ { "model": "economy-model-id" } ], "balanced": [ { "model": "balanced-model-id", "effort": "high" } ], "expert": [ { "model": "expert-model-id", "effort": "high" } ] } }, "autonomous_convergence": { "enabled": true, "limits": { "correction_commits": 2, "final_verification_attempts": 2, "complete_suite_executions": 3, "exact_duplicate_commands": 2, "context_renewals": 2 } }}Validate a configuration with node scripts/model-routing.mjs validate-config --config <path>.
Execution budgets and review lifecycle
Execution limits and review limits are separate. A review does not get more attempts because some other counter changed.
| Execution budget | Limit | Boundary |
|---|---|---|
| Correction commits | 2 | Hard stop |
| Final verification attempts | 2 | Hard stop |
| Complete-suite executions | 3 | Hard stop |
| Exact duplicate commands | 2 | Repetition is surfaced and capped |
| Context renewals | 2 | Additional renewal is escalated |
Review has its own limits: one correction recheck per cycle, at most two cycles for the same seam, and one strategy restart. Final review waits for a stable head. If that review forces a correction, one more review of the corrected head is available.
An initial review gets one owner correction and one recheck by the same reviewer. If a load-bearing problem remains, the circuit breaker trips. The owner may try one genuinely different strategy and run a second review cycle. If that still fails on a load-bearing problem, the run ends as BLOCKED.
Hard execution limits win over a host's goal or continue setting. Zimster also stops for scope expansion, sensitive decisions without authority, required approval, missing required review, contradictory requirements, or exhausted limits.
Local records
Run state lives under the repository's Git administrative directory by default. It keeps the current slice, routing decisions, review history, checkpoints, and verification records tied to the Git state that produced them.
Zimster contains no upload or telemetry mechanism for those records.