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: 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.py
index 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.py
index 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"