claude-dev-env 8.15.1 → 8.16.0

package/.agents/skills/second-account-workers/SKILL.md

@@ -1,16 +1,33 @@
 ---
 name: second-account-workers
 description: >-
-  Run local headless Claude workers through the second-account picker.
-  Triggers: spawn a worker on the second account, offload a worker,
-  claude-ev worker, save main account usage.
+  Run local headless Claude workers through the account picker.
+  Triggers: spawn a worker on the second account or another extra account, offload a worker,
+  use a named Claude profile, save main account usage.
 ---
 
-# Second Account Workers
+# Extra account workers
 
 Use this skill when a task needs a local Claude worker and the session should
 save main account usage.
 
+## Configure extra profiles
+
+Run `claude_account_profile.py --profile-name NAME` for each extra profile.
+The script creates `<profiles root>/NAME` and the `claude-NAME.cmd` launcher.
+Running it again with the same name leaves the profile and launcher in place.
+
+To set worker order, put `extra-profiles.json` in the main Claude home. Write a
+JSON list of profile names, with the first choice first. Names use letters,
+digits, hyphens, and underscores. The worker uses the existing second profile
+when the file is absent. When the file exists, its list sets the full order.
+Keep `main` and `wait` out of the list because they name picker decisions.
+The picker tries each profile after checking the main account's expiring usage.
+For direct picker calls, `--second-config-dir` sets the first extra profile and
+each `--extra-config-dir` adds another in the order given.
+Picker JSON prints `config_dir` for the choice and meters under `main`, `second`,
+`extra_2`, and later labels.
+
 ## Choose a worker
 
 Keep the Agent tool for small, fast lookups. For any worker that edits code,
@@ -34,10 +51,11 @@ Read the JSON report and worker log after the process ends. The JSON fields are
 The runner writes one summary line with the selected account, exit code, and
 report path.
 
-When the command exits 3 and the report has `"account": "wait"`, both accounts
-are out of room. Report the picker's reason and reset time. Do not fall back to
-the Agent tool. Claude can also return exit 3 after a worker starts. When the
-report account is `main` or `second`, report the child's exit code and result.
+When the command exits 3 and the report has `"account": "wait"`, no account is
+eligible. Report the picker's reason and reset time. Do not fall back to the
+Agent tool. Claude can also return exit 3 after a worker starts. When the
+report account is `main`, `second`, or `extra_2` and later, report the child's
+exit code and result.
 
 Workers never commit, push, or call `gh`. The calling session reviews each
 worktree diff and owns every Git step.

package/package.json

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

package/scripts/claude_account_choice.py

@@ -1,21 +1,8 @@
 #!/usr/bin/env python3
-"""Name the Claude account a runner job uses, protecting the main account.
+"""Choose a Claude account for a runner job while protecting the main account.
 
-The main account is the one its owner works on, so a job borrows it only to
-spend leftover usage that expires soon. Every other job goes to the second
-account while that account has room, and waits when it has none::
-
-    main week resets in 5 hours, 20% left, 5-hour window 10% used -> main
-    main week resets in 3 days                                    -> second
-    second at 99% of its week, main not spendable                 -> wait
-    main meter unread                                             -> never main
-
-::
-
-    python claude_account_choice.py --main-config-dir C:/Users/me/.claude
-        --second-config-dir C:/Users/me/.claude-profiles/ev
-    {"account": "second", "config_dir": "C:/Users/me/.claude-profiles/ev",
-     "reason": "second account has 60% of its week and 90% of its 5-hour window left"}
+The main account takes a job only to spend usage that expires soon. Otherwise,
+the picker tries extra profiles in order and waits when every one is full.
 """
 
 from __future__ import annotations
@@ -23,6 +10,7 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+from collections.abc import Sequence
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
@@ -52,6 +40,9 @@ from dev_env_scripts_constants.claude_account_constants import (
     MAIN_SPEND_WINDOW,
     MAIN_WEEKLY_USED_CEILING_PERCENT,
     REASON_MAIN_EXPIRING_TEMPLATE,
+    REASON_ALL_EXTRAS_WAIT_TEMPLATE,
+    REASON_EXTRA_HAS_ROOM_TEMPLATE,
+    REASON_EXTRA_UNREAD_TEMPLATE,
     REASON_SECOND_HAS_ROOM_TEMPLATE,
     REASON_SECOND_UNREAD,
     REASON_WAIT_TEMPLATE,
@@ -70,6 +61,15 @@ class AccountDecision:
     reason: str
 
 
+@dataclass(frozen=True)
+class ExtraAccount:
+    """One ordered extra profile and its usage reading."""
+
+    name: str
+    meters: AccountUsageMeters | None
+    config_dir: Path | None = None
+
+
 def _main_spendable_reason(
     main_meters: AccountUsageMeters | None, now: datetime
 ) -> str | None:
@@ -92,14 +92,23 @@ def _main_spendable_reason(
     )
 
 
-def _wait_decision(
-    second_meters: AccountUsageMeters, *, is_week_blocked: bool
-) -> AccountDecision:
-    blocking_reset = (
-        second_meters.weekly_resets_at
-        if is_week_blocked
-        else second_meters.session_resets_at
-    )
+def _blocking_reset(meters: AccountUsageMeters) -> datetime | None:
+    all_blocking_resets: list[datetime] = []
+    weekly_used = meters.weekly_utilization
+    session_used = meters.session_utilization
+    if weekly_used is not None and weekly_used >= SECOND_WEEKLY_USED_CEILING_PERCENT:
+        if meters.weekly_resets_at is None:
+            return None
+        all_blocking_resets.append(meters.weekly_resets_at)
+    if session_used is not None and session_used >= SECOND_SESSION_USED_CEILING_PERCENT:
+        if meters.session_resets_at is None:
+            return None
+        all_blocking_resets.append(meters.session_resets_at)
+    return max(all_blocking_resets, default=None)
+
+
+def _wait_decision(second_meters: AccountUsageMeters) -> AccountDecision:
+    blocking_reset = _blocking_reset(second_meters)
     return AccountDecision(
         account=CHOICE_WAIT,
         reason=REASON_WAIT_TEMPLATE.format(
@@ -112,28 +121,83 @@ def _wait_decision(
     )
 
 
-def _second_account_decision(
-    second_meters: AccountUsageMeters | None,
-) -> AccountDecision:
-    if second_meters is None:
-        return AccountDecision(account=CHOICE_SECOND, reason=REASON_SECOND_UNREAD)
-    session_used = second_meters.session_utilization
-    weekly_used = second_meters.weekly_utilization
+def _extra_account_decision(extra_account: ExtraAccount) -> AccountDecision | None:
+    meters = extra_account.meters
+    unread_reason = (
+        REASON_SECOND_UNREAD
+        if extra_account.name == CHOICE_SECOND
+        else REASON_EXTRA_UNREAD_TEMPLATE.format(account=extra_account.name)
+    )
+    if meters is None:
+        return AccountDecision(account=extra_account.name, reason=unread_reason)
+    session_used = meters.session_utilization
+    weekly_used = meters.weekly_utilization
     if session_used is None or weekly_used is None:
-        return AccountDecision(account=CHOICE_SECOND, reason=REASON_SECOND_UNREAD)
+        return AccountDecision(account=extra_account.name, reason=unread_reason)
     is_week_blocked = weekly_used >= SECOND_WEEKLY_USED_CEILING_PERCENT
     is_session_blocked = session_used >= SECOND_SESSION_USED_CEILING_PERCENT
     if is_week_blocked or is_session_blocked:
-        return _wait_decision(second_meters, is_week_blocked=is_week_blocked)
+        return None
+    reason_template = (
+        REASON_SECOND_HAS_ROOM_TEMPLATE
+        if extra_account.name == CHOICE_SECOND
+        else REASON_EXTRA_HAS_ROOM_TEMPLATE
+    )
     return AccountDecision(
-        account=CHOICE_SECOND,
-        reason=REASON_SECOND_HAS_ROOM_TEMPLATE.format(
+        account=extra_account.name,
+        reason=reason_template.format(
+            account=extra_account.name,
             weekly_remaining_percent=FULL_PERCENT - weekly_used,
             session_remaining_percent=FULL_PERCENT - session_used,
         ),
     )
 
 
+def choose_account_from_extras(
+    *,
+    main_meters: AccountUsageMeters | None,
+    all_extra_accounts: Sequence[ExtraAccount],
+    now: datetime,
+) -> AccountDecision:
+    """Choose main or the first extra profile with room in list order.
+
+    Args:
+        main_meters: The main account's meters, or None when unread.
+        all_extra_accounts: The extra accounts in the order they are tried.
+        now: The time the reset windows are measured from.
+
+    Returns:
+        The chosen account and the reason, or a wait naming the soonest reset.
+    """
+    main_reason = _main_spendable_reason(main_meters, now)
+    if main_reason is not None:
+        return AccountDecision(account=CHOICE_MAIN, reason=main_reason)
+    for each_extra_account in all_extra_accounts:
+        decision = _extra_account_decision(each_extra_account)
+        if decision is not None:
+            return decision
+    return _all_extras_wait_decision(all_extra_accounts)
+
+
+def _all_extras_wait_decision(
+    all_extra_accounts: Sequence[ExtraAccount],
+) -> AccountDecision:
+    if len(all_extra_accounts) == 1 and all_extra_accounts[0].meters is not None:
+        return _wait_decision(all_extra_accounts[0].meters)
+    all_resets = (
+        _blocking_reset(each_extra_account.meters)
+        for each_extra_account in all_extra_accounts
+        if each_extra_account.meters is not None
+    )
+    next_reset = min((reset for reset in all_resets if reset is not None), default=None)
+    return AccountDecision(
+        account=CHOICE_WAIT,
+        reason=REASON_ALL_EXTRAS_WAIT_TEMPLATE.format(
+            next_reset=next_reset.isoformat() if next_reset else UNKNOWN_RESET_TEXT
+        ),
+    )
+
+
 def choose_account(
     *,
     main_meters: AccountUsageMeters | None,
@@ -159,10 +223,11 @@ def choose_account(
     Returns:
         The chosen account and the reason.
     """
-    main_reason = _main_spendable_reason(main_meters, now)
-    if main_reason is not None:
-        return AccountDecision(account=CHOICE_MAIN, reason=main_reason)
-    return _second_account_decision(second_meters)
+    return choose_account_from_extras(
+        main_meters=main_meters,
+        all_extra_accounts=(ExtraAccount(name=CHOICE_SECOND, meters=second_meters),),
+        now=now,
+    )
 
 
 def read_account_meters(credentials_path: Path) -> AccountUsageMeters | None:
@@ -180,6 +245,64 @@ def read_account_meters(credentials_path: Path) -> AccountUsageMeters | None:
         return None
 
 
+def read_extra_accounts(
+    all_config_directories: Sequence[Path],
+) -> tuple[ExtraAccount, ...]:
+    """Read ordered extra profiles and reject duplicate directories.
+
+    Args:
+        all_config_directories: The extra profile homes in the order they are tried.
+
+    Returns:
+        One extra account per directory, with its meters.
+
+    Raises:
+        ValueError: When two entries name the same directory.
+    """
+    all_resolved_directories = [
+        str(each_directory.resolve()).casefold()
+        for each_directory in all_config_directories
+    ]
+    if len(set(all_resolved_directories)) != len(all_config_directories):
+        raise ValueError("extra account config directories must be distinct")
+    return tuple(
+        ExtraAccount(
+            name=CHOICE_SECOND if each_index == 1 else f"extra_{each_index}",
+            meters=read_account_meters(each_directory / CREDENTIALS_FILE_NAME),
+            config_dir=each_directory,
+        )
+        for each_index, each_directory in enumerate(all_config_directories, start=1)
+    )
+
+
+def config_directory_for_decision(
+    decision: AccountDecision,
+    *,
+    main_config_dir: Path,
+    all_extra_accounts: Sequence[ExtraAccount],
+) -> Path | None:
+    """Find the selected account's config directory.
+
+    Args:
+        decision: The chosen account and reason.
+        main_config_dir: The main account's Claude home.
+        all_extra_accounts: The extra accounts the decision chose from.
+
+    Returns:
+        The chosen account's Claude home, or None on wait.
+    """
+    if decision.account == CHOICE_MAIN:
+        return main_config_dir
+    return next(
+        (
+            each_extra_account.config_dir
+            for each_extra_account in all_extra_accounts
+            if each_extra_account.name == decision.account
+        ),
+        None,
+    )
+
+
 def _build_argument_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Name the Claude account a runner job uses."
@@ -194,6 +317,7 @@ def _build_argument_parser() -> argparse.ArgumentParser:
         type=Path,
         default=default_profile_home(),
     )
+    parser.add_argument("--extra-config-dir", type=Path, action="append", default=[])
     return parser
 
 
@@ -253,7 +377,7 @@ def meters_payload(
 
 
 def main(all_command_arguments: list[str]) -> int:
-    """Print the chosen account and both accounts' meters as JSON.
+    """Print the chosen account and every account's meters as JSON.
 
     Args:
         all_command_arguments: Command-line arguments after the program name.
@@ -261,26 +385,33 @@ def main(all_command_arguments: list[str]) -> int:
     Returns:
         Zero once the choice is printed.
     """
-    arguments = _build_argument_parser().parse_args(all_command_arguments)
-    config_directory_by_account = {
-        CHOICE_MAIN: arguments.main_config_dir,
-        CHOICE_SECOND: arguments.second_config_dir,
-    }
+    parser = _build_argument_parser()
+    arguments = parser.parse_args(all_command_arguments)
+    try:
+        extra_accounts = read_extra_accounts(
+            (arguments.second_config_dir, *arguments.extra_config_dir)
+        )
+    except ValueError as error:
+        parser.error(str(error))
     main_meters = read_account_meters(arguments.main_config_dir / CREDENTIALS_FILE_NAME)
-    second_meters = read_account_meters(
-        arguments.second_config_dir / CREDENTIALS_FILE_NAME
-    )
-    decision = choose_account(
+    decision = choose_account_from_extras(
         main_meters=main_meters,
-        second_meters=second_meters,
+        all_extra_accounts=extra_accounts,
         now=datetime.now().astimezone(),
     )
-    config_directory = config_directory_by_account.get(decision.account)
+    config_directory = config_directory_for_decision(
+        decision,
+        main_config_dir=arguments.main_config_dir,
+        all_extra_accounts=extra_accounts,
+    )
     report = {
         **decision_payload(decision, config_directory=config_directory),
         JSON_METERS_KEY: {
             CHOICE_MAIN: meters_payload(main_meters),
-            CHOICE_SECOND: meters_payload(second_meters),
+            **{
+                extra_account.name: meters_payload(extra_account.meters)
+                for extra_account in extra_accounts
+            },
         },
     }
     print(json.dumps(report))

package/scripts/claude_account_profile.py

@@ -1,26 +1,10 @@
 #!/usr/bin/env python3
-"""Keep the second account's Claude profile linked to the main Claude home.
+"""Keep a named extra Claude profile linked to the main Claude home.
 
-The second account runs Claude with its own sign-in and history, and with
-everything else the main home holds: skills, rules, plugins, settings, docs::
-
-    main home                 profile home (second account)
-    skills/          <-----   skills/            link
-    CLAUDE.md        <-----   CLAUDE.md          link
-    .credentials.json         .credentials.json  its own sign-in
-    projects/                 projects/          its own history
-
-Each run converges the profile on that picture. A stale copy moves into
-``.replaced/<time>/`` with its content kept, a link whose main entry is gone
-is removed, a main link under an account-local name such as a credentials
-backup is removed, and a second run changes nothing. The run also writes the
-``claude-ev.cmd`` launcher that starts Claude on this profile.
-
-::
-
-    python claude_account_profile.py
-    {"linked": ["CLAUDE.md"], "moved_aside": [], "unlinked": [],
-     "launcher": "C:/Users/me/.local/bin/claude-ev.cmd"}
+Each profile keeps its own sign-in and history while sharing the main home's
+skills, rules, plugins, settings, and docs. Stale shared copies move into
+``.replaced/<time>/``. A second run with the same name changes nothing. The
+launcher is named ``claude-<profile-name>.cmd``.
 """
 
 from __future__ import annotations
@@ -29,6 +13,7 @@ import argparse
 import filecmp
 import json
 import os
+import re
 import subprocess
 import sys
 from collections.abc import Callable
@@ -39,18 +24,22 @@ from pathlib import Path
 from dev_env_scripts_constants.claude_account_constants import (
     ALL_ACCOUNT_LOCAL_NAME_PREFIXES,
     ALL_ACCOUNT_LOCAL_NAMES,
+    ALL_WINDOWS_RESERVED_PROFILE_NAMES,
     ALL_WINDOWS_JUNCTION_COMMAND_PREFIX,
+    CHOICE_MAIN,
+    CHOICE_WAIT,
     JSON_LAUNCHER_KEY,
     JSON_LINKED_KEY,
     JSON_MOVED_ASIDE_KEY,
     JSON_UNLINKED_KEY,
     ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS,
-    LAUNCHER_FILE_NAME,
+    LAUNCHER_FILE_NAME_TEMPLATE,
     LAUNCHER_REPLACED_SUFFIX,
     LAUNCHER_TEXT_TEMPLATE,
     MAIN_CLAUDE_HOME_DIRECTORY_NAME,
     PROFILES_ROOT_DIRECTORY_NAME,
     PROFILES_ROOT_ENVIRONMENT_VARIABLE,
+    PROFILE_NAME_PATTERN,
     REPLACED_DIRECTORY_NAME,
     REPLACED_STAMP_FORMAT,
     SECOND_ACCOUNT_PROFILE_NAME,
@@ -69,8 +58,32 @@ class ProfileSyncReport:
     all_unlinked: tuple[str, ...]
 
 
-def default_profile_home() -> Path:
-    """Locate the second account's profile directory.
+def validate_profile_name(profile_name: str) -> str:
+    """Accept a profile name safe for a directory and command launcher.
+
+    Args:
+        profile_name: The name to check.
+
+    Returns:
+        The same name.
+
+    Raises:
+        ValueError: When the name has other characters or is reserved.
+    """
+    reserved_names = ALL_WINDOWS_RESERVED_PROFILE_NAMES | {CHOICE_MAIN, CHOICE_WAIT}
+    if (
+        re.fullmatch(PROFILE_NAME_PATTERN, profile_name) is None
+        or profile_name.casefold() in reserved_names
+    ):
+        raise ValueError("profile name must use letters, digits, hyphens, or underscores")
+    return profile_name
+
+
+def default_profile_home(profile_name: str = SECOND_ACCOUNT_PROFILE_NAME) -> Path:
+    """Locate a named extra account's profile directory.
+
+    Args:
+        profile_name: The profile's name under the profiles root.
 
     Returns:
         The profile under the profiles root the environment names, else under
@@ -82,7 +95,7 @@ def default_profile_home() -> Path:
         if profiles_root
         else Path.home() / PROFILES_ROOT_DIRECTORY_NAME
     )
-    return root / SECOND_ACCOUNT_PROFILE_NAME
+    return root / validate_profile_name(profile_name)
 
 
 def is_account_local(entry_name: str) -> bool:
@@ -296,36 +309,47 @@ def sync_profile(
     )
 
 
-def _moved_launcher_name(now: datetime) -> str:
-    return f"{LAUNCHER_FILE_NAME}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
+def _moved_launcher_name(launcher_file_name: str, now: datetime) -> str:
+    return f"{launcher_file_name}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
 
 
 def write_launcher(
-    *, launcher_directory: Path, profile_home: Path, now: datetime
+    *,
+    launcher_directory: Path,
+    profile_home: Path,
+    now: datetime,
+    profile_name: str = SECOND_ACCOUNT_PROFILE_NAME,
 ) -> Path:
-    """Write the launcher that runs Claude under the second account's profile.
+    """Write the launcher that runs Claude under a named profile.
 
     ::
 
-        claude-ev -p "fix the test"
+        claude-NAME -p "fix the test"
         -> CLAUDE_CONFIG_DIR=<profile home>, then claude -p "fix the test"
-        an older claude-ev.cmd -> claude-ev.cmd.replaced-<time>
+        an older claude-NAME.cmd -> claude-NAME.cmd.replaced-<time>
 
     Args:
         launcher_directory: The directory on PATH that holds the launcher.
-        profile_home: The second account's Claude home.
+        profile_home: The named account's Claude home.
         now: The run time that names a moved older launcher.
+        profile_name: The name used in the launcher file name.
 
     Returns:
         The launcher path.
     """
-    launcher_path = launcher_directory / LAUNCHER_FILE_NAME
+    launcher_file_name = LAUNCHER_FILE_NAME_TEMPLATE.format(
+        profile_name=validate_profile_name(profile_name)
+    )
+    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(now)))
+        os.replace(
+            launcher_path,
+            launcher_path.with_name(_moved_launcher_name(launcher_file_name, now)),
+        )
     launcher_directory.mkdir(parents=True, exist_ok=True)
     launcher_path.write_bytes(launcher_bytes)
     return launcher_path
@@ -338,7 +362,8 @@ def _build_argument_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--main-home", type=Path, default=Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME
     )
-    parser.add_argument("--profile-home", type=Path, default=default_profile_home())
+    parser.add_argument("--profile-name", default=SECOND_ACCOUNT_PROFILE_NAME)
+    parser.add_argument("--profile-home", type=Path)
     parser.add_argument(
         "--launcher-directory",
         type=Path,
@@ -356,27 +381,34 @@ def main(all_command_arguments: list[str]) -> int:
     Returns:
         Zero once the profile and launcher match the main home.
     """
-    arguments = _build_argument_parser().parse_args(all_command_arguments)
+    parser = _build_argument_parser()
+    arguments = parser.parse_args(all_command_arguments)
+    try:
+        validate_profile_name(arguments.profile_name)
+    except ValueError as error:
+        parser.error(str(error))
+    print(json.dumps(_sync_named_profile(arguments)))
+    return 0
+
+
+def _sync_named_profile(arguments: argparse.Namespace) -> dict[str, object]:
+    profile_home = arguments.profile_home or default_profile_home(arguments.profile_name)
     now = datetime.now(timezone.utc)
     report = sync_profile(
-        main_home=arguments.main_home, profile_home=arguments.profile_home, now=now
+        main_home=arguments.main_home, profile_home=profile_home, now=now
     )
     launcher_path = write_launcher(
         launcher_directory=arguments.launcher_directory,
-        profile_home=arguments.profile_home,
+        profile_home=profile_home,
         now=now,
+        profile_name=arguments.profile_name,
     )
-    print(
-        json.dumps(
-            {
-                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 0
+    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),
+    }
 
 
 if __name__ == "__main__":