claude-dev-env 8.34.0 → 8.35.1

package/docs/codex-accounts.md

@@ -1,24 +1,31 @@
 # Codex accounts
 
-The codex_account_choice picker spreads agent work across up to four Codex
-accounts on one machine. Each account signs in under
-its own Codex home, and every home shares the same Codex setup: config, rules,
-skills, plugins and prompts. A job asks the picker which account to use.
+The codex_account_choice picker spreads agent work across the Codex accounts
+on one machine. Each account signs in under its own Codex home, and every home
+shares the same Codex setup: config, rules, skills, plugins, prompts and agents.
+A job asks the picker which account to use.
 
 ## Pieces
 
 | File | What it does |
 |---|---|
-| `scripts/codex_account_choice.py` | `choose` names the account and tier a job runs on, `check` tells a running job whether its account is still above a floor, `sync` links the shared setup into every account's home |
+| `scripts/codex_account_choice.py` | `choose` names the account and tier a job runs on, `check` tells a running job whether its account is still above a floor, `sync` links the shared setup into every account's home, `setup` and `install` write one launcher per account |
 | `scripts/codex_account_meters.py` | Reads one account's rate-limit windows through `codex app-server` with `CODEX_HOME` set to that account's home |
-| `scripts/dev_env_scripts_constants/codex_account_constants.py` | The account names in try order, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
+| `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
 
 ## Names and order
 
-The accounts are `codex-1`, `codex-2`, `codex-3` and `codex-4`. Their homes are
-`~/.codex-profiles/codex-1` and so on, or under `CODEX_PROFILES_ROOT` when set.
-Jobs try them in that order. The names say nothing about a plan, so a plan change
-keeps every name. To change the order, sign the accounts into different folders.
+The account roster names the accounts and their order. It comes from the
+`CODEX_ACCOUNT_PROFILES` environment variable, a comma-separated list such as
+`alpha,beta`. When that variable is unset or empty, the roster is the saved list
+in `account-launchers.json` under the profiles root. When neither exists, the
+accounts are `codex-1`, `codex-2`, `codex-3` and `codex-4`.
+
+`choose`, `sync` and `check` all work on that list, in that order. `check`
+accepts only a name on it. Each account's home is `~/.codex-profiles/<name>`, or
+`<name>` under `CODEX_PROFILES_ROOT` when set. `~/.codex` holds the shared setup
+and is never an account. A name uses letters, digits, hyphens or underscores.
+`main`, `wait` and the Windows device names are refused.
 
 ## Sign in once
 
@@ -33,8 +40,54 @@ $env:CODEX_HOME = "$HOME\.codex-profiles\codex-1"; codex login
 ```
 
 The sign-in lives in that folder's `auth.json`. Only the entries in
-`ALL_SHARED_CODEX_HOME_NAMES` link to `~/.codex`. Sign-in, sessions, history,
-logs and state files stay per account.
+`ALL_SHARED_CODEX_HOME_NAMES` link to `~/.codex`. They are `AGENTS.md`, `agents`,
+`config.toml`, `hooks`, `hooks.json`, `plugins`, `prompts`, `rules` and `skills`.
+Sign-in, sessions, history, logs and state files stay per account.
+
+## Named launchers
+
+Each roster account gets a launcher, `codex-<name>.cmd`, in `~/.local/bin`. It
+sets `CODEX_HOME` to that account's home and runs Codex with every argument, so
+`codex-alpha exec "fix the test"` runs on the `alpha` account.
+
+Run the setup once:
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py setup
+```
+
+It prints the saved names, then asks for one name per line. A blank line or the
+end of input finishes. An invalid name prints the reason and asks again. A
+repeated name counts once. The setup saves the list to
+`~/.codex-profiles/account-launchers.json`, links each account's home to
+`~/.codex`, and writes each launcher.
+
+Rerun the installer after the shared setup or this package changes:
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py install
+```
+
+It reads the roster, links every account's home, and rewrites any launcher that
+differs. A second run changes nothing. With no roster it prints `{}`.
+`CODEX_ACCOUNT_PROFILES` overrides the saved file here too. Both commands take
+`--main-home` and `--launcher-directory`.
+
+The launcher runs `call codex %*`. `codex` is npm's `codex.cmd`, and its last
+line ends the batch scope. Without `call`, that line also drops the launcher's
+`CODEX_HOME`, and Codex runs on the main home.
+
+The names typed in one setup run become the whole roster. A saved name
+left out has its launcher renamed to `codex-<name>.cmd.replaced-<time>`. Its
+folder under the profiles root stays, with its `auth.json`, so typing the name
+again restores it. A blank first line empties the roster and moves every launcher
+aside.
+
+`check <name>` reads a saved name the same way:
+
+```
+python packages/claude-dev-env/scripts/codex_account_choice.py check alpha --floor 1
+```
 
 ## Which account a job uses
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.34.0",
+    "version": "8.35.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/claude_account_profile.py

@@ -28,14 +28,15 @@ from dev_env_scripts_constants.claude_account_constants import (
     ALL_WINDOWS_JUNCTION_COMMAND_PREFIX,
     CHOICE_MAIN,
     CHOICE_WAIT,
+    CLAUDE_LAUNCHER_PROGRAM,
     JSON_LAUNCHER_KEY,
     JSON_LINKED_KEY,
     JSON_MOVED_ASIDE_KEY,
     JSON_UNLINKED_KEY,
     ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS,
-    LAUNCHER_FILE_NAME_TEMPLATE,
+    LAUNCHER_BODY_TEMPLATE,
     LAUNCHER_REPLACED_SUFFIX,
-    LAUNCHER_TEXT_TEMPLATE,
+    LauncherProgram,
     MAIN_CLAUDE_HOME_DIRECTORY_NAME,
     PROFILES_ROOT_DIRECTORY_NAME,
     PROFILES_ROOT_ENVIRONMENT_VARIABLE,
@@ -309,8 +310,58 @@ def sync_profile(
     )
 
 
-def _moved_launcher_name(launcher_file_name: str, now: datetime) -> str:
-    return f"{launcher_file_name}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
+def sync_report_payload(report: ProfileSyncReport) -> dict[str, object]:
+    """Turn a sync report into its JSON payload.
+
+    Args:
+        report: The entries one sync linked, moved aside, and unlinked.
+
+    Returns:
+        The linked, moved-aside, and unlinked entries as JSON lists.
+    """
+    return {
+        JSON_LINKED_KEY: list(report.all_linked),
+        JSON_MOVED_ASIDE_KEY: list(report.all_moved_aside),
+        JSON_UNLINKED_KEY: list(report.all_unlinked),
+    }
+
+
+def move_launcher_aside(launcher_path: Path, now: datetime) -> Path:
+    """Rename a launcher to ``<name>.replaced-<time>`` beside it.
+
+    Args:
+        launcher_path: The launcher to move.
+        now: The run time that names the moved launcher.
+
+    Returns:
+        The moved launcher's path.
+    """
+    moved_path = launcher_path.with_name(
+        f"{launcher_path.name}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
+    )
+    os.replace(launcher_path, moved_path)
+    return moved_path
+
+
+def launcher_path(
+    launcher_directory: Path, profile_name: str, launcher_program: LauncherProgram
+) -> Path:
+    """Name the launcher file for a profile.
+
+    Args:
+        launcher_directory: The directory on PATH that holds the launcher.
+        profile_name: The name used in the launcher file name.
+        launcher_program: The program the launcher runs, which names the file.
+
+    Returns:
+        The launcher path.
+
+    Raises:
+        ValueError: When the profile name is not a valid profile name.
+    """
+    return launcher_directory / launcher_program.file_name_template.format(
+        profile_name=validate_profile_name(profile_name)
+    )
 
 
 def write_launcher(
@@ -318,41 +369,41 @@ def write_launcher(
     launcher_directory: Path,
     profile_home: Path,
     now: datetime,
-    profile_name: str = SECOND_ACCOUNT_PROFILE_NAME,
+    profile_name: str,
+    launcher_program: LauncherProgram,
 ) -> Path:
-    """Write the launcher that runs Claude under a named profile.
+    """Write the launcher that runs a program under a named profile.
 
     ::
 
         claude-NAME -p "fix the test"
-        -> CLAUDE_CONFIG_DIR=<profile home>, then claude -p "fix the test"
+        -> CLAUDE_CONFIG_DIR=<profile home>, then call claude -p "fix the test"
         an older claude-NAME.cmd -> claude-NAME.cmd.replaced-<time>
 
     Args:
         launcher_directory: The directory on PATH that holds the launcher.
-        profile_home: The named account's Claude home.
+        profile_home: The named account's home for the program.
         now: The run time that names a moved older launcher.
         profile_name: The name used in the launcher file name.
+        launcher_program: The program to run and the variable naming its home.
 
     Returns:
         The launcher path.
     """
-    launcher_file_name = LAUNCHER_FILE_NAME_TEMPLATE.format(
-        profile_name=validate_profile_name(profile_name)
+    target_path = launcher_path(launcher_directory, profile_name, launcher_program)
+    launcher_text = LAUNCHER_BODY_TEMPLATE.format(
+        environment_variable=launcher_program.environment_variable,
+        profile_home=profile_home,
+        program=launcher_program.program,
     )
-    launcher_path = launcher_directory / launcher_file_name
-    launcher_text = LAUNCHER_TEXT_TEMPLATE.format(profile_home=profile_home)
     launcher_bytes = launcher_text.encode(TEXT_ENCODING)
-    if launcher_path.is_file() and launcher_path.read_bytes() == launcher_bytes:
-        return launcher_path
-    if launcher_path.is_file():
-        os.replace(
-            launcher_path,
-            launcher_path.with_name(_moved_launcher_name(launcher_file_name, now)),
-        )
+    if target_path.is_file() and target_path.read_bytes() == launcher_bytes:
+        return target_path
+    if target_path.is_file():
+        move_launcher_aside(target_path, now)
     launcher_directory.mkdir(parents=True, exist_ok=True)
-    launcher_path.write_bytes(launcher_bytes)
-    return launcher_path
+    target_path.write_bytes(launcher_bytes)
+    return target_path
 
 
 def _build_argument_parser() -> argparse.ArgumentParser:
@@ -402,13 +453,9 @@ def _sync_named_profile(arguments: argparse.Namespace) -> dict[str, object]:
         profile_home=profile_home,
         now=now,
         profile_name=arguments.profile_name,
+        launcher_program=CLAUDE_LAUNCHER_PROGRAM,
     )
-    return {
-        JSON_LINKED_KEY: list(report.all_linked),
-        JSON_MOVED_ASIDE_KEY: list(report.all_moved_aside),
-        JSON_UNLINKED_KEY: list(report.all_unlinked),
-        JSON_LAUNCHER_KEY: str(launcher_path),
-    }
+    return {**sync_report_payload(report), JSON_LAUNCHER_KEY: str(launcher_path)}
 
 
 if __name__ == "__main__":