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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: keep Codex AGENTS.md, skills and rules in unsloth start codex (#16947)
Nilaye59af4633d9e
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.pyindex e6b1c029fc8..5c3ac0bd305 100644--- a/unsloth_cli/commands/start.py+++ b/unsloth_cli/commands/start.py@@ -173,6 +173,9 @@ _CODEX_SUBAGENT_MCP_SERVER = "unsloth_local_agent"_CODEX_SUBAGENT_MCP_TOOL = "spawn_local_agent"_CODEX_SUBAGENT_CONFIG_ENV = "UNSLOTH_CODEX_SUBAGENT_CONFIG"_CODEX_PARENT_OVERLAY_MANIFEST = ".unsloth-parent-overlay.json"+_CODEX_USER_FILES = ("AGENTS.md", "AGENTS.override.md", "skills", "rules", "prompts")+_CODEX_USER_FILES_MANIFEST = "unsloth_user_files.json"+_CODEX_COPIED_DIRS = {"agents", "skills", "rules", "prompts", "plugins", "marketplaces", "sessions"}_CODEX_EPHEMERAL_STALE_SECONDS = 24 * 60 * 60_CODEX_EPHEMERAL_HEARTBEAT_SECONDS = 60_CODEX_SUBAGENT_TOOL_DESCRIPTION = (@@ -3556,17 +3559,21 @@ def _codex_mcp_tables(source: Path, seen: frozenset) -> list:return tables-def _with_user_codex_mcp_servers(text: str, home: Path) -> str:- _, _, carried = _codex_mcp_manifest(home)+def _codex_user_home(home: Path) -> Path:source = _codex_source_home()home_key = home.resolve(strict = False)- if source.resolve(strict = False) == home_key:- # The printed recipe exports CODEX_HOME=home: keep reading the home it was built from.- followed = _codex_mcp_followed(home)- if followed is not None and followed.resolve(strict = False) != home_key:- source = followed- else:- source = _codex_source_home(ignore_configured = True)+ if source.resolve(strict = False) != home_key:+ return source+ # The printed recipe exports CODEX_HOME=home: keep reading the home it was built from.+ followed = _codex_mcp_followed(home)+ if followed is not None and followed.resolve(strict = False) != home_key:+ return followed+ return _codex_source_home(ignore_configured = True)+++def _with_user_codex_mcp_servers(text: str, home: Path, source: Path) -> str:+ _, _, carried = _codex_mcp_manifest(home)+ home_key = home.resolve(strict = False)source_key = str(source.resolve(strict = False))tables = _codex_mcp_tables(source, frozenset({str(home_key), source_key}))# Only replace what came from the user's config; servers added in this home stay.@@ -3602,7 +3609,9 @@ def write_codex_config(existing = config.read_text(encoding = "utf-8") if config.exists() else ""merged = _merge_codex_config(existing, base)if keep_mcp_servers:- merged = _with_user_codex_mcp_servers(merged, home)+ source = _codex_user_home(home)+ merged = _with_user_codex_mcp_servers(merged, home, source)+ _link_codex_user_files(home, source)if merged != existing:config.write_text(merged, encoding = "utf-8")typer.echo(f"Updated {config}")@@ -3780,6 +3789,85 @@ def _create_directory_junction(source: Path, target: Path) -> bool:return result.returncode == 0+def _link_codex_entry(source: Path, target: Path) -> bool:+ _remove_overlay_entry(target)+ try:+ target.symlink_to(source, target_is_directory = source.is_dir())+ return True+ except OSError:+ pass+ if source.is_file():+ # Only auth.json: Codex rewrites it in place, but a SQLite db under a second name keeps its own WAL and corrupts (sqlite.org/howtocorrupt.html 2.6).+ if source.name == "auth.json":+ with contextlib.suppress(OSError):+ os.link(source, target)+ return True+ shutil.copy2(source, target)+ return True+ if source.is_dir():+ if _create_directory_junction(source, target):+ return True+ if source.name in _CODEX_COPIED_DIRS:+ shutil.copytree(source, target)+ return True+ return False+++def _link_codex_user_files(home: Path, source: Path) -> None:+ manifest = home / _CODEX_USER_FILES_MANIFEST+ try:+ linked = json.loads(manifest.read_text(encoding = "utf-8"))["entries"]+ except (OSError, ValueError, TypeError, KeyError):+ linked = []+ for entry in linked if isinstance(linked, list) else []:+ parts = entry.split("/") if isinstance(entry, str) else []+ if (+ 0 < len(parts) <= 2+ and parts[0] in _CODEX_USER_FILES+ and all(part not in ("", ".", "..") and "\\" not in part for part in parts)+ and os.path.lexists(home.joinpath(*parts))+ ):+ _remove_overlay_entry(home.joinpath(*parts))+ entries = []+ for name in _CODEX_USER_FILES:+ # Resolved: a relative or temporary source would leave dangling links.+ entry = (source / name).resolve(strict = False)+ target = home / name+ if not entry.exists():+ continue+ if name == "rules" and entry.is_dir() and not os.path.lexists(target):+ # Codex appends approvals to rules/default.rules: a linked dir would write them into the user's.+ target.mkdir()+ if not os.path.lexists(target):+ if _link_codex_entry(entry, target):+ entries.append(name)+ elif (+ entry.is_dir()+ and target.is_dir()+ and not target.is_symlink()+ and not _is_junction(target)+ ):+ # Codex creates skills/.system in every home it runs in.+ for child in entry.iterdir():+ child_target = target / child.name+ if name == "rules" and child.is_file():+ # Codex skips symlinked *.rules (DirEntry::file_type); default.rules stays this home's.+ if child.name == "default.rules" or os.path.lexists(child_target):+ child_target = target / f"user-{child.name}"+ if os.path.lexists(child_target):+ continue+ try:+ os.link(child.resolve(strict = False), child_target)+ except OSError:+ shutil.copy2(child, child_target)+ elif os.path.lexists(child_target) or not _link_codex_entry(+ child.resolve(strict = False), child_target+ ):+ continue+ entries.append(f"{name}/{child_target.name}")+ _write_private_json(manifest, {"entries": entries})++def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:"""Add local-agent routing without replacing the cloud parent's configuration."""overlay.mkdir(parents = True, exist_ok = True, mode = 0o700)@@ -3816,8 +3904,6 @@ def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:for target in list(overlay.iterdir()):_remove_overlay_entry(target)- # Keep the user's auth, config, plugins, agents, skills, rules and session state visible. Symlinks make this an overlay rather than a stale copy; if Windows denies them, directory junctions keep large runtime state shared without a bulk copy, and the configuration surfaces and sessions are copied only when both link forms are unavailable.- fallback_dirs = {"agents", "skills", "rules", "plugins", "marketplaces", "sessions"}entries = []if source_home.is_dir():for source in source_home.iterdir():@@ -3827,28 +3913,8 @@ def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:_CODEX_PARENT_OVERLAY_MANIFEST,}:continue- target = overlay / source.name- _remove_overlay_entry(target)- try:- target.symlink_to(source, target_is_directory = source.is_dir())+ if _link_codex_entry(source, overlay / source.name):entries.append(source.name)- except OSError:- if source.is_file():- # Only auth.json: Codex rewrites it in place, but a SQLite db under a second name keeps its own WAL and corrupts (sqlite.org/howtocorrupt.html 2.6).- linked = False- if source.name == "auth.json":- with contextlib.suppress(OSError):- os.link(source, target)- linked = True- if not linked:- shutil.copy2(source, target)- entries.append(source.name)- elif source.is_dir():- if _create_directory_junction(source, target):- entries.append(source.name)- elif source.name in fallback_dirs:- shutil.copytree(source, target)- entries.append(source.name)# Not signed in yet: a dangling link lands the first login in the user's home, not the overlay.auth = source_home / "auth.json"if not os.path.lexists(auth):diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.pyindex c865167c29c..b37c4c0e7be 100644--- a/unsloth_cli/tests/test_start.py+++ b/unsloth_cli/tests/test_start.py@@ -2831,6 +2831,123 @@ def test_codex_keeps_the_users_mcp_servers(fake_studio, tmp_path, monkeypatch):assert user_config.read_text() == '[mcp_servers.docs]\nurl = "http://127.0.0.1:9000/mcp"\n'+def test_codex_keeps_the_users_instructions_skills_rules_and_prompts(+ fake_studio, tmp_path, monkeypatch+):+ source_home = tmp_path / "user-codex"+ (source_home / "skills" / "release").mkdir(parents = True)+ (source_home / "skills" / "release" / "SKILL.md").write_text("release steps\n")+ (source_home / "rules").mkdir()+ (source_home / "rules" / "default.rules").write_text(+ 'prefix_rule(pattern = ["rm"], decision = "forbidden")\n'+ )+ (source_home / "prompts").mkdir()+ (source_home / "prompts" / "summarize.md").write_text("Summarize the diff.\n")+ (source_home / "AGENTS.md").write_text("Answer in French.\n")+ monkeypatch.setenv("CODEX_HOME", str(source_home))+ home = tmp_path / "agents" / "codex"++ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert (home / "AGENTS.md").read_text() == "Answer in French.\n"+ assert (home / "skills" / "release" / "SKILL.md").read_text() == "release steps\n"+ assert "forbidden" in (home / "rules" / "user-default.rules").read_text()+ assert not (home / "rules").is_symlink()+ assert (home / "prompts" / "summarize.md").read_text() == "Summarize the diff.\n"+ # Codex persists an approval by appending to $CODEX_HOME/rules/default.rules.+ with open(home / "rules" / "default.rules", "a") as rules:+ rules.write('prefix_rule(pattern = ["ls"], decision = "allow")\n')+ assert "allow" not in (source_home / "rules" / "default.rules").read_text()++ (source_home / "AGENTS.md").unlink()+ (source_home / "AGENTS.override.md").write_text("Answer in German.\n")+ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert (home / "AGENTS.override.md").read_text() == "Answer in German.\n"+ assert not os.path.lexists(home / "AGENTS.md")+ assert (source_home / "AGENTS.override.md").read_text() == "Answer in German.\n"+++def test_codex_refreshes_copied_user_files_without_symlinks(fake_studio, tmp_path, monkeypatch):+ source_home = tmp_path / "user-codex"+ (source_home / "skills" / "old").mkdir(parents = True)+ (source_home / "AGENTS.md").write_text("first\n")+ monkeypatch.setenv("CODEX_HOME", str(source_home))++ def deny_symlink(*args, **kwargs):+ raise OSError("symlinks unavailable")++ monkeypatch.setattr(Path, "symlink_to", deny_symlink)+ monkeypatch.setattr(start, "_create_directory_junction", lambda source, target: False)+ home = tmp_path / "agents" / "codex"+ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert (home / "skills" / "old").is_dir()++ (source_home / "AGENTS.md").write_text("second\n")+ (source_home / "skills" / "old").rmdir()+ (source_home / "skills" / "new").mkdir()+ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert (home / "AGENTS.md").read_text() == "second\n"+ assert not (home / "skills" / "old").exists()+ assert (home / "skills" / "new").is_dir()+++def test_codex_merges_user_rules_into_a_used_saved_home_as_real_files(+ fake_studio, tmp_path, monkeypatch+):+ source_home = tmp_path / "user-codex"+ (source_home / "rules").mkdir(parents = True)+ forbid = 'prefix_rule(pattern = ["rm"], decision = "forbidden")\n'+ (source_home / "rules" / "default.rules").write_text(forbid)+ (source_home / "rules" / "team.rules").write_text(forbid)+ monkeypatch.setenv("CODEX_HOME", str(source_home))+ home = tmp_path / "agents" / "codex"+ (home / "rules").mkdir(parents = True)+ approved = 'prefix_rule(pattern = ["ls"], decision = "allow")\n'+ (home / "rules" / "default.rules").write_text(approved)++ for _ in range(2):+ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ rules = {p.name: p for p in (home / "rules").iterdir()}+ assert set(rules) == {"default.rules", "user-default.rules", "team.rules"}+ assert not any(p.is_symlink() for p in rules.values())+ assert rules["default.rules"].read_text() == approved+ assert rules["user-default.rules"].read_text() == forbid+ assert rules["team.rules"].read_text() == forbid++ (source_home / "rules" / "team.rules").unlink()+ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert not os.path.lexists(home / "rules" / "team.rules")+ assert (source_home / "rules" / "default.rules").read_text() == forbid+++def test_codex_merges_user_skills_into_a_used_saved_home(fake_studio, tmp_path, monkeypatch):+ source_home = tmp_path / "user-codex"+ (source_home / "skills" / "release").mkdir(parents = True)+ (source_home / "skills" / "release" / "SKILL.md").write_text("release steps\n")+ monkeypatch.setenv("CODEX_HOME", str(source_home))+ home = tmp_path / "agents" / "codex"+ (home / "skills" / ".system").mkdir(parents = True)++ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert (home / "skills" / "release" / "SKILL.md").read_text() == "release steps\n"+ assert (home / "skills" / ".system").is_dir()+ assert not (source_home / "skills" / ".system").exists()++ shutil.rmtree(source_home / "skills" / "release")+ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert not os.path.lexists(home / "skills" / "release")+ assert (home / "skills" / ".system").is_dir()+++def test_codex_links_user_files_from_a_relative_codex_home(fake_studio, tmp_path, monkeypatch):+ (tmp_path / "user-codex").mkdir()+ (tmp_path / "user-codex" / "AGENTS.md").write_text("Answer in French.\n")+ monkeypatch.chdir(tmp_path)+ monkeypatch.setenv("CODEX_HOME", "user-codex")++ assert CliRunner().invoke(start.start_app, ["codex", "--no-launch"]).exit_code == 0+ assert (tmp_path / "agents" / "codex" / "AGENTS.md").read_text() == "Answer in French.\n"++def test_codex_keeps_mcp_servers_added_in_the_saved_home(fake_studio, tmp_path, monkeypatch):tomllib = pytest.importorskip("tomllib")user_home = tmp_path / "user-home"