scootcli 0.1.0__tar.gz → 0.3.0__tar.gz

{scootcli-0.1.0 → scootcli-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Sergey Neskoromny
+Copyright (c) 2026 Sergey Nes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{scootcli-0.1.0/src/scootcli.egg-info → scootcli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scootcli
-Version: 0.1.0
+Version: 0.3.0
 Summary: A tiny coding agent that goes where you point it
 Author: Sergey Nes
 License-Expression: MIT
@@ -25,17 +25,25 @@ Dynamic: license-file
 
 # scoot
 
+[![PyPI](https://img.shields.io/pypi/v/scootcli.svg?label=PyPI)](https://pypi.org/project/scootcli/)
+[![tests](https://github.com/sergenes/scootcli/actions/workflows/tests.yml/badge.svg)](https://github.com/sergenes/scootcli/actions/workflows/tests.yml)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#install-options)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#install-options)
+[![Providers](https://img.shields.io/badge/providers-OpenAI%20%7C%20Ollama%20%7C%20Anthropic-orange.svg)](#providers-and-models)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
 ```
        ╭───╮      scoot: a tiny coding agent that goes where you point it.
        │o o│
-    T──┤───┤      pipx install scootcli
+    T──┤───┤      pipx install scootcli   (or: curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash)
     │  ╰┬─┬╯      scoot
   (o)═══╧═╧═(o)
 ```
 
 `scoot` is a terminal coding agent in plain Python.
 You type what you want in natural language; it reads, searches, edits, and runs things in your repo, asking before anything risky.
-It talks to official model APIs (OpenAI today, a local Ollama for free, Anthropic next) and has **zero third-party dependencies**: the whole tool is the Python standard library, and it ships as a single-file zipapp as well as a wheel.
+It talks to official model APIs (OpenAI, Anthropic, and a local Ollama for free) and has **zero third-party dependencies**: the whole tool is the Python standard library, and it ships as a single-file zipapp as well as a wheel.
 
 ## Where this comes from
 
@@ -88,7 +96,7 @@ A bare name means the default provider, which is the first provider that has a k
 |---|---|---|---|
 | `openai` | OpenAI Responses API | `OPENAI_API_KEY` | `gpt-5.3-codex` |
 | `ollama` | local Ollama, Responses API | none | `llama3.2` |
-| `anthropic` | Messages API | `ANTHROPIC_API_KEY` | arrives in 0.2.0 |
+| `anthropic` | Anthropic Messages API | `ANTHROPIC_API_KEY` | `claude-opus-5` |
 
 ```bash
 scoot models                         # every configured provider, grouped
@@ -98,7 +106,38 @@ scoot --model auto "..."             # pick a model per prompt from the live lis
 ```
 
 Inside the REPL, `/model <provider/model>` switches and is remembered for the next launch; `/model default` goes back to the provider's preferred model.
-`SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it.
+
+### Routing
+
+`auto` is opt-in (`--model auto`, `SCOOT_MODEL=auto`, or `/model auto`) because choosing costs a decision per turn.
+Without any configuration it uses a built-in heuristic over the models your providers actually list: a strong coding model for multi-step or editing prompts, a cheaper one for short questions, never a dated snapshot.
+A turn is routed once, at its first model call, and stays on that model.
+
+Write your own rules in `~/.config/scoot/router.json` (or the file named by `SCOOT_ROUTER`); first match wins, and a rule whose provider has no key is skipped:
+
+```json
+{
+  "rules": [
+    {"when": {"has_images": true},        "use": "anthropic/claude-opus-5"},
+    {"when": {"complex": true},           "use": "openai/gpt-5.3-codex"},
+    {"when": {"est_tokens_over": 60000},  "use": "anthropic/claude-sonnet-5"},
+    {"when": {"prompt_matches": "(?i)translate|summari[sz]e"}, "use": "ollama/qwen3"}
+  ],
+  "default": "ollama/llama3.2",
+  "classifier": {
+    "model": "ollama/llama3.2",
+    "tiers": {"simple": "ollama/llama3.2", "coding": "openai/gpt-5.3-codex", "hard": "anthropic/claude-opus-5"}
+  }
+}
+```
+
+Conditions: `complex`, `has_images`, `needs_tools`, `est_tokens_over`, `prompt_matches`.
+The optional `classifier` asks a small model one question per turn ("simple, coding, or hard?") and maps the answer to a tier; it adds a short call, and any failure falls through to the rules.
+Expect it to be rough with a 3B local model: on a hand-labelled set of seven prompts, `llama3.2` and `qwen2.5` each got four right, mostly confusing "coding" with "hard".
+The rules are deterministic, so put the decisions you care about there, and if you want a better judge, name a cheap hosted model as the classifier (`openai/gpt-5-mini`), which costs a few hundred tokens per turn.
+`/route` shows the rules in force and why the current model was picked; `/status` shows tokens per model.
+`SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it, on both OpenAI and Anthropic.
+On Claude Opus 5 the server-side refusal fallback is requested by default, so a declined request is retried on another Claude model inside the same call; `SCOOT_ANTHROPIC_FALLBACKS=0` turns that off.
 
 A note on how this is built: scoot speaks the OpenAI chat format internally and translates at the edge.
 Adding a provider that speaks that format is one registry row; a different wire format is one small adapter (`src/scootcli/providers/`).
@@ -173,7 +212,7 @@ Without a TTY, scoot falls back to a plain prompt with no bar and no dock.
 
 ### Tools and approvals
 
-The agent has seven tools: `read_file`, `list_dir`, `search`, `write_file`, `edit_file`, `run_shell`, and `update_plan` (a progress checklist for multi-step work).
+The agent has eight tools: `read_file`, `list_dir`, `search`, `write_file`, `edit_file`, `run_shell`, `open_editor` (hands a file to IntelliJ IDEA's `idea -e` or to VS Code, `SCOOT_EDITOR` picks), and `update_plan` (a progress checklist for multi-step work).
 Every tool is sandboxed to the workspace root.
 
 When a call needs approval you can approve once `[a]`, trust that tool for the session `[t]`, approve everything this session `[A]`, edit the arguments `[e]`, skip `[s]`, or quit `[q]`.
@@ -196,11 +235,14 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 
 ```bash
 pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
 git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e .                       # from source
 ```
 
+The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.
 

{scootcli-0.1.0 → scootcli-0.3.0}/README.md

@@ -1,16 +1,24 @@
 # scoot
 
+[![PyPI](https://img.shields.io/pypi/v/scootcli.svg?label=PyPI)](https://pypi.org/project/scootcli/)
+[![tests](https://github.com/sergenes/scootcli/actions/workflows/tests.yml/badge.svg)](https://github.com/sergenes/scootcli/actions/workflows/tests.yml)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#install-options)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#install-options)
+[![Providers](https://img.shields.io/badge/providers-OpenAI%20%7C%20Ollama%20%7C%20Anthropic-orange.svg)](#providers-and-models)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
 ```
        ╭───╮      scoot: a tiny coding agent that goes where you point it.
        │o o│
-    T──┤───┤      pipx install scootcli
+    T──┤───┤      pipx install scootcli   (or: curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash)
     │  ╰┬─┬╯      scoot
   (o)═══╧═╧═(o)
 ```
 
 `scoot` is a terminal coding agent in plain Python.
 You type what you want in natural language; it reads, searches, edits, and runs things in your repo, asking before anything risky.
-It talks to official model APIs (OpenAI today, a local Ollama for free, Anthropic next) and has **zero third-party dependencies**: the whole tool is the Python standard library, and it ships as a single-file zipapp as well as a wheel.
+It talks to official model APIs (OpenAI, Anthropic, and a local Ollama for free) and has **zero third-party dependencies**: the whole tool is the Python standard library, and it ships as a single-file zipapp as well as a wheel.
 
 ## Where this comes from
 
@@ -63,7 +71,7 @@ A bare name means the default provider, which is the first provider that has a k
 |---|---|---|---|
 | `openai` | OpenAI Responses API | `OPENAI_API_KEY` | `gpt-5.3-codex` |
 | `ollama` | local Ollama, Responses API | none | `llama3.2` |
-| `anthropic` | Messages API | `ANTHROPIC_API_KEY` | arrives in 0.2.0 |
+| `anthropic` | Anthropic Messages API | `ANTHROPIC_API_KEY` | `claude-opus-5` |
 
 ```bash
 scoot models                         # every configured provider, grouped
@@ -73,7 +81,38 @@ scoot --model auto "..."             # pick a model per prompt from the live lis
 ```
 
 Inside the REPL, `/model <provider/model>` switches and is remembered for the next launch; `/model default` goes back to the provider's preferred model.
-`SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it.
+
+### Routing
+
+`auto` is opt-in (`--model auto`, `SCOOT_MODEL=auto`, or `/model auto`) because choosing costs a decision per turn.
+Without any configuration it uses a built-in heuristic over the models your providers actually list: a strong coding model for multi-step or editing prompts, a cheaper one for short questions, never a dated snapshot.
+A turn is routed once, at its first model call, and stays on that model.
+
+Write your own rules in `~/.config/scoot/router.json` (or the file named by `SCOOT_ROUTER`); first match wins, and a rule whose provider has no key is skipped:
+
+```json
+{
+  "rules": [
+    {"when": {"has_images": true},        "use": "anthropic/claude-opus-5"},
+    {"when": {"complex": true},           "use": "openai/gpt-5.3-codex"},
+    {"when": {"est_tokens_over": 60000},  "use": "anthropic/claude-sonnet-5"},
+    {"when": {"prompt_matches": "(?i)translate|summari[sz]e"}, "use": "ollama/qwen3"}
+  ],
+  "default": "ollama/llama3.2",
+  "classifier": {
+    "model": "ollama/llama3.2",
+    "tiers": {"simple": "ollama/llama3.2", "coding": "openai/gpt-5.3-codex", "hard": "anthropic/claude-opus-5"}
+  }
+}
+```
+
+Conditions: `complex`, `has_images`, `needs_tools`, `est_tokens_over`, `prompt_matches`.
+The optional `classifier` asks a small model one question per turn ("simple, coding, or hard?") and maps the answer to a tier; it adds a short call, and any failure falls through to the rules.
+Expect it to be rough with a 3B local model: on a hand-labelled set of seven prompts, `llama3.2` and `qwen2.5` each got four right, mostly confusing "coding" with "hard".
+The rules are deterministic, so put the decisions you care about there, and if you want a better judge, name a cheap hosted model as the classifier (`openai/gpt-5-mini`), which costs a few hundred tokens per turn.
+`/route` shows the rules in force and why the current model was picked; `/status` shows tokens per model.
+`SCOOT_EFFORT` (`low` | `medium` | `high` | `xhigh`, default `medium`) sets the reasoning effort for models that take it, on both OpenAI and Anthropic.
+On Claude Opus 5 the server-side refusal fallback is requested by default, so a declined request is retried on another Claude model inside the same call; `SCOOT_ANTHROPIC_FALLBACKS=0` turns that off.
 
 A note on how this is built: scoot speaks the OpenAI chat format internally and translates at the edge.
 Adding a provider that speaks that format is one registry row; a different wire format is one small adapter (`src/scootcli/providers/`).
@@ -148,7 +187,7 @@ Without a TTY, scoot falls back to a plain prompt with no bar and no dock.
 
 ### Tools and approvals
 
-The agent has seven tools: `read_file`, `list_dir`, `search`, `write_file`, `edit_file`, `run_shell`, and `update_plan` (a progress checklist for multi-step work).
+The agent has eight tools: `read_file`, `list_dir`, `search`, `write_file`, `edit_file`, `run_shell`, `open_editor` (hands a file to IntelliJ IDEA's `idea -e` or to VS Code, `SCOOT_EDITOR` picks), and `update_plan` (a progress checklist for multi-step work).
 Every tool is sandboxed to the workspace root.
 
 When a call needs approval you can approve once `[a]`, trust that tool for the session `[t]`, approve everything this session `[A]`, edit the arguments `[e]`, skip `[s]`, or quit `[q]`.
@@ -171,11 +210,14 @@ The bottom row shows the mascot's face (its eyes follow the turn: `o o` idle, `>
 
 ```bash
 pipx install scootcli                          # recommended: isolated, `scoot` on PATH
+curl -fsSL https://raw.githubusercontent.com/sergenes/scootcli/main/install.sh | bash   # no pipx: puts the zipapp at ~/.local/bin/scoot
 pip install scootcli                           # anywhere
 curl -LO https://github.com/sergenes/scootcli/releases/latest/download/scoot.pyz && python3 scoot.pyz  # single file, no install
 git clone https://github.com/sergenes/scootcli && cd scootcli && pip install -e .                       # from source
 ```
 
+The install script needs only `curl` and Python 3.9+. `SCOOT_VERSION=v0.2.0` pins a release and `SCOOT_INSTALL_DIR` changes the target; read it before you run it, it is sixty lines.
+
 Requirements: Python 3.9 or newer on macOS or Linux.
 Nothing else: no compiler, no packages, no `curl`.
 

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/__init__.py

@@ -1,4 +1,4 @@
 """scoot: a tiny coding agent that goes where you point it."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/agent.py

@@ -129,7 +129,10 @@ class Agent:
             except ScootError as exc:
                 return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
 
-            session.account(result.usage)
+            try:
+                session.account(result.usage, model=result.model or session.active_model)
+            except TypeError:  # older/fake sessions with a one-argument account()
+                session.account(result.usage)
             session.messages.append(self._assistant_message(result))
 
             if result.tool_calls:
@@ -187,19 +190,33 @@ class Agent:
 
     # ── message construction ─────────────────────────────────────────────────────
     def _pick_model(self, session) -> str:
-        """Resolve the model for this turn. For ``auto``, use the heuristic over live models."""
+        """Resolve the model for this turn. ``auto`` routes once per turn (see ``providers.router``)."""
         if session.model.lower() != "auto":
             return session.resolved_model()
-        from .models import resolve_auto
+        from .providers.router import Router, compute_hints
 
-        last_user = self._last_user_text(session)
+        router = getattr(session, "router", None)
+        if router is None:
+            router = Router()
+            try:
+                session.router = router
+            except Exception:
+                pass
         try:
             available = session.available_models()
         except Exception:
             available = []
         bad = getattr(session, "bad_models", None) or set()
         available = [m for m in available if m not in bad] or available
-        return resolve_auto(last_user, available, fallback=session.resolved_model())
+        hints = compute_hints(session)
+        return router.choose(session, hints, available, session.resolved_model(),
+                             classify=self._classify_with_provider).model
+
+    def _classify_with_provider(self, model: str, prompt: str) -> str:
+        """One small, non-streaming call used by a configured router classifier."""
+        result = self.provider.chat([{"role": "user", "content": prompt}], model=model, max_tokens=5,
+                                    temperature=0, hints={"purpose": "route"})
+        return result.content or ""
 
     def _fallback_model(self, session) -> bool:
         """After a model-unavailable error, blacklist it and switch models. Returns False if stuck."""

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/auth.py

@@ -43,14 +43,19 @@ def status_rows(config) -> List[dict]:
     default = registry.default_provider_name(config)
     rows = []
     for spec in registry.all_specs():
-        rows.append({
+        url = registry.base_url_for(spec)
+        row = {
             "name": spec.name,
             "source": key_source(spec),
             "required": spec.key_required,
             "configured": is_configured(spec),
             "default": spec.name == default,
-            "base_url": registry.base_url_for(spec),
-        })
+            "base_url": url,
+            "reachable": None,  # only probed for keyless local servers
+        }
+        if not spec.key_required and registry.is_local_url(url):
+            row["reachable"] = registry.reachable(url)
+        rows.append(row)
     return rows
 
 

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/cli.py

@@ -141,6 +141,16 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
     from .agent import Agent
     from .repl import ReplSession, ReplUI
 
+    from .providers.registry import readiness
+
+    ready, message = readiness(config)
+    if not ready:  # fail fast with guidance instead of a connection error after retries
+        if as_json:
+            print(_json.dumps({"status": "error", "model": "", "steps": 0, "content": "",
+                               "error": message, "usage": {}}, indent=2))
+        else:
+            eprint(color(message, "yellow"))
+        return 1
     session = ReplSession(config, pool)
     if resume is not None:
         session.apply_record(resume)
@@ -194,7 +204,6 @@ def _cmd_auth(config: Config, pool: ProviderPool, words: List[str]) -> int:
 
 def _interactive(pool: ProviderPool, resume=None) -> int:
     """Launch the persistent REPL (banner, live status, ESC-interrupt, slash-commands)."""
-    from .auth import is_configured, missing_key_hint
     from .repl import Repl
 
     config = pool.config
@@ -206,9 +215,11 @@ def _interactive(pool: ProviderPool, resume=None) -> int:
         resume = sessions.latest_for_root(str(config.root))
 
     try:
-        spec = pool.spec
-        if not is_configured(spec):  # first-run onboarding: guide, but still open the REPL
-            eprint(color(f"No API key for {spec.name}: {missing_key_hint(spec)}", "yellow"))
+        from .providers.registry import readiness
+
+        ready, message = readiness(config)
+        if not ready:  # first-run onboarding: guide, but still open the REPL so /auth is usable
+            eprint(color(message, "yellow"))
     except ScootError as exc:
         eprint(color(f"⚠ {redact(str(exc))}", "yellow"))
     return Repl(config, pool, resume=resume).run()

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/commands/__init__.py

@@ -51,6 +51,7 @@ def load_builtins() -> None:
     from . import verbosity as _verbosity  # noqa: F401
     from . import copy as _copy  # noqa: F401
     from . import logo as _logo  # noqa: F401
+    from . import route as _route  # noqa: F401
 
     _loaded = True
 

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/commands/auth.py

@@ -24,8 +24,10 @@ def _show(session) -> None:
     print(color("providers:", "bold"))
     for row in rows:
         name = row["name"] + ("  (default)" if row["default"] else "")
-        if not row["required"]:
-            state = color("no key needed", "gray")
+        if not row["required"] and row.get("reachable") is False:
+            state = color("not running (ollama serve; install from https://ollama.com)", "yellow")
+        elif not row["required"]:
+            state = color("no key needed" + (", running" if row.get("reachable") else ""), "gray")
         elif row["source"]:
             state = color(f"key from {row['source']}", "green")
         else:

scootcli-0.3.0/src/scootcli/commands/route.py

@@ -0,0 +1,21 @@
+"""/route — show how the ``auto`` model alias routes: rule source, rules, classifier, last decision."""
+
+from __future__ import annotations
+
+from ..providers.router import Router, config_path, describe
+from ..rendering import color
+from . import register
+from .base import SlashCommand
+
+
+def _run(session, args: str):
+    router = getattr(session, "router", None) or Router()
+    print(color("routing (for /model auto):", "bold"))
+    for line in describe(router):
+        print("  " + line)
+    if session.model.lower() != "auto":
+        print(color(f"  auto is off; the preference is '{session.model}'. Turn it on with /model auto.", "gray"))
+    print(color(f"  edit rules in {config_path()} (see README: Routing)", "gray"))
+
+
+register(SlashCommand("route", "show how 'auto' picks a model", _run))

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/commands/status.py

@@ -42,6 +42,13 @@ def _run(session, args: str):
     print(color("status:", "bold"))
     for label, value in rows:
         print(f"  {color(label + ':', 'gray'):<28} {value}")
+    by_model = getattr(session, "usage_by_model", None) or {}
+    if len(by_model) > 1 or (by_model and session.model.lower() == "auto"):
+        print(f"  {color('tokens by model:', 'gray')}")
+        for name, u in sorted(by_model.items(), key=lambda kv: -(kv[1]['prompt'] + kv[1]['completion'])):
+            print(f"    {color(name, 'cyan'):<40} prompt={u['prompt']} completion={u['completion']} calls={u['calls']}")
+    if session.model.lower() == "auto" and getattr(session, "route_reason", ""):
+        print(f"  {color('routed by:', 'gray'):<28} {session.route_reason}")
     trusted = getattr(session, "trusted_tools", None)
     if trusted:
         print(f"  {color('trusted tools:', 'gray'):<28} {', '.join(sorted(trusted))}")

{scootcli-0.1.0 → scootcli-0.3.0}/src/scootcli/config.py

@@ -178,6 +178,7 @@ class Config:
     images: bool = True  # detect dropped image paths + describe them with a vision model (M22)
     vision_model: str = "auto"  # provider/model for image descriptions, or "auto" → pick a capable one
     image_max_bytes: int = 4 * 1024 * 1024  # per-image cap (no downscale without a 3rd-party lib)
+    editor: str = "idea"  # external editor for the open_editor tool: idea | vscode
     env_files: Tuple[str, ...] = ()  # the .env files that were read, in load order (shown by /status)
     logo: bool = True  # mascot in the launch banner + status-bar face (--no-logo / SCOOT_LOGO / /logo)
     emoji: bool = True  # 🛴 transcript label; off → ⏺ for terminals without an emoji font (--no-emoji)
@@ -214,6 +215,7 @@ class Config:
             images=_as_bool(get("SCOOT_IMAGES", "true")),
             vision_model=get("SCOOT_VISION_MODEL", "auto"),
             image_max_bytes=int(get("SCOOT_IMAGE_MAX_BYTES", str(4 * 1024 * 1024))),
+            editor=get("SCOOT_EDITOR", "idea").strip().lower(),
             logo=_resolve_logo_setting(get("SCOOT_LOGO")),
             emoji=_as_bool(get("SCOOT_EMOJI", "true")),
         )