@jiawang1209/codex-hud 0.1.0

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.
Files changed (56) hide show
  1. package/.codex-plugin/plugin.json +41 -0
  2. package/CHANGELOG.md +9 -0
  3. package/LICENSE +21 -0
  4. package/README.md +342 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +206 -0
  7. package/dist/cli.js.map +1 -0
  8. package/dist/codex-statusline.d.ts +9 -0
  9. package/dist/codex-statusline.js +96 -0
  10. package/dist/codex-statusline.js.map +1 -0
  11. package/dist/config.d.ts +62 -0
  12. package/dist/config.js +199 -0
  13. package/dist/config.js.map +1 -0
  14. package/dist/index.d.ts +2 -0
  15. package/dist/index.js +5 -0
  16. package/dist/index.js.map +1 -0
  17. package/dist/installer.d.ts +17 -0
  18. package/dist/installer.js +125 -0
  19. package/dist/installer.js.map +1 -0
  20. package/dist/native-runner.d.ts +28 -0
  21. package/dist/native-runner.js +122 -0
  22. package/dist/native-runner.js.map +1 -0
  23. package/dist/render.d.ts +11 -0
  24. package/dist/render.js +149 -0
  25. package/dist/render.js.map +1 -0
  26. package/dist/snapshot.d.ts +12 -0
  27. package/dist/snapshot.js +32 -0
  28. package/dist/snapshot.js.map +1 -0
  29. package/dist/sources/codex.d.ts +50 -0
  30. package/dist/sources/codex.js +182 -0
  31. package/dist/sources/codex.js.map +1 -0
  32. package/dist/sources/git.d.ts +2 -0
  33. package/dist/sources/git.js +37 -0
  34. package/dist/sources/git.js.map +1 -0
  35. package/dist/sources/session.d.ts +14 -0
  36. package/dist/sources/session.js +278 -0
  37. package/dist/sources/session.js.map +1 -0
  38. package/dist/tmux-runner.d.ts +26 -0
  39. package/dist/tmux-runner.js +203 -0
  40. package/dist/tmux-runner.js.map +1 -0
  41. package/dist/types.d.ts +42 -0
  42. package/dist/types.js +2 -0
  43. package/dist/types.js.map +1 -0
  44. package/docs/installation.md +42 -0
  45. package/docs/native-codex-cli-patch.md +55 -0
  46. package/docs/plugin-marketplace.md +42 -0
  47. package/docs/release.md +35 -0
  48. package/docs/superpowers/plans/2026-05-23-codex-hud-mvp.md +234 -0
  49. package/docs/superpowers/plans/2026-05-23-productized-native-bundle.md +431 -0
  50. package/docs/superpowers/specs/2026-05-23-codex-hud-design.md +197 -0
  51. package/docs/upstream/codex-command-backed-statusline.md +101 -0
  52. package/package.json +49 -0
  53. package/patches/codex-cli-command-statusline.patch +459 -0
  54. package/plugins/codex-hud/.codex-plugin/plugin.json +41 -0
  55. package/plugins/codex-hud/skills/codex-hud/SKILL.md +153 -0
  56. package/skills/codex-hud/SKILL.md +153 -0
@@ -0,0 +1,41 @@
1
+ {
2
+ "name": "codex-hud",
3
+ "version": "0.1.0",
4
+ "description": "Real-time terminal HUD for Codex CLI sessions: context, tools, todos, git status, and session activity at a glance.",
5
+ "author": {
6
+ "name": "Codex HUD contributors",
7
+ "url": "https://github.com/Jiawang1209/codex-hud"
8
+ },
9
+ "homepage": "https://github.com/Jiawang1209/codex-hud",
10
+ "repository": "https://github.com/Jiawang1209/codex-hud",
11
+ "license": "MIT",
12
+ "keywords": [
13
+ "codex",
14
+ "codex-cli",
15
+ "hud",
16
+ "statusline",
17
+ "terminal",
18
+ "agent-cli"
19
+ ],
20
+ "skills": "./skills/",
21
+ "interface": {
22
+ "displayName": "Codex HUD",
23
+ "shortDescription": "Terminal HUD for Codex CLI sessions",
24
+ "longDescription": "Codex HUD provides a Codex CLI-first terminal telemetry layer for model, reasoning effort, project, git, context, usage, tools, todos, and session signals. The first version ships as a standalone CLI with a Codex plugin wrapper for setup and future native statusline integration.",
25
+ "developerName": "Codex HUD contributors",
26
+ "category": "Engineering",
27
+ "capabilities": [
28
+ "Read"
29
+ ],
30
+ "websiteURL": "https://github.com/Jiawang1209/codex-hud",
31
+ "privacyPolicyURL": "https://github.com/Jiawang1209/codex-hud#privacy",
32
+ "termsOfServiceURL": "https://github.com/Jiawang1209/codex-hud#license",
33
+ "brandColor": "#10A37F",
34
+ "defaultPrompt": [
35
+ "Use Codex HUD to inspect my current Codex CLI environment",
36
+ "Show me how to run codex-hud status",
37
+ "Diagnose my codex-hud setup"
38
+ ],
39
+ "screenshots": []
40
+ }
41
+ }
package/CHANGELOG.md ADDED
@@ -0,0 +1,9 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - Add Codex HUD CLI with `status`, `watch`, `doctor`, `config`, `setup`, `run`, `native`, and shim commands.
6
+ - Add configurable Claude HUD-like colors, expanded multi-line layout, git, context, usage, weekly usage, tools, and todos display.
7
+ - Add `codex-hud install` to prepare the native patched Codex adapter and install a reversible `codex` shim.
8
+ - Bundle the Codex CLI command-backed status-line patch for reproducible native HUD setup.
9
+ - Add Codex plugin marketplace packaging under `plugins/codex-hud`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Codex HUD contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,342 @@
1
+ # Codex HUD
2
+
3
+ Codex HUD is a real-time heads-up display for Codex CLI and Agent CLI workflows, showing context, tools, task progress, git state, and session signals directly in the terminal.
4
+
5
+ The first version ships with two layers:
6
+
7
+ - A Codex native status-line setup command that configures the in-window Codex CLI footer.
8
+ - A standalone `codex-hud status/watch` CLI core with richer session telemetry for development and future command-backed status-line support.
9
+
10
+ Codex HUD reads local Codex configuration, git metadata, and safe session-log metadata. It uses session event types, tool names, token counters, rate-limit counters, and plan status only; it does not need to display private message bodies.
11
+
12
+ ## Install From Source
13
+
14
+ Use this while Codex HUD is not published to npm yet, or when you want to test the latest GitHub version:
15
+
16
+ ```bash
17
+ git clone https://github.com/Jiawang1209/codex-hud.git
18
+ cd codex-hud
19
+ npm install
20
+ npm run build
21
+ npm link
22
+ codex-hud install
23
+ codex
24
+ ```
25
+
26
+ In this flow, `npm install` installs the project's development dependencies and `npm run build` compiles the TypeScript source into `dist/`. `npm link` makes the local `codex-hud` command available globally on your machine.
27
+
28
+ `codex-hud install` prepares the native Codex HUD bundle and installs a reversible `codex` shim, so you can keep launching Codex with the normal `codex` command.
29
+
30
+ ## Install From npm
31
+
32
+ ```bash
33
+ npm install -g @jiawang1209/codex-hud
34
+ codex-hud install
35
+ codex
36
+ ```
37
+
38
+ This is the recommended path after the package is published to npm.
39
+
40
+ ## Development Usage
41
+
42
+ ```bash
43
+ node dist/index.js status
44
+ node dist/index.js run
45
+ node dist/index.js setup
46
+ node dist/index.js doctor
47
+ node dist/index.js config
48
+ node dist/index.js config init
49
+ node dist/index.js watch
50
+ ```
51
+
52
+ When installed as a package, the binary is:
53
+
54
+ ```bash
55
+ codex-hud status
56
+ codex-hud run
57
+ codex-hud install
58
+ codex-hud native
59
+ codex-hud install-shim
60
+ codex-hud uninstall-shim
61
+ codex-hud setup
62
+ codex-hud doctor
63
+ codex-hud config
64
+ codex-hud config init
65
+ codex-hud watch
66
+ ```
67
+
68
+ Example output:
69
+
70
+ ```text
71
+ [gpt-5.5 medium] │ codex-hud git:(main*)
72
+ Context ████░░░░░░ 42% │ Usage ███████░░░ 68% (3h 24m / 5h)
73
+ Todos 2/5 │ Exec active, Plan x2
74
+ ```
75
+
76
+ ## Commands
77
+
78
+ - `status`: print one HUD snapshot.
79
+ - `watch`: refresh the HUD until interrupted.
80
+ - `run`: launch Codex inside a tmux session with a live Codex HUD pane.
81
+ - `pane`: internal command used by `run` to refresh the HUD in a small pane.
82
+ - `install`: prepare the full native bundle: patched Codex checkout, build, and reversible `codex` shim.
83
+ - `native`: launch a patched Codex CLI binary with `codex-hud status` wired into the native footer.
84
+ - `install-shim`: install a reversible `codex` wrapper that launches `codex-hud native`.
85
+ - `uninstall-shim`: remove the `codex` wrapper installed by `install-shim`.
86
+ - `setup`: configure Codex CLI's native in-window `[tui].status_line` with HUD-like items.
87
+ - `install-statusline`: alias for `setup`; accepts `--config <file>` for testing or custom Codex config paths.
88
+ - `doctor`: check Codex CLI, `codex-hud`, shim, patched Codex, native status command, Codex home, and Node.js readiness.
89
+ - `config`: print the effective Codex HUD configuration.
90
+ - `config init`: create `~/.codex-hud/config.json` with default settings.
91
+
92
+ ## Run Codex With A HUD Pane
93
+
94
+ For the closest current approximation of a Claude HUD-like persistent display, use:
95
+
96
+ ```bash
97
+ codex-hud run
98
+ ```
99
+
100
+ The default launcher uses `tmux`. It creates a tmux session with Codex in the main pane and a small live HUD pane underneath.
101
+
102
+ Pass Codex arguments after `--`:
103
+
104
+ ```bash
105
+ codex-hud run -- --model gpt-5.5 --sandbox danger-full-access
106
+ ```
107
+
108
+ Useful wrapper options:
109
+
110
+ ```bash
111
+ codex-hud run --session my-work --height 5
112
+ codex-hud run --dry-run -- --model gpt-5.5
113
+ ```
114
+
115
+ Terminal launcher options:
116
+
117
+ ```bash
118
+ codex-hud run --terminal tmux
119
+ codex-hud run --terminal iterm
120
+ codex-hud run --terminal terminal
121
+ ```
122
+
123
+ Launcher behavior:
124
+
125
+ - `tmux`: portable default, works inside Terminal.app, iTerm2, and most terminal emulators.
126
+ - `iterm`: macOS iTerm2 AppleScript launcher with a native horizontal split pane.
127
+ - `terminal`: macOS Terminal.app AppleScript launcher that opens separate Codex and HUD terminal sessions.
128
+
129
+ `codex-hud run` is intentionally a wrapper, not a Codex fork. It keeps Codex HUD usable today while the project tracks native command-backed status-line support upstream.
130
+
131
+ ## Auto-Launch With `codex`
132
+
133
+ Recommended product install:
134
+
135
+ ```bash
136
+ npm install -g @jiawang1209/codex-hud
137
+ codex-hud install
138
+ codex
139
+ ```
140
+
141
+ `codex-hud install` clones a clean Codex CLI source checkout, applies the bundled native status-line patch, builds the patched Codex binary, and installs the reversible shim below.
142
+
143
+ For the Claude HUD-like experience where users keep typing `codex` and the HUD appears automatically, Codex HUD provides a reversible command shim:
144
+
145
+ ```bash
146
+ codex-hud install-shim --codex /path/to/patched/codex
147
+ ```
148
+
149
+ The shim writes a `codex` wrapper to `~/.local/bin/codex`. If `~/.local/bin` appears before the official Codex binary in `PATH`, then:
150
+
151
+ ```bash
152
+ codex
153
+ ```
154
+
155
+ will transparently run:
156
+
157
+ ```bash
158
+ codex-hud native --codex /path/to/patched/codex -- "$@"
159
+ ```
160
+
161
+ That native launcher starts the patched Codex binary with:
162
+
163
+ ```bash
164
+ -c 'tui.status_line=["command: codex-hud status"]'
165
+ ```
166
+
167
+ For this development machine, the current patched binary is:
168
+
169
+ ```bash
170
+ /Users/liuyue/Desktop/Github_repos/openai-codex/codex-rs/target/debug/codex
171
+ ```
172
+
173
+ Install the local shim with:
174
+
175
+ ```bash
176
+ codex-hud install-shim \
177
+ --codex /Users/liuyue/Desktop/Github_repos/openai-codex/codex-rs/target/debug/codex
178
+ ```
179
+
180
+ Remove it and return to the official `codex` command with:
181
+
182
+ ```bash
183
+ codex-hud uninstall-shim
184
+ ```
185
+
186
+ `install-shim` refuses to overwrite an existing non-Codex-HUD `codex` file in the target bin directory. Use `--bin-dir <dir>` for testing or custom PATH layouts.
187
+
188
+ ## Codex In-Window Status Line
189
+
190
+ Run:
191
+
192
+ ```bash
193
+ codex-hud setup
194
+ ```
195
+
196
+ This writes the closest currently supported Codex CLI native status line to `~/.codex/config.toml`:
197
+
198
+ ```toml
199
+ [tui]
200
+ status_line = [
201
+ "model-with-reasoning",
202
+ "task-progress",
203
+ "current-dir",
204
+ "git-branch",
205
+ "context-used",
206
+ "five-hour-limit",
207
+ "weekly-limit",
208
+ "fast-mode",
209
+ ]
210
+ ```
211
+
212
+ Restart `codex` after running setup. Inside Codex you can also use `/statusline` to inspect or reorder the built-in items.
213
+
214
+ Claude HUD uses Claude Code's command-backed `statusLine` API, where the app invokes a plugin script directly in the prompt footer. Codex CLI 0.131.0 does not currently expose an equivalent command-backed status-line provider; its supported native integration is the fixed `tui.status_line` item list above. Codex HUD keeps the richer CLI renderer in place so it can become the status-line command as soon as Codex exposes that API.
215
+
216
+ The upstream feature request draft lives at:
217
+
218
+ ```text
219
+ docs/upstream/codex-command-backed-statusline.md
220
+ ```
221
+
222
+ There is also a local native Codex CLI proof-of-concept patch that adds
223
+ `tui.status_line = ["command: codex-hud status"]` support and preserves multi-line HUD output in
224
+ the native bottom footer. See:
225
+
226
+ ```text
227
+ docs/native-codex-cli-patch.md
228
+ ```
229
+
230
+ ## Configuration
231
+
232
+ Codex HUD looks for config at:
233
+
234
+ ```text
235
+ ~/.codex-hud/config.json
236
+ ```
237
+
238
+ Supported MVP keys include `layout`, `refreshIntervalMs`, `pathLevels`, `display`, `colors`, and `codexHome`. The default `layout` is `expanded`, which renders a Claude HUD-like multi-line display. Set `layout` to `compact` for a single-line output.
239
+
240
+ The configuration is intentionally close to Claude HUD-style customization. Example:
241
+
242
+ ```json
243
+ {
244
+ "language": "zh",
245
+ "lineLayout": "expanded",
246
+ "pathLevels": 2,
247
+ "elementOrder": ["model", "project", "context", "usage", "weekly", "tools", "todos", "sessionTime"],
248
+ "gitStatus": {
249
+ "enabled": true,
250
+ "showDirty": true,
251
+ "showAheadBehind": true,
252
+ "showFileStats": false
253
+ },
254
+ "display": {
255
+ "showModel": true,
256
+ "showProject": true,
257
+ "showGit": true,
258
+ "showContext": true,
259
+ "showUsage": true,
260
+ "showWeekly": true,
261
+ "showTools": true,
262
+ "showAgents": true,
263
+ "showTodos": true,
264
+ "showConfigCounts": true,
265
+ "showDuration": true,
266
+ "showMemoryUsage": true
267
+ },
268
+ "colors": {
269
+ "context": "yellow",
270
+ "usage": "magenta",
271
+ "weekly": "magenta",
272
+ "warning": "yellow",
273
+ "usageWarning": "magenta",
274
+ "critical": "red",
275
+ "model": "magenta",
276
+ "project": "cyan",
277
+ "git": "magenta",
278
+ "gitBranch": "cyan",
279
+ "label": "dim",
280
+ "custom": "#FF6600"
281
+ }
282
+ }
283
+ ```
284
+
285
+ `elementOrder` controls the order of HUD sections. `colors` accepts named ANSI colors such as `cyan`, `magenta`, `yellow`, `red`, `green`, `dim`, and truecolor hex values like `#FF6600`.
286
+
287
+ Initialize the config file with:
288
+
289
+ ```bash
290
+ codex-hud config init
291
+ ```
292
+
293
+ ## Data Sources
294
+
295
+ - `~/.codex/config.toml` for model and reasoning effort.
296
+ - `~/.codex/sessions/**/*.jsonl` for token counters, rate limits, tool activity, and plan progress. Codex HUD prefers the newest session whose recorded cwd overlaps the current project.
297
+ - `git` for branch and dirty state.
298
+ - `codex --version` for diagnostics.
299
+
300
+ Tool activity is summarized from the most recent tool calls rather than the entire session, so long-running sessions stay readable.
301
+ Context uses the latest token-count frame's `last_token_usage` when available, falling back to cumulative session usage only when needed.
302
+ Progress values render as bars, with terminal colors enabled automatically for TTY output and disabled when `NO_COLOR` is set.
303
+
304
+ ## Plugin Wrapper
305
+
306
+ The repository includes `.codex-plugin/plugin.json` and `skills/codex-hud/SKILL.md`. The plugin wrapper documents how to install Codex HUD, configure the native Codex status line, and use the richer CLI renderer while Codex command-backed status-line support is not yet available.
307
+
308
+ ## Marketplace
309
+
310
+ This repository includes a local marketplace snapshot at:
311
+
312
+ ```text
313
+ .agents/plugins/marketplace.json
314
+ ```
315
+
316
+ For local testing, add the marketplace snapshot from this repository and install `codex-hud` from it with Codex plugin commands.
317
+
318
+ ```bash
319
+ codex plugin marketplace add /path/to/codex-hud
320
+ codex plugin list --marketplace codex-hud-marketplace
321
+ codex plugin add codex-hud@codex-hud-marketplace
322
+ ```
323
+
324
+ The marketplace entry uses the standard Codex plugin layout path `./plugins/codex-hud`.
325
+
326
+ To install the plugin wrapper from GitHub:
327
+
328
+ ```bash
329
+ codex plugin marketplace add Jiawang1209/codex-hud --ref main
330
+ codex plugin list --marketplace codex-hud-marketplace
331
+ codex plugin add codex-hud@codex-hud-marketplace
332
+ ```
333
+
334
+ The Marketplace plugin is the Codex-side wrapper: it exposes Codex HUD guidance and diagnostics inside Codex. The terminal HUD runtime still needs the `codex-hud` CLI command from either `npm install -g @jiawang1209/codex-hud` after npm publish or the source install flow above.
335
+
336
+ ## Privacy
337
+
338
+ Codex HUD reads local Codex configuration, local Codex session metadata, and local git metadata. It does not upload data.
339
+
340
+ ## License
341
+
342
+ MIT
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ export declare const HELP_TEXT = "codex-hud\n\nUsage:\n codex-hud status Print one HUD snapshot\n codex-hud watch Refresh HUD snapshots until interrupted\n codex-hud pane Refresh HUD snapshots for a small tmux pane\n codex-hud run Run Codex with a live HUD pane\n codex-hud install Prepare native Codex HUD integration\n codex-hud native Run patched Codex with codex-hud in the native footer\n codex-hud install-shim [--bin-dir <dir>] [--codex <path>]\n codex-hud uninstall-shim [--bin-dir <dir>]\n codex-hud setup Configure Codex CLI's native in-window status line\n codex-hud doctor Check Codex HUD runtime readiness\n codex-hud config Print effective configuration\n codex-hud config init [--path <file>]\n codex-hud install-statusline [--config <file>]\n\nOptions:\n --terminal <tmux|iterm|terminal>\n Launcher for codex-hud run (default: tmux)\n --height <rows> HUD pane height for tmux mode\n --session <name> tmux session name for tmux mode\n --codex <path> Patched Codex binary for native/shim mode\n --bin-dir <dir> Directory where install-shim writes the codex wrapper\n --codex-source <dir>\n OpenAI Codex checkout used by codex-hud install\n --dry-run Print launcher commands without running them\n -h, --help Show this help\n";
2
+ export declare function runCli(argv?: string[]): Promise<number>;
package/dist/cli.js ADDED
@@ -0,0 +1,206 @@
1
+ import { loadConfig, writeDefaultConfig } from "./config.js";
2
+ import { installCodexStatusLine } from "./codex-statusline.js";
3
+ import { renderHud } from "./render.js";
4
+ import { createHudSnapshot } from "./snapshot.js";
5
+ import { createDoctorReport } from "./sources/codex.js";
6
+ import { parseRunArgs, runCodexHudSession } from "./tmux-runner.js";
7
+ import { installCodexShim, parseNativeArgs, parseShimArgs, removeCodexShim, runNativeCodex, } from "./native-runner.js";
8
+ import { installProduct, parseInstallArgs } from "./installer.js";
9
+ export const HELP_TEXT = `codex-hud
10
+
11
+ Usage:
12
+ codex-hud status Print one HUD snapshot
13
+ codex-hud watch Refresh HUD snapshots until interrupted
14
+ codex-hud pane Refresh HUD snapshots for a small tmux pane
15
+ codex-hud run Run Codex with a live HUD pane
16
+ codex-hud install Prepare native Codex HUD integration
17
+ codex-hud native Run patched Codex with codex-hud in the native footer
18
+ codex-hud install-shim [--bin-dir <dir>] [--codex <path>]
19
+ codex-hud uninstall-shim [--bin-dir <dir>]
20
+ codex-hud setup Configure Codex CLI's native in-window status line
21
+ codex-hud doctor Check Codex HUD runtime readiness
22
+ codex-hud config Print effective configuration
23
+ codex-hud config init [--path <file>]
24
+ codex-hud install-statusline [--config <file>]
25
+
26
+ Options:
27
+ --terminal <tmux|iterm|terminal>
28
+ Launcher for codex-hud run (default: tmux)
29
+ --height <rows> HUD pane height for tmux mode
30
+ --session <name> tmux session name for tmux mode
31
+ --codex <path> Patched Codex binary for native/shim mode
32
+ --bin-dir <dir> Directory where install-shim writes the codex wrapper
33
+ --codex-source <dir>
34
+ OpenAI Codex checkout used by codex-hud install
35
+ --dry-run Print launcher commands without running them
36
+ -h, --help Show this help
37
+ `;
38
+ export async function runCli(argv = process.argv.slice(2)) {
39
+ const command = argv[0] ?? "status";
40
+ if (command === "--help" || command === "-h" || command === "help") {
41
+ process.stdout.write(HELP_TEXT);
42
+ return 0;
43
+ }
44
+ if (command === "status") {
45
+ const config = await loadConfig();
46
+ const snapshot = await createHudSnapshot({ config });
47
+ process.stdout.write(`${renderHud({ config, options: terminalRenderOptions(), snapshot })}\n`);
48
+ return 0;
49
+ }
50
+ if (command === "doctor") {
51
+ const report = await createDoctorReport();
52
+ process.stdout.write(`${report.lines.join("\n")}\n`);
53
+ return report.ok ? 0 : 1;
54
+ }
55
+ if (command === "setup" || command === "install-statusline") {
56
+ return await runInstallStatusLine(argv.slice(1));
57
+ }
58
+ if (command === "config") {
59
+ if (argv[1] === "init") {
60
+ return await runConfigInit(argv.slice(2));
61
+ }
62
+ const config = await loadConfig();
63
+ process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
64
+ return 0;
65
+ }
66
+ if (command === "watch") {
67
+ const config = await loadConfig();
68
+ await runWatch(config);
69
+ return 0;
70
+ }
71
+ if (command === "pane") {
72
+ const config = await loadConfig();
73
+ await runPane(config);
74
+ return 0;
75
+ }
76
+ if (command === "run") {
77
+ return await runCodexHudSession(parseRunArgs(argv.slice(1)));
78
+ }
79
+ if (command === "install") {
80
+ return await installProduct(parseInstallArgs(argv.slice(1)));
81
+ }
82
+ if (command === "native") {
83
+ return await runNativeCodex(parseNativeArgs(argv.slice(1)));
84
+ }
85
+ if (command === "install-shim") {
86
+ return await runInstallShim(argv.slice(1));
87
+ }
88
+ if (command === "uninstall-shim") {
89
+ return await runUninstallShim(argv.slice(1));
90
+ }
91
+ process.stderr.write(`codex-hud: unknown command '${command}'\n`);
92
+ return 1;
93
+ }
94
+ async function runInstallShim(args) {
95
+ try {
96
+ const result = await installCodexShim(parseShimArgs(args));
97
+ const action = result.changed ? "installed" : "already installed";
98
+ process.stdout.write(`codex-hud: codex shim ${action} at ${result.path}\n`);
99
+ process.stdout.write("codex-hud: ensure this directory appears before the official codex binary in PATH.\n");
100
+ return 0;
101
+ }
102
+ catch (error) {
103
+ const message = error instanceof Error ? error.message : "failed to install codex shim";
104
+ process.stderr.write(`codex-hud: ${message}\n`);
105
+ return 1;
106
+ }
107
+ }
108
+ async function runUninstallShim(args) {
109
+ const result = await removeCodexShim(parseShimArgs(args));
110
+ const action = result.removed ? "removed" : "not installed";
111
+ process.stdout.write(`codex-hud: codex shim ${action} at ${result.path}\n`);
112
+ return 0;
113
+ }
114
+ async function runInstallStatusLine(args) {
115
+ const configPath = parseConfigArg(args);
116
+ try {
117
+ const result = await installCodexStatusLine(configPath);
118
+ const action = result.changed ? "configured" : "already configured";
119
+ process.stdout.write(`codex-hud: Codex status line ${action} at ${result.configPath}\n`);
120
+ process.stdout.write(`codex-hud: restart Codex CLI, then use /statusline to inspect or reorder items.\n`);
121
+ return 0;
122
+ }
123
+ catch {
124
+ process.stderr.write("codex-hud: failed to configure Codex status line\n");
125
+ return 1;
126
+ }
127
+ }
128
+ async function runConfigInit(args) {
129
+ const configPath = parsePathArg(args);
130
+ try {
131
+ const writtenPath = await writeDefaultConfig(configPath);
132
+ process.stdout.write(`codex-hud: created ${writtenPath}\n`);
133
+ return 0;
134
+ }
135
+ catch (error) {
136
+ const code = typeof error === "object" && error && "code" in error ? String(error.code) : "";
137
+ if (code === "EEXIST") {
138
+ process.stderr.write(`codex-hud: config already exists${configPath ? ` at ${configPath}` : ""}\n`);
139
+ return 1;
140
+ }
141
+ process.stderr.write(`codex-hud: failed to create config\n`);
142
+ return 1;
143
+ }
144
+ }
145
+ function parsePathArg(args) {
146
+ const index = args.indexOf("--path");
147
+ if (index === -1)
148
+ return undefined;
149
+ return args[index + 1];
150
+ }
151
+ function parseConfigArg(args) {
152
+ const index = args.indexOf("--config");
153
+ if (index === -1)
154
+ return undefined;
155
+ return args[index + 1];
156
+ }
157
+ async function runWatch(config) {
158
+ let stopped = false;
159
+ const stop = () => {
160
+ stopped = true;
161
+ };
162
+ process.once("SIGINT", stop);
163
+ process.once("SIGTERM", stop);
164
+ try {
165
+ while (!stopped) {
166
+ const snapshot = await createHudSnapshot({ config });
167
+ process.stdout.write("\x1Bc");
168
+ process.stdout.write(`${renderHud({ config, options: terminalRenderOptions(), snapshot })}\n`);
169
+ await sleep(config.refreshIntervalMs);
170
+ }
171
+ }
172
+ finally {
173
+ process.off("SIGINT", stop);
174
+ process.off("SIGTERM", stop);
175
+ }
176
+ }
177
+ async function runPane(config) {
178
+ let stopped = false;
179
+ const stop = () => {
180
+ stopped = true;
181
+ };
182
+ process.once("SIGINT", stop);
183
+ process.once("SIGTERM", stop);
184
+ try {
185
+ while (!stopped) {
186
+ const snapshot = await createHudSnapshot({ config });
187
+ process.stdout.write("\x1b[2J\x1b[H");
188
+ process.stdout.write(renderHud({ config, options: terminalRenderOptions(), snapshot }));
189
+ await sleep(config.refreshIntervalMs);
190
+ }
191
+ }
192
+ finally {
193
+ process.off("SIGINT", stop);
194
+ process.off("SIGTERM", stop);
195
+ }
196
+ }
197
+ function sleep(ms) {
198
+ return new Promise((resolve) => setTimeout(resolve, ms));
199
+ }
200
+ function terminalRenderOptions() {
201
+ return {
202
+ color: process.env.CODEX_HUD_FORCE_COLOR === "1" || (process.stdout.isTTY && !process.env.NO_COLOR),
203
+ terminalWidth: process.stdout.columns,
204
+ };
205
+ }
206
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,9 @@
1
+ export declare const CODEX_HUD_STATUS_LINE_ITEMS: readonly ["model-with-reasoning", "task-progress", "current-dir", "git-branch", "context-used", "five-hour-limit", "weekly-limit", "fast-mode"];
2
+ export interface CodexStatusLineInstallResult {
3
+ configPath: string;
4
+ changed: boolean;
5
+ items: readonly string[];
6
+ }
7
+ export declare function resolveCodexConfigPath(explicitPath?: string, homeDir?: string): string;
8
+ export declare function installCodexStatusLine(configPath?: string): Promise<CodexStatusLineInstallResult>;
9
+ export declare function buildCodexStatusLineToml(input: string): string;