Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: refuse to start Claude Code or OpenCode on a context too small for their own prompt (#14799)

Nilay681bbb85ce81
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index dd257751e9a..5ea8eeaf06b 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -87,6 +87,10 @@ _DSH_SAFE_PERMISSION_MODE = "workspace-write"
_DSH_YOLO_PERMISSION_MODE = "danger-full-access"
# dsh's pi-ai provider sends max_tokens = contextWindow - its prompt estimate - 4,096 (pi-ai CONTEXT_SAFETY_TOKENS), floored at 1, and dsh's own instructions and tools are about 6,500 tokens: at 8,192 every reply is cut after one token (#14315).
_DSH_MIN_CONTEXT = 16384
+# First request of a stock install (system prompt + tool schemas) before any user text, measured on Claude Code 2.1 and OpenCode 1.19 / 2.1. MCP servers and project instructions add to it.
+_CLAUDE_PROMPT_TOKENS = 16_000
+_OPENCODE_PROMPT_TOKENS = 7_500
+_OPENCODE_V2_PROMPT_TOKENS = 5_500
_PI_PROVIDER = "unsloth"
_SUBAGENT_NAME = "unsloth"
_SUBAGENT_DESCRIPTION = (
@@ -205,6 +209,10 @@ _OPENCODE_PROVIDER = "unsloth-studio"
# OpenCode sends min(limit.output, this) as max_tokens unless the env var below raises it.
_OPENCODE_OUTPUT_TOKEN_MAX = 32_000
_CLAUDE_COMPACT_OUTPUT_RESERVE = 20_000
+# Claude Code 2.1.307-2.1.309 compact one token past window - min(max output, 20k) - 3k, in the TUI and -p alike.
+_CLAUDE_COMPACT_BUFFER = 3_000
+# claude 2.1 ignores a smaller CLAUDE_CODE_AUTO_COMPACT_WINDOW and warns about it on every launch.
+_CLAUDE_MIN_AUTO_COMPACT_WINDOW = 100_000
_OPENCODE_OUTPUT_TOKEN_MAX_ENV = "OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX"
_VIBE_PROVIDER = "unsloth-studio"
_VIBE_MODEL_ALIAS = "unsloth"
@@ -3263,9 +3271,12 @@ def _claude_local_env(
if window:
# claude assumes 200k for a model id it does not recognize, and clamps AUTO_COMPACT_WINDOW to [100k, that]. MAX_CONTEXT_TOKENS sets the window itself.
env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] = str(int(window))
- env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = str(int(window))
+ # Blank, not omitted, below the floor so an inherited value cannot apply; MAX_CONTEXT_TOKENS still bounds compaction there.
+ env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = (
+ str(int(window)) if int(window) >= _CLAUDE_MIN_AUTO_COMPACT_WINDOW else ""
+ )
env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] = "90"
- # claude reserves min(max output, 20k) + 13k before compacting, so its 32k default output leaves a 32k window nothing; above 20k the cap gains no room.
+ # claude reserves min(max output, 20k) + 3k before compacting, so its 32k default output would take 20k of a 32k window; above 20k the cap gains no room.
output = opencode_output_limit(int(window))
if output < _CLAUDE_COMPACT_OUTPUT_RESERVE:
env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] = str(output)
@@ -5365,6 +5376,167 @@ def opencode_compaction_reserved(window: int, output: int) -> int:
return max(1, min(output, max(window // 10, 8192)))
+def _agent_compacts_at(
+ agent: str,
+ window: int,
+ max_tokens: Optional[int] = None,
+) -> int:
+ if agent == "claude":
+ output = min(opencode_output_limit(window), _CLAUDE_COMPACT_OUTPUT_RESERVE)
+ return min(window * 9 // 10, window - output - _CLAUDE_COMPACT_BUFFER)
+ return window - opencode_compaction_reserved(window, opencode_output_limit(window, max_tokens))
+
+
+_CLAUDE_RESUME_ARGS = ({"-c", "--continue", "--fork-session"}, {"-r", "--resume", "--session-id"})
+_OPENCODE_RESUME_ARGS = ({"-c", "--continue", "--fork", "--no-replay"}, {"-s", "--session"})
+
+
+def _only_resumes(args: list, resume_args: tuple) -> bool:
+ """True when the forwarded args only reopen an interactive session, which keeps the stock prompt."""
+ flags, valued = resume_args
+ rest = list(args)
+ while rest:
+ arg = rest.pop(0)
+ name = arg.split("=", 1)[0]
+ if name in flags:
+ continue
+ if name not in valued:
+ return False
+ if "=" not in arg and rest and not rest[0].startswith("-"):
+ rest.pop(0)
+ return True
+
+
+def _early_context_check(model: Optional[str], check):
+ """Run check now, or return it for _before_load when a running Studio could resolve model to a Connection."""
+ # A Connection is only known once _connect asks that server, and it never loads; an auto-started one serves no Connections.
+ if model and find_studio_server() is not None:
+ return check
+ check()
+ return None
+
+
+def _before_load(context_check, preload = None):
+ if context_check is None:
+ return preload
+
+ def check(base, key, requested, gguf_variant):
+ context_check()
+ if preload is not None:
+ preload(base, key, requested, gguf_variant)
+
+ return check
+
+
+def _command_line_options(ctx, quote) -> Optional[list]:
+ """The options typed on this command line, minus --max-seq-length and --api-key."""
+ # Duck-typed: typer may vendor its own click, so isinstance / enum identity against ours fails.
+ if ctx is None:
+ return None
+ parts = []
+ for param in ctx.command.params:
+ if param.param_type_name != "option" or param.name in ("max_seq_length", "api_key"):
+ continue
+ if getattr(ctx.get_parameter_source(param.name), "name", None) != "COMMANDLINE":
+ continue
+ value = ctx.params.get(param.name)
+ if param.is_flag:
+ if value:
+ parts.append(param.opts[0])
+ elif param.secondary_opts:
+ parts.append(param.secondary_opts[0])
+ continue
+ for item in value if param.multiple else [value]:
+ if item is not None:
+ item = getattr(item, "value", item)
+ parts += [param.opts[0], quote(str(item))]
+ return parts
+
+
+def _check_agent_context(
+ agent: str,
+ name: str,
+ entry: dict,
+ prompt_tokens: int,
+ max_tokens: Optional[int] = None,
+ loaded: bool = True,
+ refuse: bool = True,
+ model: Optional[str] = None,
+ gguf_variant: Optional[str] = None,
+ ctx = None,
+) -> None:
+ window = entry.get("context_length") or entry.get("max_context_length")
+ if not window:
+ return
+ window = int(window)
+ roomy = 2 * prompt_tokens
+ compacts_at = _agent_compacts_at(agent, window, max_tokens)
+ # Before the load only refuse; the window Studio actually fits is checked again after it.
+ if compacts_at >= roomy or (not loaded and (compacts_at >= prompt_tokens or not refuse)):
+ return
+ suggested = next(
+ (
+ size
+ for size in (1 << bits for bits in range(14, 21))
+ if _agent_compacts_at(agent, size, max_tokens) >= roomy
+ ),
+ 1 << 20,
+ )
+ native = int(entry.get("native_context_length") or 0)
+ if native:
+ suggested = min(suggested, native)
+ if entry.get("connection"):
+ # --max-seq-length only labels a Connection's window; it cannot grow the provider's.
+ hint = "A Connection's context is set by its provider, so pick a model with a longer one."
+ elif native and (
+ native <= window or _agent_compacts_at(agent, native, max_tokens) < prompt_tokens
+ ):
+ hint = f"Its full context is {native:,} tokens, so pick a model with a longer one."
+ else:
+ quote = _powershell_quote if os.name == "nt" else shlex.quote
+ given = _command_line_options(ctx, quote) or []
+ # A positional org/name (or none at all, outside a command) never reaches the option sources.
+ if model and not {"--model", "-m"} & set(given):
+ given = ["--model", quote(model), *given]
+ if gguf_variant and "--gguf-variant" not in given:
+ given += ["--gguf-variant", quote(gguf_variant)]
+ if max_tokens and "--max-tokens" not in given:
+ given += ["--max-tokens", str(int(max_tokens))]
+ if ctx is not None and ctx.get_parameter_source("api_key").name == "COMMANDLINE":
+ # Not remembered yet before the load; never echo the key itself.
+ given += ["--api-key", "<your key>"]
+ forwarded = list(ctx.args) if ctx is not None else []
+ target = "".join(f" {part}" for part in given)
+ # Only a refused launch's args (none, or resume flags) are echoed: scripted ones can carry a prompt.
+ if refuse:
+ tail = "".join(f" {quote(arg)}" for arg in forwarded)
+ else:
+ tail = " plus your other arguments" if forwarded else ""
+ hint = (
+ f"Run unsloth start {agent}{target} --max-seq-length {suggested}{tail} "
+ "(a smaller quant if that does not fit in memory"
+ + ("" if loaded else "; for a Connection, a model with a longer context")
+ + ")."
+ )
+ state = "is loaded" if loaded else "would load"
+ if compacts_at < prompt_tokens:
+ message = (
+ f"{entry['id']} {state} with {window:,} tokens of context, too few for {name}: "
+ f"its own instructions and tools take about {prompt_tokens:,}, so it would compact "
+ f"on every message. {hint}"
+ )
+ if refuse:
+ _fail(message)
+ typer.echo(f"Warning: {message}", err = True)
+ return
+ typer.echo(
+ f"Warning: {entry['id']} {state} with {window:,} tokens of context, and {name}'s "
+ f"instructions and tools take about {prompt_tokens:,} of it (more with MCP servers), "
+ f"so it will compact often. {hint}",
+ err = True,
+ )
+
+
def _opencode_output_env(model: dict, max_tokens: Optional[int]) -> dict:
"""Lift OpenCode's output ceiling when --max-tokens exceeds it; re-emit an inherited one so a --no-launch recipe keeps it."""
window = model.get("context_length") or model.get("max_context_length")
@@ -6981,6 +7153,34 @@ def claude(
)
# Before the install prompt: _install_agent runs a remote installer, and this can refuse outright, so asking first fetches a tool the run cannot use.
_preflight_agent_gguf(_CLAUDE_GGUF_AGENT, model, serve = serve, launch = launch)
+ # Only a bare or resumed interactive launch is refused: its prompt is the stock one and the TUI would hide a warning. Other forwarded args (-p, --tools, a --no-launch recipe a driver extends) can shrink the prompt, so they only warn.
+ # CLAUDE_CODE_SIMPLE is the env form of --bare: a minimal prompt that may fit, so it only warns too.
+ simple = os.environ.get("CLAUDE_CODE_SIMPLE", "").strip().lower() not in (
+ "",
+ "0",
+ "false",
+ "no",
+ "off",
+ )
+ refuse_small_context = launch and not simple and _only_resumes(ctx.args, _CLAUDE_RESUME_ARGS)
+ context_check = None
+ if max_seq_length > 0 and not as_subagent:
+ # Before the load, which would evict the resident model only for this to refuse.
+ context_check = _early_context_check(
+ model,
+ functools.partial(
+ _check_agent_context,
+ "claude",
+ "Claude Code",
+ {"id": model or "The loaded model", "context_length": max_seq_length},
+ _CLAUDE_PROMPT_TOKENS,
+ loaded = False,
+ model = model,
+ gguf_variant = gguf_variant,
+ ctx = ctx,
+ refuse = refuse_small_context,
+ ),
+ )
_require_agent_for_launch("claude", install_hint, launch)
server_options = ServerOptions(
enable_tools = enable_tools,
@@ -7004,7 +7204,9 @@ def claude(
),
serve = serve,
launch = launch,
- preload_check = functools.partial(_attach_gguf_check, _CLAUDE_GGUF_AGENT),
+ preload_check = _before_load(
+ context_check, functools.partial(_attach_gguf_check, _CLAUDE_GGUF_AGENT)
+ ),
server_options = server_options,
connections = True,
)
@@ -7012,6 +7214,17 @@ def claude(
try:
if not entry.get("connection"):
_require_gguf_for_agent(_CLAUDE_GGUF_AGENT, base, key, entry["id"])
+ if not as_subagent:
+ _check_agent_context(
+ "claude",
+ "Claude Code",
+ entry,
+ _CLAUDE_PROMPT_TOKENS,
+ refuse = refuse_small_context,
+ model = model,
+ gguf_variant = gguf_variant,
+ ctx = ctx,
+ )
except BaseException:
_shutdown_auto_served()
raise
@@ -7377,6 +7590,26 @@ def opencode(
_check_app_flags(app, ctx.args, as_subagent)
command_name, opencode_v2 = _opencode_command()
install_hint = _npm_install_hint("@opencode/cli" if opencode_v2 else "opencode-ai")
+ opencode_prompt_tokens = _OPENCODE_V2_PROMPT_TOKENS if opencode_v2 else _OPENCODE_PROMPT_TOKENS
+ refuse_small_context = launch and _only_resumes(ctx.args, _OPENCODE_RESUME_ARGS)
+ context_check = None
+ if max_seq_length > 0 and not as_subagent and not app:
+ context_check = _early_context_check(
+ model,
+ functools.partial(
+ _check_agent_context,
+ "opencode",
+ "OpenCode",
+ {"id": model or "The loaded model", "context_length": max_seq_length},
+ opencode_prompt_tokens,
+ max_tokens,
+ loaded = False,
+ model = model,
+ gguf_variant = gguf_variant,
+ ctx = ctx,
+ refuse = refuse_small_context,
+ ),
+ )
_require_agent_for_launch(command_name, install_hint, launch and not app)
server_options = ServerOptions(
enable_tools = enable_tools,
@@ -7400,6 +7633,7 @@ def opencode(
),
serve = serve,
launch = launch,
+ preload_check = _before_load(context_check),
server_options = server_options,
connections = True,
)
@@ -7410,6 +7644,22 @@ def opencode(
if app:
target = _opencode_app_target(max_tokens, server_options.request_body())
return _add_app_provider(target, base, api_key, entry)
+ if not as_subagent:
+ try:
+ _check_agent_context(
+ "opencode",
+ "OpenCode",
+ entry,
+ opencode_prompt_tokens,
+ max_tokens,
+ refuse = refuse_small_context,
+ model = model,
+ gguf_variant = gguf_variant,
+ ctx = ctx,
+ )
+ except BaseException:
+ _shutdown_auto_served()
+ raise
if opencode_v2:
typer.echo(
f"OpenCode V2 provider policies must allow '{_OPENCODE_PROVIDER}'.",
diff --git a/unsloth_cli/tests/test_claude_subagent_mcp.py b/unsloth_cli/tests/test_claude_subagent_mcp.py
index a7687b4f232..38bc0897012 100644
--- a/unsloth_cli/tests/test_claude_subagent_mcp.py
+++ b/unsloth_cli/tests/test_claude_subagent_mcp.py
@@ -334,7 +334,7 @@ def test_local_child_uses_unsloth_without_overwriting_parent_auth(
assert child_env["ANTHROPIC_AUTH_TOKEN"] == "sk-unsloth-test"
assert child_env["ANTHROPIC_MODEL"] == "unsloth/model-GGUF:Q4_K_M"
assert child_env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] == "32768"
- assert child_env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] == "32768"
+ assert child_env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] == ""
assert child_env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] == "90"
assert child_env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] == "8192"
assert "ANTHROPIC_API_KEY" not in child_env
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index e4d5dd3bdd2..4a6c9bc5467 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -1581,7 +1581,9 @@ def fake_studio(tmp_path, monkeypatch):
return state.get("providers", [])
if url.endswith("/api/inference/load"):
already_loaded = state["models"][0]["id"] == payload["model_path"]
- state["models"] = [{"id": payload["model_path"], "context_length": 4096}]
+ state["models"] = [
+ {"id": payload["model_path"], "context_length": MODEL["context_length"]}
+ ]
return {
"status": "already_loaded" if already_loaded else "loaded",
"model": payload["model_path"],
@@ -1821,7 +1823,7 @@ def test_connect_claude_as_subagent_preserves_cloud_parent(fake_studio, tmp_path
"UNSLOTH_CLAUDE_SUBAGENT_API_KEY": "sk-unsloth-feedfacefeedface",
"UNSLOTH_CLAUDE_SUBAGENT_MODEL": MODEL["id"] + ":UD-Q4_K_XL",
"UNSLOTH_CLAUDE_SUBAGENT_BYPASS_PERMISSIONS": "0",
- "UNSLOTH_CLAUDE_SUBAGENT_CONTEXT_WINDOW": "4096",
+ "UNSLOTH_CLAUDE_SUBAGENT_CONTEXT_WINDOW": str(MODEL["context_length"]),
start._CLAUDE_SUBAGENT_SETTINGS_ENV: str(settings_path),
}
settings = json.loads(settings_path.read_text())
@@ -3514,7 +3516,10 @@ def test_connect_model_flag_matches_canonical_id(fake_studio, monkeypatch):
return {"model": canonical, "display_name": canonical}
if url.endswith("/api/inference/loaded-models"):
# Decoy sorts first, so models[0] is the wrong pick on the old code.
- return {"object": "list", "data": [MODEL, {"id": canonical, "context_length": 4096}]}
+ return {
+ "object": "list",
+ "data": [MODEL, {"id": canonical, "context_length": MODEL["context_length"]}],
+ }
return inner(method, url, token, payload, timeout, error)
monkeypatch.setattr(start, "_http_json", http_json)
@@ -7515,8 +7520,8 @@ def test_connect_pi_as_subagent_preserves_cloud_parent(fake_studio, tmp_path, yo
"baseUrl": f"{BASE}/v1",
"apiKey": "sk-unsloth-feedfacefeedface",
"model": MODEL["id"] + ":UD-Q4_K_XL",
- "contextWindow": 4096,
- "maxTokens": 1024,
+ "contextWindow": MODEL["context_length"],
+ "maxTokens": 32_000,
"approve": yolo,
}
assert "Ask Pi to spawn an Unsloth or local agent." in result.output
@@ -7727,6 +7732,362 @@ def test_dsh_warns_when_the_context_leaves_replies_no_room(fake_studio, window,
assert ("--max-seq-length 16384" in result.output) is warned
+def launched(monkeypatch):
+ calls = []
+ monkeypatch.setattr(start, "_launch", lambda command, env, **kwargs: calls.append(command) or 0)
+ return calls
+
+
+_AGENT_ARGS = {"claude": ["-p", "hi"], "opencode": ["run", "hi"]}
+
+
+ "agent, window, outcome, suggested",
+ [
+ ("claude", 8_192, "too few", 65536),
+ ("claude", 16_384, "too few", 65536),
+ ("claude", 24_576, "too few", 65536),
+ ("claude", 32_768, "tight", 65536),
+ ("claude", 40_960, "tight", 65536),
+ ("claude", 65_536, "ok", None),
+ ("opencode", 8_192, "too few", 32768),
+ ("opencode", 16_384, "tight", 32768),
+ ("opencode", 32_768, "ok", None),
+ ],
+)
[email protected]("mode", ["tui", "args", "no-launch"])
+def test_agent_checks_the_context_fits_its_own_prompt(
+ fake_studio, launched, agent, window, outcome, suggested, mode
+):
+ fake_studio.state["models"] = [{**MODEL, "context_length": window}]
+ args = {"tui": [], "args": _AGENT_ARGS[agent], "no-launch": ["--no-launch"]}[mode]
+ result = CliRunner().invoke(start.start_app, [agent, *args])
+ refused = outcome == "too few" and mode == "tui"
+ assert result.exit_code == (1 if refused else 0), result.output
+ assert (f"loaded with {window:,} tokens of context, too few" in result.output) is (
+ outcome == "too few"
+ )
+ assert ("Warning: " in result.output) is (outcome != "ok" and not refused)
+ assert ("so it will compact often" in result.output) is (outcome == "tight")
+ assert (f"--max-seq-length {suggested}" in result.output) is (suggested is not None)
+ assert bool(launched) is (mode != "no-launch" and not refused)
+
+
+def test_opencode_v2_prompt_fits_where_v1_does_not(fake_studio, launched, monkeypatch):
+ monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode2", True))
+ fake_studio.state["models"] = [{**MODEL, "context_length": 8_192}]
+ result = CliRunner().invoke(start.start_app, ["opencode"])
+ assert result.exit_code == 0, result.output
+ assert "so it will compact often" in result.output
+ assert launched
+
+
[email protected]("agent", ["claude", "opencode"])
+def test_agent_context_check_skips_subagent_mode(fake_studio, agent):
+ fake_studio.state["models"] = [{**MODEL, "context_length": 8_192}]
+ result = CliRunner().invoke(start.start_app, [agent, "--as-subagent", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ assert "tokens of context" not in result.output
+
+
+def test_agent_context_check_caps_the_suggestion_at_the_native_window(capsys):
+ entry = {"id": "m", "context_length": 16_384, "native_context_length": 40_960}
+ with pytest.raises(typer.Exit):
+ start._check_agent_context("claude", "Claude Code", entry, start._CLAUDE_PROMPT_TOKENS)
+ assert "--max-seq-length 40960" in capsys.readouterr().err
+
+
[email protected]("native", [8_192, 16_384])
+def test_agent_context_check_when_the_native_window_cannot_fit(capsys, native):
+ entry = {"id": "m", "context_length": 8_192, "native_context_length": native}
+ with pytest.raises(typer.Exit):
+ start._check_agent_context("claude", "Claude Code", entry, start._CLAUDE_PROMPT_TOKENS)
+ err = capsys.readouterr().err
+ assert "--max-seq-length" not in err
+ assert f"Its full context is {native:,} tokens" in err
+
+
+def test_agent_context_check_ignores_an_unknown_window(capsys):
+ start._check_agent_context("claude", "Claude Code", {"id": "m"}, start._CLAUDE_PROMPT_TOKENS)
+ assert capsys.readouterr().err == ""
+
+
+ "window, compacts_at",
+ [
+ (16_384, 9_288),
+ (24_576, 15_432),
+ (32_768, 21_576),
+ (40_960, 27_720),
+ (65_536, 46_152),
+ (131_072, 108_072),
+ ],
+)
+def test_claude_compaction_point_matches_claude_code(window, compacts_at):
+ # Measured on Claude Code 2.1.307-2.1.309 (TUI and -p) with the env _claude_local_env writes: compaction starts within 256 tokens past this.
+ assert start._agent_compacts_at("claude", window) == compacts_at
+
+
[email protected]("running", [False, True])
[email protected]("agent", ["claude", "opencode"])
+def test_agent_context_check_refuses_before_installing_or_loading(
+ fake_studio, launched, monkeypatch, agent, running
+):
+ requirements = []
+ monkeypatch.setattr(start, "_require_agent_for_launch", lambda *args: requirements.append(args))
+ if not running:
+ monkeypatch.setattr(start, "find_studio_server", lambda: None)
+ result = CliRunner().invoke(
+ start.start_app, [agent, "--model", "unsloth/other-GGUF", "--max-seq-length", "8192"]
+ )
+ assert result.exit_code == 1, result.output
+ assert "unsloth/other-GGUF would load with 8,192 tokens of context, too few" in result.output
+ assert not any(url.endswith("/api/inference/load") for _, url, _ in fake_studio)
+ assert not launched
+ assert bool(requirements) is running
+
+
[email protected]("agent", ["claude", "opencode"])
+def test_agent_context_check_on_a_connection_never_suggests_a_resize(fake_studio, launched, agent):
+ fake_studio.state["providers"] = [GEMINI_CONNECTION]
+ result = CliRunner().invoke(
+ start.start_app, [agent, "--model", "gemini-2.5-flash", "--max-seq-length", "8192"]
+ )
+ assert result.exit_code == 1, result.output
+ assert "A Connection's context is set by its provider" in result.output
+ assert (
+ "--max-seq-length 65536" not in result.output
+ and "--max-seq-length 32768" not in result.output
+ )
+ assert _loads(fake_studio) == []
+ assert not launched
+
+
[email protected]("agent, suggested", [("claude", 65536), ("opencode", 32768)])
[email protected]("variant", [None, "Q8_0"])
+def test_agent_context_retry_keeps_the_requested_model(
+ fake_studio, launched, agent, suggested, variant
+):
+ target = "unsloth/other-GGUF"
+ quant = ["--gguf-variant", variant] if variant else []
+ result = CliRunner().invoke(
+ start.start_app, [agent, "--model", target, *quant, "--max-seq-length", "8192"]
+ )
+ assert result.exit_code == 1, result.output
+ selection = f" --gguf-variant {variant}" if variant else ""
+ command = f"unsloth start {agent} --model {target}{selection} --max-seq-length {suggested}"
+ assert command in result.output
+ retry = CliRunner().invoke(start.start_app, shlex.split(command)[2:])
+ assert retry.exit_code == 0, retry.output
+ loads = [payload for _, url, payload in fake_studio if url.endswith("/api/inference/load")]
+ assert len(loads) == 1
+ assert loads[0]["model_path"] == target
+ assert loads[0]["max_seq_length"] == suggested
+ assert loads[0].get("gguf_variant") == variant
+ assert launched
+
+
+def test_agent_context_check_does_not_resize_a_connection(fake_studio):
+ fake_studio.state["providers"] = [GEMINI_CONNECTION]
+ result = CliRunner().invoke(
+ start.start_app,
+ ["claude", "--no-launch", "--model", "gemini-2.5-flash", "--max-seq-length", "8192"],
+ )
+ assert result.exit_code == 0, result.output
+ assert "too few for Claude Code" in result.output
+ assert "A Connection's context is set by its provider" in result.output
+ assert "--max-seq-length 65536" not in result.output
+
+
[email protected]("agent", ["claude", "opencode"])
+def test_agent_context_retry_keeps_the_load_flags(fake_studio, launched, agent):
+ flags = ["--no-load-in-4bit", "--tensor-parallel", "--gpu-memory-mode", "manual"]
+ args = [
+ agent,
+ "--model",
+ "unsloth/other",
+ *flags,
+ "--api-key",
+ "sk-secret",
+ "--max-seq-length",
+ "8192",
+ ]
+ result = CliRunner().invoke(start.start_app, args)
+ assert result.exit_code == 1, result.output
+ assert "sk-secret" not in result.output
+ line = next(l for l in result.output.splitlines() if "Run unsloth start" in l)
+ command = line[line.index("unsloth start") : line.index(" (a smaller quant")]
+ assert command.startswith(f"unsloth start {agent} --model unsloth/other ")
+ assert " ".join(flags) in command and "--max-seq-length 8192" not in command
+ retry = CliRunner().invoke(start.start_app, shlex.split(command)[2:])
+ assert retry.exit_code == 0, retry.output
+ load = [p for _, url, p in fake_studio if url.endswith("/api/inference/load")][-1]
+ assert load["load_in_4bit"] is False
+
+
+def test_agent_context_retry_keeps_a_positional_model(fake_studio, launched):
+ result = CliRunner().invoke(
+ start.start_app, ["claude", "unsloth/other-GGUF", "--max-seq-length", "8192"]
+ )
+ assert result.exit_code == 1, result.output
+ command = "unsloth start claude --model unsloth/other-GGUF --max-seq-length 65536"
+ assert command in result.output
+ retry = CliRunner().invoke(start.start_app, shlex.split(command)[2:])
+ assert retry.exit_code == 0, retry.output
+ loads = [p for _, url, p in fake_studio if url.endswith("/api/inference/load")]
+ assert loads[-1]["model_path"] == "unsloth/other-GGUF"
+
+
+def test_agent_context_retry_names_a_typed_key_without_echoing_it(fake_studio, launched):
+ args = [
+ "claude",
+ "--model",
+ "unsloth/other-GGUF",
+ "--api-key",
+ "sk-secret",
+ "--max-seq-length",
+ "8192",
+ ]
+ result = CliRunner().invoke(start.start_app, args)
+ assert result.exit_code == 1, result.output
+ assert "--api-key <your key>" in result.output
+ assert "sk-secret" not in result.output
+
+
+ "agent, passthrough, suggested",
+ [
+ ("claude", ["--continue"], 65536),
+ ("claude", ["-r", "abc123"], 65536),
+ ("claude", ["--resume"], 65536),
+ ("opencode", ["-c"], 32768),
+ ("opencode", ["--session", "ses_1", "--fork"], 32768),
+ ],
+)
+def test_agent_context_check_refuses_a_resumed_session(
+ fake_studio, launched, agent, passthrough, suggested
+):
+ fake_studio.state["models"] = [{**MODEL, "context_length": 8_192}]
+ result = CliRunner().invoke(start.start_app, [agent, *passthrough])
+ assert result.exit_code == 1, result.output
+ assert f"--max-seq-length {suggested} {' '.join(passthrough)}" in result.output
+ assert not launched
+
+
+ "agent, args", [("claude", ["-p", "SECRET_PROMPT"]), ("opencode", ["run", "SECRET_PROMPT"])]
+)
+def test_agent_context_warning_never_echoes_a_scripted_prompt(fake_studio, launched, agent, args):
+ fake_studio.state["models"] = [{**MODEL, "context_length": 8_192}]
+ result = CliRunner().invoke(start.start_app, [agent, *args])
+ assert result.exit_code == 0, result.output
+ assert "too few" in result.output and "plus your other arguments" in result.output
+ assert "SECRET_PROMPT" not in result.output
+
+
+ "simple, refused", [("1", False), ("true", False), ("0", True), ("", True)]
+)
+def test_claude_simple_mode_only_warns(fake_studio, launched, monkeypatch, simple, refused):
+ monkeypatch.setenv("CLAUDE_CODE_SIMPLE", simple)
+ fake_studio.state["models"] = [{**MODEL, "context_length": 8_192}]
+ result = CliRunner().invoke(start.start_app, ["claude"])
+ assert result.exit_code == (1 if refused else 0), result.output
+ assert "too few for Claude Code" in result.output
+ assert bool(launched) is not refused
+
+
+def test_opencode_context_retry_keeps_max_tokens(fake_studio, launched):
+ target = "unsloth/other-GGUF"
+ args = ["opencode", "--model", target, "--max-tokens", "1000", "--max-seq-length", "8192"]
+ result = CliRunner().invoke(start.start_app, args)
+ assert result.exit_code == 1, result.output
+ command = f"unsloth start opencode --model {target} --max-tokens 1000 --max-seq-length 16384"
+ assert command in result.output
+ retry = CliRunner().invoke(start.start_app, shlex.split(command)[2:])
+ assert retry.exit_code == 0, retry.output
+ assert launched
+
+
[email protected]("agent, suggested", [("claude", 65536), ("opencode", 32768)])
+def test_agent_context_retry_restarts_the_model_after_fitting(
+ fake_studio, launched, monkeypatch, agent, suggested
+):
+ target = "unsloth/other-GGUF"
+ started, stopped = [], []
+ server = SimpleNamespace(pid = 999, poll = lambda: None)
+ monkeypatch.setattr(start, "find_studio_server", lambda: None)
+
+ def serve(
+ base,
+ model,
+ load,
+ server_options = None,
+ ):
+ started.append((model, load))
+ fake_studio.state["models"] = [{"id": model, "context_length": load.max_seq_length or 8192}]
+ start._auto_served_server = server
+ return base, server
+
+ monkeypatch.setattr(start, "_start_studio_server", serve)
+ monkeypatch.setattr(start, "_shutdown_server", lambda server: stopped.append(server))
+ result = CliRunner().invoke(
+ start.start_app, [agent, "--model", target, "--gguf-variant", "Q8_0"]
+ )
+ assert result.exit_code == 1, result.output
+ assert "is loaded with 8,192 tokens of context, too few" in result.output
+ assert len(started) == len(stopped) == 1
+ command = (
+ f"unsloth start {agent} --model {target} --gguf-variant Q8_0 "
+ f"--max-seq-length {suggested}"
+ )
+ assert command in result.output
+ retry = CliRunner().invoke(start.start_app, shlex.split(command)[2:])
+ assert retry.exit_code == 0, retry.output
+ assert len(started) == 2
+ assert started[1][0] == target
+ assert started[1][1].gguf_variant == "Q8_0"
+ assert started[1][1].max_seq_length == suggested
+ assert launched
+
+
[email protected]("args", [["--no-launch"], ["run", "hi"], []])
+def test_agent_context_check_before_loading_only_refuses_the_tui(fake_studio, launched, args):
+ result = CliRunner().invoke(
+ start.start_app,
+ ["opencode", "--model", "unsloth/other-GGUF", "--max-seq-length", "16384", *args],
+ )
+ assert result.exit_code == 0, result.output
+ assert "would load" not in result.output
+ assert any(url.endswith("/api/inference/load") for _, url, _ in fake_studio)
+
+
+def test_agent_context_check_does_not_refuse_a_no_launch_recipe_before_loading(fake_studio):
+ # A driver may extend the recipe with --tools "" (upstream prompt-cache CI), which fits any window.
+ result = CliRunner().invoke(
+ start.start_app,
+ ["claude", "--no-launch", "--model", "unsloth/other-GGUF", "--max-seq-length", "8192"],
+ )
+ assert result.exit_code == 0, result.output
+ assert any(url.endswith("/api/inference/load") for _, url, _ in fake_studio)
+
+
[email protected]("window, expected", [(32_768, ""), (99_999, ""), (100_000, "100000")])
+def test_claude_auto_compact_window_is_blank_below_claudes_floor(window, expected):
+ env = start._claude_local_env(BASE, "k", {"id": "m", "context_length": window})
+ assert env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] == expected
+ assert env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] == str(window)
+
+
+def test_opencode_v2_prompt_fits_where_v1_does_not_without_launch(fake_studio, monkeypatch):
+ monkeypatch.setattr(start, "_opencode_command", lambda *_: ("opencode2", True))
+ fake_studio.state["models"] = [{**MODEL, "context_length": 8_192}]
+ result = CliRunner().invoke(start.start_app, ["opencode", "--no-launch"])
+ assert result.exit_code == 0, result.output
+ assert "so it will compact often" in result.output
+
+
def _vibe_settings(env: dict) -> tuple:
return json.loads(env["VIBE_PROVIDERS"]), json.loads(env["VIBE_MODELS"])