Add account groups with isolated CODEX_HOME support

README.md

@@ -95,14 +95,30 @@ Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth-auto.exe" -Force -Error
 | Command | Description |
 |---------|-------------|
 | `codex-auth list [--live] [--api\|--skip-api]` | List all accounts. `--live` keeps refreshing the terminal view; `--api` forces remote refresh, while `--skip-api` forbids remote API use for this command. |
-| `codex-auth login [--device-auth]` | Run `codex login` (optionally with `--device-auth`), then add the current account |
+| `codex-auth login [--device-auth] [--group <name>]` | Run `codex login` (optionally with `--device-auth`), then add the current account to the default account set or a named group |
 | `codex-auth switch [--live] [--auto] [--api\|--skip-api]` | Switch the active account interactively. Without `--live` it exits after one switch; with `--live` it stays open and keeps refreshing. `--auto` requires `--live` and auto-switches away from the current account when the live view shows it as exhausted or returns a non-200 usage API status. |
 | `codex-auth switch <query>` | Switch the active account directly by row number, alias, or fuzzy match using stored local data only. |
 | `codex-auth remove [--live] [--api\|--skip-api]` | Interactive remove. `--live` keeps the picker open after each deletion; `--api` forces remote refresh and `--skip-api` forbids remote API use for this command. |
 | `codex-auth remove <query> [<query>...]` | Remove one or more accounts by row number, alias, email, account name, or `account_key` match using stored local data. |
 | `codex-auth remove --all` | Remove all stored accounts. |
 | `codex-auth status` | Show auto-switch, service, and usage status |
 
+### Account Groups
+
+Groups keep separate Codex account sets with their own `CODEX_HOME`. The `default` group is the normal Codex home. Named groups can be used to keep workspaces such as `work`, `trading`, or `personal` separate.
+
+See [docs/account-groups.md](./docs/account-groups.md) for the full command reference.
+
+| Command | Description |
+|---------|-------------|
+| `codex-auth group list` | List configured groups and account counts |
+| `codex-auth group create <name> [<account>...]` | Create a group and optionally copy existing accounts into it |
+| `codex-auth group <name> list [--live] [--api\|--skip-api]` | List accounts in one group |
+| `codex-auth group <name> login [--device-auth]` | Login and add the account directly to one group |
+| `codex-auth group <name> add <account> [<account>...]` | Copy accounts from another group into this group |
+| `codex-auth group <name> switch [--live] [--auto] [--api\|--skip-api]` | Switch the active account inside one group |
+| `codex-auth group <name> launch [-- <codext-arg>...]` | Launch `codext` with this group's `CODEX_HOME` |
+
 ### Import
 
 | Command | Description |
@@ -226,8 +242,11 @@ Add the currently logged-in Codex account:
 ```shell
 codex-auth login
 codex-auth login --device-auth
+codex-auth login --group work --device-auth
 ```
 
+`--group <name>` creates the group when needed and stores the logged-in account in that group's Codex home.
+
 ### Import
 
 #### Single File

docs/account-groups.md

@@ -0,0 +1,105 @@
+# Account Groups
+
+Account groups let one `codex-auth` installation manage multiple isolated Codex homes.
+Each group has its own `auth.json`, account registry, account snapshots, and sessions.
+
+The `default` group is the normal Codex home at `~/.codex`. Named groups are created under `~/codex-auth/groups/<name>`.
+
+## Create and Inspect Groups
+
+Create an empty group:
+
+```shell
+codex-auth group create work
+```
+
+List all groups:
+
+```shell
+codex-auth group list
+```
+
+Print a group's Codex home:
+
+```shell
+codex-auth group work path
+codex-auth group path work
+```
+
+Group names may contain letters, numbers, `_`, and `-`.
+
+## Login Into a Group
+
+Login directly into a group:
+
+```shell
+codex-auth group work login
+codex-auth group work login --device-auth
+```
+
+The top-level login command can also target a group:
+
+```shell
+codex-auth login --group work
+codex-auth login --group work --device-auth
+```
+
+If the group does not exist, login creates it first.
+
+## Copy or Import Accounts
+
+Copy existing accounts into a group by row number, alias, email, account name, or account key:
+
+```shell
+codex-auth group work add 01
+codex-auth group work add jane@example.com personal
+```
+
+The source account remains in its original group. When the selector matches the `default` group, that match is used first. Other groups are searched only when `default` has no match.
+
+Create a group and copy accounts in one command:
+
+```shell
+codex-auth group create work 01 jane@example.com
+```
+
+Import an auth file directly into a group:
+
+```shell
+codex-auth group work import /path/to/auth.json --alias work-main
+```
+
+Remove accounts from one group:
+
+```shell
+codex-auth group work remove 01
+codex-auth group work remove jane@example.com
+```
+
+Removing an account from one group does not remove it from other groups.
+
+## Use a Group
+
+List accounts in a group:
+
+```shell
+codex-auth group work list
+codex-auth group work list --skip-api
+```
+
+Switch the active account inside a group:
+
+```shell
+codex-auth group work switch
+codex-auth group work switch 02
+codex-auth group work switch --live --auto
+```
+
+Launch `codext` with a group's `CODEX_HOME`:
+
+```shell
+codex-auth group work launch
+codex-auth group work launch -- --model gpt-5.4
+```
+
+Arguments after `--` are passed to `codext`.

docs/implement.md

@@ -16,6 +16,7 @@ This document describes how `codex-auth` stores accounts, synchronizes auth file
 - `<codex_home>/accounts/auth.json.bak.YYYYMMDD-hhmmss[.N]`
 - `<codex_home>/accounts/registry.json.bak.YYYYMMDD-hhmmss[.N]`
 - `<codex_home>/sessions/...`
+- Account group behavior is documented in [docs/account-groups.md](./account-groups.md).
 
 ## File Permissions