Release v0.1.8 with install guidance and review fixes

Author: sidrat2612

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.8] - 2026-05-09
+
+### Fixed
+- Renamed base exception class from `RouterSmitError` to `RoutesmithError` (typo fix).
+- Removed unused `import time` from `metrics.py` and `import os` from `state.py`.
+- Moved `import math` from inside function body to module level in `planner.py`.
+- Fixed TOML fallback parser not parsing float values (e.g. `7.5` stayed as a string).
+
+### Changed
+- `hosts/__init__.py` now exports all host adapters (Aider, ClaudeCode, Codex, Copilot, Cursor, GeminiCLI, Generic) instead of only GeminiCLI.
+
+## [0.1.7] - 2026-05-09
+
+### Added
+- Token-efficient install guidance for Claude Code, Codex, Gemini CLI, Copilot, Cursor, VS Code, and Aider with delegation tiers, spawn depth rules, preferred tool selection, and context-management recommendations.
+- Project-scoped Claude Code settings generation for `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` and `CLAUDE_CODE_DISABLE_1M_CONTEXT`, merged additively into `.claude/settings.json`.
+- Concrete Aider context defaults for chat history limits, prompt caching, and repo-map size.
+- New `SkillConfig` fields for `context_window_limit`, `autocompact_threshold`, and `max_spawn_depth`.
+- New `HostCapabilities.supports_context_management` flag.
+- Delegation-tier, task-complexity, and tool-cost advisories.
+- Install adapter tests covering Claude, Codex, Gemini, Copilot, Cursor, and Aider token-saving config output.
+
+### Changed
+- Aider installs now write `.aider.conf.yml` when safe and fall back to `.aider.routesmith.yml` when an existing config is already present.
+
 ## [0.1.6] - Unreleased
 
 ### Added

README.md

@@ -137,14 +137,54 @@ Dependencies are resolved automatically — tests wait for code, docs wait for i
 | `ROUTESMITH_PERFORMANCE_FILE` | Performance telemetry store path | `.routesmith/performance.json` |
 | `ROUTESMITH_PERFORMANCE_MAX_RECORDS` | Max stored telemetry records | `500` |
 | `ROUTESMITH_PERFORMANCE_MAX_AGE_DAYS` | Optional age-based pruning window | — |
+| `ROUTESMITH_CONTEXT_WINDOW_LIMIT` | Prefer leaner context defaults for supported hosts | `true` |
+| `ROUTESMITH_AUTOCOMPACT_THRESHOLD` | Auto-compaction threshold percentage for supported hosts | `80` |
+| `ROUTESMITH_MAX_SPAWN_DEPTH` | Advisory max subagent nesting depth written into host configs | `2` |
 
 ### Config File
 
 Create `.routesmith.toml` in your project root:
 
+Example:
+
+```toml
+[routesmith]
+default_mode = "auto"
+allow_model_switch = true
+routing_preference = "cost"
+
+# Performance-aware routing
+performance_routing_enabled = true
+performance_store_file = ".routesmith/performance.json"
+performance_max_records = 500
+performance_max_age_days = 30
+
+# Token-efficiency knobs
+context_window_limit = true
+autocompact_threshold = 80
+max_spawn_depth = 2
+
+# Optional Python hooks
+policy_plugins = [
+  "my_project.routing:plugin",
+  "my_project.routing:CustomPlugin",
+]
+
+[routesmith.policy_overrides]
+planning = "balanced"
+documentation = "fast"
+```
+
+What the new knobs do:
+
+- `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.
+- `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`.
+- `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.
+
 Recommended config shape:
 
 - 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.
+- 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.
 - Add a `[routesmith.policy_overrides]` section when you want static remaps such as `planning = "balanced"` or `documentation = "fast"`.
 - 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.
 - 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.
@@ -175,12 +215,12 @@ When a model's historical success rate drops below 70% or average latency exceed
 
 Generate host-specific configuration files:
 
-- `routesmith install claude` writes `CLAUDE.md`.
+- `routesmith install claude` writes `CLAUDE.md` and merges token-saving settings into `.claude/settings.json`.
 - `routesmith install codex` writes `AGENTS.md`.
 - `routesmith install gemini` writes `GEMINI.md`.
 - `routesmith install copilot` writes `.github/copilot-instructions.md`.
-- `routesmith install cursor` writes `.cursorrules`.
-- `routesmith install aider` writes `.aider.conf.yml`.
+- `routesmith install cursor` writes `.cursorules`.
+- `routesmith install aider` writes `.aider.conf.yml`, or `.aider.routesmith.yml` if an existing Aider config is already present.
 
 ## Auto Mode (Default)
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "routesmith"
-version = "0.1.6"
+version = "0.1.8"
 description = "Auto-route coding agent tasks to the best model in your IDE. Python library + MCP server for Claude Code, Codex, Gemini CLI, Copilot, Cursor, and Aider."
 readme = "README.md"
 license = "MIT"

src/routesmith/__init__.py

@@ -98,7 +98,12 @@ def serve_stdio() -> None:
     run_stdio_server()
 
 
-def install(target: str) -> InstallResult:
+def install(
+    target: str,
+    *,
+    root: Path | None = None,
+    config: SkillConfig | None = None,
+) -> InstallResult:
     """Install routesmith configuration for a target host."""
     from routesmith.install import run_install
-    return run_install(target)
+    return run_install(target, root=root, config=config)

src/routesmith/advisory.py

@@ -20,14 +20,30 @@
     "Single-task prompt detected. No multi-step decomposition needed."
 )
 
+DELEGATION_TIER_ADVISORY = (
+    "Use the cheapest capability tier that can handle each subtask. "
+    "Reserve deep reasoning for planning, architecture, and tradeoff decisions."
+)
+
+TASK_COMPLEXITY_ADVISORY = (
+    "Complex plan may benefit from parallel delegation."
+)
+
+TOOL_COST_ADVISORY = (
+    "Prefer low-cost tool alternatives: text-first web fetch over screenshot-heavy browsing, "
+    "extracted PDF text over heavier readers, and reusable helpers for repeated fetch workflows."
+)
+
 
 def generate_advisory(
     plan: RoutePlan,
     capabilities: HostCapabilities,
     pinned_model: str | None = None,
+    max_spawn_depth: int = 2,
 ) -> list[str]:
     """Generate advisory messages based on plan and host capabilities."""
     messages: list[str] = []
+    capability_classes = {task.preferred_capability_class for task in plan.tasks}
 
     if pinned_model:
         messages.append(PINNED_MODEL_ADVISORY)
@@ -38,10 +54,23 @@ def generate_advisory(
     if len(plan.tasks) == 1:
         messages.append(SINGLE_TASK_ADVISORY)
 
-    if len(plan.tasks) > 3 and not capabilities.supports_dynamic_switch:
-        messages.append(
-            f"Complex multi-step task ({len(plan.tasks)} steps) detected in a host "
-            f"without model switching. Each step will use optimized prompts."
-        )
+    if len(capability_classes) > 1:
+        messages.append(DELEGATION_TIER_ADVISORY)
+
+    if len(plan.tasks) > 3:
+        if not capabilities.supports_dynamic_switch:
+            messages.append(
+                f"Complex multi-step task ({len(plan.tasks)} steps) detected in a host "
+                f"without model switching. Each step will use optimized prompts."
+            )
+        else:
+            messages.append(
+                f"{TASK_COMPLEXITY_ADVISORY} "
+                f"Plan has {len(plan.tasks)} subtasks; "
+                f"generated host configs limit subagent nesting to {max_spawn_depth} levels."
+            )
+
+    if capabilities.supports_context_management:
+        messages.append(TOOL_COST_ADVISORY)
 
     return messages

src/routesmith/config.py

@@ -53,7 +53,10 @@ def _parse_value(raw_value: str) -> Any:
             return value.lower() == "true"
         if value.isdigit():
             return int(value)
-        return value
+        try:
+            return float(value)
+        except ValueError:
+            return value
 
     def _get_section_target(section: list[str]) -> dict[str, Any]:
         target = result
@@ -145,6 +148,24 @@ def _get(key: str, env_var: str, default: Any, cast: type = str) -> Any:
             None,
             float,
         ),
+        context_window_limit=_get(
+            "context_window_limit",
+            "ROUTESMITH_CONTEXT_WINDOW_LIMIT",
+            True,
+            bool,
+        ),
+        autocompact_threshold=_get(
+            "autocompact_threshold",
+            "ROUTESMITH_AUTOCOMPACT_THRESHOLD",
+            80,
+            int,
+        ),
+        max_spawn_depth=_get(
+            "max_spawn_depth",
+            "ROUTESMITH_MAX_SPAWN_DEPTH",
+            2,
+            int,
+        ),
         config_file=config_file,
         policy_overrides=file_config.get("policy_overrides", {}),
         policy_plugins=_get("policy_plugins", "ROUTESMITH_POLICY_PLUGINS", [], list),

src/routesmith/exceptions.py

@@ -1,37 +1,37 @@
 """Custom exceptions for routesmith."""
 
 
-class RouterSmitError(Exception):
+class RoutesmithError(Exception):
     """Base exception for routesmith."""
 
 
-class HostDetectionError(RouterSmitError):
+class HostDetectionError(RoutesmithError):
     """Raised when host detection fails critically."""
 
 
-class ModelSwitchError(RouterSmitError):
+class ModelSwitchError(RoutesmithError):
     """Raised when a model switch attempt fails."""
 
 
-class PlannerError(RouterSmitError):
+class PlannerError(RoutesmithError):
     """Raised when the planner cannot decompose a prompt."""
 
 
-class PolicyError(RouterSmitError):
+class PolicyError(RoutesmithError):
     """Raised when policy resolution fails."""
 
 
-class ExecutionError(RouterSmitError):
+class ExecutionError(RoutesmithError):
     """Raised when task execution fails."""
 
 
-class ConfigurationError(RouterSmitError):
+class ConfigurationError(RoutesmithError):
     """Raised when configuration is invalid."""
 
 
-class InstallError(RouterSmitError):
+class InstallError(RoutesmithError):
     """Raised when an install operation fails."""
 
 
-class ProviderError(RouterSmitError):
+class ProviderError(RoutesmithError):
     """Raised when a provider operation fails."""

src/routesmith/executor.py

@@ -49,7 +49,11 @@ def explain(self, prompt: str) -> RoutePlan:
         plan = router.resolve_plan(plan)
 
         # Generate advisory
-        advisory = generate_advisory(plan, capabilities)
+        advisory = generate_advisory(
+            plan,
+            capabilities,
+            max_spawn_depth=self.config.max_spawn_depth,
+        )
         plan.advisory.extend(advisory)
 
         # Review
@@ -90,7 +94,12 @@ def run(
                 task.suggested_model = model
 
         # Generate advisory
-        advisory = generate_advisory(plan, capabilities, pinned_model=pinned_model)
+        advisory = generate_advisory(
+            plan,
+            capabilities,
+            pinned_model=pinned_model,
+            max_spawn_depth=self.config.max_spawn_depth,
+        )
         plan.advisory.extend(advisory)
         t_route_end = time.perf_counter()
 

src/routesmith/hosts/__init__.py

@@ -2,11 +2,23 @@
 
 from routesmith.hosts.base import BaseHostAdapter
 from routesmith.hosts.detector import detect_host, get_host_capabilities
+from routesmith.hosts.aider import AiderHostAdapter
+from routesmith.hosts.claude_code import ClaudeCodeHostAdapter
+from routesmith.hosts.codex import CodexHostAdapter
+from routesmith.hosts.copilot import CopilotHostAdapter
+from routesmith.hosts.cursor import CursorHostAdapter
 from routesmith.hosts.gemini_cli import GeminiCLIHostAdapter
+from routesmith.hosts.generic import GenericHostAdapter
 
 __all__ = [
     "BaseHostAdapter",
     "detect_host",
     "get_host_capabilities",
+    "AiderHostAdapter",
+    "ClaudeCodeHostAdapter",
+    "CodexHostAdapter",
+    "CopilotHostAdapter",
+    "CursorHostAdapter",
     "GeminiCLIHostAdapter",
+    "GenericHostAdapter",
 ]

src/routesmith/hosts/aider.py

@@ -73,6 +73,7 @@ def get_capabilities(self) -> HostCapabilities:
             supports_repo_instructions=True,
             supports_settings_edit=True,
             supports_env_override=True,
+            supports_context_management=True,
             model_family="mixed",
             notes=[
                 "Aider supports multiple providers (Anthropic, OpenAI, etc.).",