@victor-software-house/pi-multicodex 2.0.1 → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -196
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,252 +2,119 @@
|
|
|
2
2
|
|
|
3
3
|
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
MultiCodex is a [pi](https://github.com/badlogic/pi-mono) extension that manages multiple ChatGPT Codex accounts and rotates between them automatically when you hit quota limits.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
You add your Codex accounts once. After that, MultiCodex transparently picks the account with the most remaining quota for every request. When one account runs dry mid-session, it switches to another and retries — no manual intervention needed.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- auto-imports pi's stored `openai-codex` auth when it is new or changed
|
|
11
|
-
- rotates accounts on quota and rate-limit failures
|
|
12
|
-
- prefers untouched accounts when usage data is available
|
|
13
|
-
- otherwise prefers the account whose weekly window resets first
|
|
14
|
-
- keeps the implementation focused on Codex account rotation
|
|
9
|
+
## Getting started
|
|
15
10
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- one operator command family instead of scattered commands (`/multicodex ...`)
|
|
19
|
-
- account operations are fast in-session (`/multicodex use` picker with `Backspace` remove + confirmation)
|
|
20
|
-
- non-UI operations are available for inspection and recovery (`show`, `verify`, `path`, `reset`, `help`)
|
|
21
|
-
- settings and account state use stable local paths under `~/.pi/agent/`
|
|
22
|
-
- release and quality checks are automated through CI and semantic-release
|
|
23
|
-
|
|
24
|
-
## Install
|
|
11
|
+
Install from npm:
|
|
25
12
|
|
|
26
13
|
```bash
|
|
27
14
|
pi install npm:@victor-software-house/pi-multicodex
|
|
28
15
|
```
|
|
29
16
|
|
|
30
|
-
Restart
|
|
17
|
+
Restart pi. That is all you need — MultiCodex takes over the normal `openai-codex` provider path and auto-imports any Codex auth you have already set up in pi.
|
|
31
18
|
|
|
32
|
-
|
|
19
|
+
To manage your accounts inside a session, type `/multicodex`.
|
|
33
20
|
|
|
34
|
-
|
|
21
|
+
## How it works
|
|
35
22
|
|
|
36
|
-
|
|
37
|
-
mise install
|
|
38
|
-
pnpm install
|
|
39
|
-
pnpm check
|
|
40
|
-
```
|
|
23
|
+
When you start a session, MultiCodex:
|
|
41
24
|
|
|
42
|
-
|
|
25
|
+
1. Imports your existing pi Codex auth automatically (if present).
|
|
26
|
+
2. Checks usage data across all managed accounts.
|
|
27
|
+
3. Picks the account with the most headroom — preferring untouched accounts first, then the one whose weekly reset window ends soonest.
|
|
43
28
|
|
|
44
|
-
|
|
45
|
-
mise run install
|
|
46
|
-
mise run check
|
|
47
|
-
mise run pack-dry
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
Run the extension directly during local development:
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
pi -e ./index.ts
|
|
54
|
-
```
|
|
29
|
+
When a request hits a quota or rate limit **before** any output is streamed, MultiCodex marks that account exhausted, picks the next available one, and retries the request. This happens up to 5 times transparently. Once output has started streaming, the error is surfaced as-is.
|
|
55
30
|
|
|
56
|
-
##
|
|
31
|
+
## Commands
|
|
57
32
|
|
|
58
|
-
|
|
33
|
+
Everything lives under one command: `/multicodex`.
|
|
59
34
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
- `/multicodex rotation`
|
|
72
|
-
- show current hard-coded rotation policy
|
|
73
|
-
- `/multicodex verify`
|
|
74
|
-
- verify writable local paths and report runtime summary
|
|
75
|
-
- `/multicodex path`
|
|
76
|
-
- show storage and settings file paths
|
|
77
|
-
- `/multicodex reset [manual|quota|all]`
|
|
78
|
-
- reset manual override state, quota cooldown state, or both
|
|
79
|
-
- `/multicodex help`
|
|
80
|
-
- print compact usage text
|
|
35
|
+
| Command | What it does |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `/multicodex` | Open the main interactive menu |
|
|
38
|
+
| `/multicodex show` | Print account status and cached usage |
|
|
39
|
+
| `/multicodex use [identifier]` | Activate an account, or open the picker if no identifier given |
|
|
40
|
+
| `/multicodex footer` | Configure the usage footer display |
|
|
41
|
+
| `/multicodex rotation` | Show the current rotation policy |
|
|
42
|
+
| `/multicodex verify` | Check that local storage paths are writable |
|
|
43
|
+
| `/multicodex path` | Print storage and settings file locations |
|
|
44
|
+
| `/multicodex reset [manual\|quota\|all]` | Clear manual override, quota cooldowns, or both |
|
|
45
|
+
| `/multicodex help` | Print a compact usage line |
|
|
81
46
|
|
|
82
|
-
|
|
47
|
+
All subcommands support dynamic autocomplete. `/multicodex use` also autocompletes from your managed account list.
|
|
83
48
|
|
|
84
|
-
|
|
49
|
+
Commands that do not need a UI panel (`show`, `verify`, `path`, `reset`, `help`) work in non-interactive mode too.
|
|
85
50
|
|
|
86
|
-
|
|
51
|
+
## Account picker
|
|
87
52
|
|
|
88
|
-
|
|
53
|
+
The `/multicodex use` picker lets you select, add, and remove accounts in one place.
|
|
89
54
|
|
|
90
55
|
|
|
91
56
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
## Architecture overview
|
|
97
|
-
|
|
98
|
-
The implementation is currently organized around these modules:
|
|
99
|
-
|
|
100
|
-
- `provider.ts`
|
|
101
|
-
- overrides the normal `openai-codex` provider path
|
|
102
|
-
- mirrors Codex models and installs the managed stream wrapper
|
|
103
|
-
- `stream-wrapper.ts`
|
|
104
|
-
- account selection, retry, and quota-rotation path during streaming
|
|
105
|
-
- `account-manager.ts`
|
|
106
|
-
- managed account storage, token refresh, usage cache, activation logic, and auth import sync
|
|
107
|
-
- `auth.ts`
|
|
108
|
-
- reads pi's `~/.pi/agent/auth.json` and extracts importable `openai-codex` OAuth state
|
|
109
|
-
- `status.ts`
|
|
110
|
-
- footer rendering, footer settings persistence, footer settings panel, and footer status refresh logic
|
|
111
|
-
- `commands.ts`
|
|
112
|
-
- `/multicodex` command-family routing, autocomplete, and account-selection flows
|
|
113
|
-
- `hooks.ts`
|
|
114
|
-
- session-start and session-switch refresh behavior
|
|
115
|
-
- `storage.ts`
|
|
116
|
-
- persisted account state in `~/.pi/agent/codex-accounts.json`
|
|
117
|
-
|
|
118
|
-
## Project direction
|
|
119
|
-
|
|
120
|
-
This project is maintained as its own package and release line.
|
|
121
|
-
|
|
122
|
-
Current direction:
|
|
123
|
-
|
|
124
|
-
- package name: `@victor-software-house/pi-multicodex`
|
|
125
|
-
- Codex-only scope
|
|
126
|
-
- local account state stored at `~/.pi/agent/codex-accounts.json`
|
|
127
|
-
- footer and future extension settings stored under `pi-multicodex` in `~/.pi/agent/settings.json`
|
|
128
|
-
- internal logic split into focused modules today, with a broader shared controller planned next
|
|
129
|
-
- current roadmap tracked in `ROADMAP.md`
|
|
130
|
-
|
|
131
|
-
Current next milestones:
|
|
57
|
+
- **Enter** activates the highlighted account.
|
|
58
|
+
- **Backspace** removes it (after confirmation).
|
|
132
59
|
|
|
133
|
-
|
|
134
|
-
2. Add configurable rotation settings and document the rotation behavior contract.
|
|
135
|
-
3. Broaden the current footer controller into a shared MultiCodex controller.
|
|
136
|
-
4. Improve imported-account labels by deriving email identity safely when possible.
|
|
60
|
+
When you remove an active account, MultiCodex switches to the next available one automatically.
|
|
137
61
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
The current runtime behavior is:
|
|
141
|
-
|
|
142
|
-
### Account selection priority
|
|
143
|
-
|
|
144
|
-
1. Use the manual account selected with `/multicodex use` when it is still available.
|
|
145
|
-
2. Otherwise clear the stale manual override and select the best available managed account.
|
|
146
|
-
3. Best-account selection prefers:
|
|
147
|
-
- untouched accounts with usage data
|
|
148
|
-
- then the account whose weekly reset window ends first
|
|
149
|
-
- then a random available account as fallback
|
|
150
|
-
|
|
151
|
-
### Quota exhaustion semantics
|
|
152
|
-
|
|
153
|
-
- Quota and rate-limit style failures are detected from provider error text.
|
|
154
|
-
- When a request fails before any output is streamed, MultiCodex marks that account exhausted and retries on another account.
|
|
155
|
-
- Exhaustion lasts until the next known reset time.
|
|
156
|
-
- If usage data does not provide a reset time, exhaustion falls back to a 1 hour cooldown.
|
|
157
|
-
|
|
158
|
-
### Retry policy
|
|
159
|
-
|
|
160
|
-
- MultiCodex retries account rotation up to 5 times for a single request.
|
|
161
|
-
- Retries only happen for quota and rate-limit style failures that occur before output is forwarded.
|
|
162
|
-
- Once output has started streaming, the original error is surfaced instead of rotating.
|
|
163
|
-
|
|
164
|
-
### Manual override behavior
|
|
165
|
-
|
|
166
|
-
- `/multicodex use <identifier>` sets the manual account override immediately.
|
|
167
|
-
- `/multicodex use` with no argument opens the account picker and sets the selected manual override.
|
|
168
|
-
- Manual override is session-local state.
|
|
169
|
-
- Manual override clears automatically when the selected account is no longer available or when it hits quota during rotation.
|
|
62
|
+
|
|
170
63
|
|
|
171
|
-
|
|
64
|
+
## Usage footer
|
|
172
65
|
|
|
173
|
-
|
|
174
|
-
- Footer updates render cached usage immediately and refresh in the background when needed.
|
|
175
|
-
- Rapid `model_select` changes debounce background refresh work so non-Codex model switching clears the footer immediately.
|
|
66
|
+
MultiCodex adds a live footer to your session showing the active account, 5-hour and 7-day usage percentages, and reset countdowns. The footer updates after every turn and on account switches.
|
|
176
67
|
|
|
177
|
-
|
|
68
|
+
You can customize which fields appear and their ordering with `/multicodex footer`.
|
|
178
69
|
|
|
179
|
-
|
|
70
|
+
## What it does under the hood
|
|
180
71
|
|
|
181
|
-
-
|
|
182
|
-
-
|
|
183
|
-
-
|
|
184
|
-
-
|
|
185
|
-
-
|
|
186
|
-
- `limit reached`
|
|
72
|
+
- **Provider override.** MultiCodex registers itself as the `openai-codex` provider. You do not need to select a different provider or change your model — it works with whatever Codex model you already use.
|
|
73
|
+
- **Auth import.** When pi has stored Codex OAuth credentials, MultiCodex imports them automatically. You can also add accounts manually with `/multicodex use <email>`.
|
|
74
|
+
- **Token refresh.** OAuth tokens are refreshed before expiry so requests do not fail due to stale credentials.
|
|
75
|
+
- **Usage tracking.** Usage data is fetched from the Codex API and cached for 5 minutes per account. The footer renders cached data immediately and refreshes in the background.
|
|
76
|
+
- **Quota cooldown.** When an account is exhausted, it stays on cooldown until its next known reset time (or 1 hour if the reset time is unknown).
|
|
187
77
|
|
|
188
|
-
##
|
|
78
|
+
## Local development
|
|
189
79
|
|
|
190
|
-
|
|
80
|
+
This repo uses `mise` for tool versions and `pnpm` for dependency management.
|
|
191
81
|
|
|
192
82
|
```bash
|
|
193
|
-
|
|
194
|
-
|
|
83
|
+
mise install # pin tool versions
|
|
84
|
+
pnpm install # install dependencies
|
|
85
|
+
pnpm check # lint + typecheck + test
|
|
86
|
+
npm pack --dry-run # verify package contents
|
|
195
87
|
```
|
|
196
88
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
This repository uses `semantic-release` with npm trusted publishing.
|
|
200
|
-
|
|
201
|
-
Maintainer flow:
|
|
202
|
-
|
|
203
|
-
1. Write Conventional Commits.
|
|
204
|
-
2. The local `commit-msg` hook validates commit messages with Lefthook + commitlint.
|
|
205
|
-
3. CI validates commit messages again and runs release checks.
|
|
206
|
-
4. Merge to `main`.
|
|
207
|
-
5. GitHub Actions runs `semantic-release` from `.github/workflows/publish.yml`.
|
|
208
|
-
6. `semantic-release` computes the next version, creates the git tag and GitHub release, updates `package.json` and `CHANGELOG.md`, and publishes to npm through trusted publishing.
|
|
209
|
-
|
|
210
|
-
Local verification:
|
|
89
|
+
Run the extension directly during development:
|
|
211
90
|
|
|
212
91
|
```bash
|
|
213
|
-
|
|
214
|
-
npm pack --dry-run
|
|
215
|
-
pnpm release:dry
|
|
92
|
+
pi -e ./index.ts
|
|
216
93
|
```
|
|
217
94
|
|
|
218
|
-
|
|
95
|
+
## Data storage
|
|
219
96
|
|
|
220
|
-
|
|
221
|
-
- the `pre-push` mise task runs the same core validations as CI:
|
|
222
|
-
- `pnpm check`
|
|
223
|
-
- `npm pack --dry-run`
|
|
97
|
+
MultiCodex stores all data locally under `~/.pi/agent/`:
|
|
224
98
|
|
|
225
|
-
|
|
99
|
+
| File | Contents |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `codex-accounts.json` | Managed account credentials and state |
|
|
102
|
+
| `settings.json` (key `pi-multicodex`) | Footer display preferences |
|
|
226
103
|
|
|
227
|
-
|
|
104
|
+
No data is sent anywhere except to the Codex API endpoints for auth refresh and usage queries.
|
|
228
105
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
Trusted publisher mapping:
|
|
232
|
-
|
|
233
|
-
- package: `@victor-software-house/pi-multicodex`
|
|
234
|
-
- repository: `victor-founder/pi-multicodex`
|
|
235
|
-
- workflow file: `.github/workflows/publish.yml`
|
|
106
|
+
## Release process
|
|
236
107
|
|
|
237
|
-
|
|
108
|
+
Releases are automated. Push a conventional commit to `main` and GitHub Actions handles versioning, changelog, npm publishing (via trusted publishing), and GitHub releases.
|
|
238
109
|
|
|
239
|
-
|
|
240
|
-
npm trust list @victor-software-house/pi-multicodex
|
|
241
|
-
script -q /dev/null bash -lc 'npm trust github @victor-software-house/pi-multicodex --repository victor-founder/pi-multicodex --file publish.yml --yes'
|
|
242
|
-
```
|
|
110
|
+
Local push protection via `lefthook` runs the same checks as CI before every push.
|
|
243
111
|
|
|
244
|
-
##
|
|
112
|
+
## Roadmap
|
|
245
113
|
|
|
246
|
-
|
|
247
|
-
- `AGENTS.md` for repository-specific agent guidance
|
|
114
|
+
See [ROADMAP.md](ROADMAP.md) for planned work including configurable rotation settings, a shared controller architecture, and immediate footer persistence.
|
|
248
115
|
|
|
249
116
|
## Acknowledgment
|
|
250
117
|
|
|
251
118
|
This project descends from earlier MultiCodex work. Thanks to the original creator for the starting point that made this package possible.
|
|
252
119
|
|
|
253
|
-
The
|
|
120
|
+
The usage footer draws on ideas from [calesennett/pi-codex-usage](https://github.com/calesennett/pi-codex-usage). Thanks to its author for the reference implementation and footer design.
|