@rse/claudex 0.9.20 → 0.9.21

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/AGENTS.md CHANGED
@@ -15,7 +15,7 @@ modal companion tools (LazyGit, Bash) into a single `claudex` command.
15
15
 
16
16
  The project is written in TypeScript and built via the `stx` task runner (config in `stx.conf`).
17
17
 
18
- - `npm start build` — runs the build procedcure: `eslint` + `tsc`.
18
+ - `npm start build` — runs the build procedure: `eslint` + `tsc`.
19
19
  - `npm start clean` — remove generated `claudex.js` and `tsc.tsbuildinfo`.
20
20
  - `npm start clean-dist` — also remove `node_modules` and `package-lock.json`.
21
21
 
@@ -23,47 +23,96 @@ There are no tests in this repository.
23
23
 
24
24
  The compiled `claudex.js` is the published entry point (`bin.claudex` in `package.json`); the
25
25
  POSIX-sh `claudex` script next to it is a thin launcher that `exec node claudex.js "$@"`.
26
- A second tiny shell script `claude` re-routes `claude session ...` → `claudex session ...` and
27
- everything else → `claudex naked ...`.
26
+ A second tiny shell script `claude` simply `exec claudex "$@"` (prepending `$CLAUDEX_BASEDIR`
27
+ to `$PATH` if set), so users can transparently substitute `claudex` for `claude`.
28
28
 
29
29
  ## Architecture
30
30
 
31
- The entire program is a single file, `claudex.ts`, dispatched as a `switch (cmd)` in `main()`.
32
- Subcommands:
31
+ The entire program is a single file, `claudex.ts`. Dispatch is driven by `commander` in
32
+ `main()`, which defines a small command surface:
33
+
34
+ ### Top-level invocation (default action: run Claude Code)
35
+
36
+ `claudex [-C] [-T [session]] [-R] [-A] [<claude-args>...]` &mdash; the default action runs
37
+ Claude Code, optionally wrapped by Capsula and/or tmux, optionally recolored, optionally
38
+ ASE-augmented. Top-level flags:
39
+
40
+ - `-C, --capsula` &mdash; run inside a per-user/per-session Capsula Docker container
41
+ (`capsula-${USER}-debian-claude-${session}`).
42
+ - `-T, --tmux [session]` &mdash; wrap in a tmux session (auto-detected name, or explicit
43
+ `[session]`). Session name is auto-detected by walking up to find `AGENTS.md` /
44
+ `CLAUDE.md`; otherwise the cwd basename is used.
45
+ - `-R, --recolor` &mdash; pipe Claude Code through `ansi-recolor` using `ansi-recolor.conf`.
46
+ - `-A, --ase` &mdash; enable ASE statusline and auto-derive `ASE_TERM_WIDTH` /
47
+ `ASE_TERM_COLORS` from the TTY for ASE diagram rendering.
48
+
49
+ Top-level `-h/--help` is intercepted before commander, passed through to `claude --help`,
50
+ and then the claudeX extension flags are appended to the help output.
51
+
52
+ In the default action the `claude` invocation:
53
+
54
+ - Prepends `$HOME/.local/bin` to `$PATH` (where `claude` is installed by the official installer).
55
+ - Injects a generated `--settings` JSON (telemetry/auto-update/bug/error-reporting disabled,
56
+ spinner verbs replaced; with `-A` adds an `ase statusline` command; with `-T` enables
57
+ experimental agent teams + `teammateMode: tmux` + `tmuxSplitPanes`).
58
+ - If `CLAUDE_MODEL=ollama:[//host[:port]]/<model>[?context=,capabilities=]` is set, rewrites
59
+ `ANTHROPIC_*` env vars (base URL, auth token "ollama", default Haiku/Opus/Sonnet model,
60
+ capabilities, auto-compact window) to point at a local Ollama server.
61
+
62
+ ### Subcommands
33
63
 
34
- - `version` &mdash; print version from `package.json`.
35
64
  - `install` &mdash; install host-side deps (tmux, lazygit, git, node, ansi-recolor,
36
- typescript-language-server, claude) via the platform's package manager, OR install
37
- the in-container deps (when run inside a Capsula sandbox, detected via `ENVIRONMENT=capsula`).
65
+ typescript-language-server, claude) via the platform's package manager (winget/choco on
66
+ Windows, MacPorts/Homebrew on macOS, apt/apk on Linux), OR the in-container deps when
67
+ `-C` is passed (Debian apt + Node.js + claude installer + the `claude` wrapper into
68
+ `/usr/bin/claude`).
38
69
  - `update` &mdash; update those same components.
39
- - `session` &mdash; main entry point: launch (or reattach to) a tmux session named after the
40
- current project (auto-detected by walking up to find `AGENTS.md` / `CLAUDE.md`), running
41
- `claudex claude` inside it. With `-s`, runs inside a per-user/per-session Capsula Docker
42
- container (`capsula-${USER}-debian-claude-${session}`).
43
- - `naked` &mdash; like `session` but without tmux: just `claudex claude` (optionally inside Capsula).
44
- - `shell` &mdash; spawn `capsula` with the curated env-var allowlist, dotfile mount list,
45
- `-b basedir`, and arbitrary trailing args. Used internally to enter the container.
46
- - `claude` &mdash; the actual `claude` invocation. Wraps `claude` with `ansi-recolor` for theming;
47
- injects `claude-settings.json` via `--settings`; if
48
- `CLAUDE_MODEL=ollama:[//host]/model[?context=,capabilities=]` is set, rewrites
49
- `ANTHROPIC_*` env vars to point at a local Ollama server; auto-derives `ASE_TERM_WIDTH`
50
- / `ASE_TERM_COLORS` from the TTY for ASE diagram rendering.
51
- - `util tmux|bash|lazygit|ase-task-edit` &mdash; helpers invoked from inside tmux. The `tmux`
52
- util applies `tmux.conf` plus runtime `bind-key` definitions for `c`/`|`/`-` (new claude
53
- pane), `g` (lazygit popup), `b` (bash popup), `q` (ASE task-edit popup).
70
+ - `internal <util> [args...]` &mdash; internal sub-dispatch, used by re-entrant
71
+ self-invocation (tmux bind-keys, container `docker exec` strings, etc.). Utilities:
72
+ - `internal tmux <tmux-args>` &mdash; spawn `tmux -f <generated-conf>` using `tmux.conf`
73
+ with `@CLAUDEX@` substituted to `node /path/to/claudex.js` and `@CLAUDEX_FLAGS_PASSTHROUGH@`
74
+ substituted to the propagated pass-through flags. Bind-keys: `c`/`|`/`-` (new claude
75
+ pane), `g` (lazygit popup), `b` (bash/shell popup), `q` (ASE task-edit popup).
76
+ - `internal shell [args...]` &mdash; spawn an interactive login shell
77
+ (`$SHELL -l ...` on POSIX; PowerShell or `$ComSpec` on Windows).
78
+ - `internal ase-task-edit` &mdash; read `#{@ase_task_id}` from the current tmux pane and
79
+ run `ase task edit <tid>`.
80
+ - `internal lazygit [args...]` &mdash; spawn `lazygit -ucf lazygit.yaml`, optionally
81
+ wrapped by `ansi-recolor` when `-R` is in effect.
82
+ - `internal capsula [args...]` &mdash; spawn `capsula -c claude -t debian -P linux/arm64`
83
+ with the curated env-var allowlist (`TERM`, `HOME`, `CLAUDE_MODEL`, `CLAUDEX`),
84
+ dotfile mount list (`.bashrc`, `.gitconfig`, `.ssh/*`, `.vimrc`, `.tmux.conf`,
85
+ `.claude*`, `.dotfiles/*`, etc.), `.env`-file null-mounts (walked up from cwd), and
86
+ `-b basedir`.
54
87
 
55
88
  ### Self-invocation
56
89
 
57
- `claudex` re-invokes itself extensively (e.g. tmux `bind-key` strings, container `docker exec`
58
- strings). For this it uses `selfPath = <basedir>/claudex` (the POSIX-sh launcher) rather than
59
- the `.js` directly, because shell strings need a runnable command. Inside the function `self()`
60
- the `.js` is invoked directly via `node`. Keep this distinction in mind when adding new
61
- self-invocations.
90
+ `claudex` re-invokes itself extensively (tmux `bind-key` strings, container `docker exec`
91
+ strings, sub-action chaining). Self-invocation uses `node claudex.js` directly via
92
+ `selfPathJS = <basedir>/claudex.js` plus `process.execPath`, not the POSIX-sh `claudex`
93
+ launcher &mdash; this avoids a shell layer and keeps argv handling consistent across
94
+ platforms. Inside tmux bind-key strings the same `node /path/to/claudex.js` form is
95
+ substituted into `tmux.conf` via the `@CLAUDEX@` placeholder.
96
+
97
+ ### Flag propagation
98
+
99
+ The pass-through flags `-R` and `-A` are propagated to spawned tmux panes via the
100
+ `CLAUDEX_FLAGS_PASSTHROUGH` env var so new claude panes inherit the user's choice.
101
+ `-C` and `-T` are deliberately NOT propagated (they are consumed at the outer layer to
102
+ avoid recursive container/tmux nesting).
103
+
104
+ The `CLAUDEX_FLAGS` env var lets users set default top-level flags (`-R`/`-C`/`-T`/`-A`);
105
+ they are merged with command-line flags (env first, command-line second; already-present
106
+ flags are not duplicated). This merge is skipped for the `internal` sub-dispatch.
62
107
 
63
108
  ### Sandbox detection
64
109
 
65
- The `-s` flag (consumed before `cmd`) sets `sandbox=true`, which switches `install`/`session`/
66
- `naked` into Capsula mode. Inside the container, `ENVIRONMENT=capsula` is set; commands that
67
- must not run in-container (`install` non-sandbox path, `session`, `naked`, `shell`) check this
68
- and `fatal()` early.
110
+ Inside the Capsula container, `ENVIRONMENT=capsula` is set; commands that must not run
111
+ in-container (`install`/`update` non-capsula path, the default action with `-C` or `-T`,
112
+ and `internal capsula`) check this and `fatal()` early.
113
+
114
+ ### Claude Code version pruning
69
115
 
116
+ After a successful install/update, `pruneClaudeVersions()` removes all but the currently
117
+ active version under `~/.local/share/claude/versions` (active version is detected by
118
+ running the installed `claude --version`).
package/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
  ChangeLog
3
3
  =========
4
4
 
5
+ 0.9.21 (2026-05-09)
6
+ -------------------
7
+
8
+ - IMPROVEMENT: support CLAUDEX\_FLAGS env variable for passing default options
9
+ - IMPROVEMENT: provide convenience keystrokes including CTRL+t for task switching
10
+ - IMPROVEMENT: improve temp file cleanup approach for tmux config
11
+ - BUGFIX: ensure docker container is really running
12
+ - BUGFIX: fix typo in code
13
+ - UPDATE: align AGENTS.md with current code state
14
+ - CLEANUP: internally, use CLAUDEX\_FLAGS\_PASSTHROUGH for the option passing
15
+ - CLEANUP: always use "node claudex.js" internally for self-execution
16
+ - REFACTOR: move pruning of obsolete Claude versions to later in flow
17
+
5
18
  0.9.20 (2026-05-09)
6
19
  -------------------
7
20
 
package/README.md CHANGED
@@ -52,14 +52,10 @@ panes of the screen.
52
52
 
53
53
  ![screenshot](doc/screenshot-1.png)
54
54
 
55
- This is with LazyGit opened in a modal window:
55
+ This is with LazyGit opened on top of Claude Code in a modal window:
56
56
 
57
57
  ![screenshot](doc/screenshot-2.png)
58
58
 
59
- This is with Bash opened in a modal window:
60
-
61
- ![screenshot](doc/screenshot-3.png)
62
-
63
59
  Installation
64
60
  ------------
65
61
 
package/claudex.js CHANGED
@@ -25,10 +25,7 @@ const findBaseDir = () => {
25
25
  return path.dirname(resolved);
26
26
  };
27
27
  const basedir = findBaseDir();
28
- /* the path used for self-invocation: always the POSIX-sh launcher
29
- next to the compiled JS, since the JS itself is not executable
30
- and embedded shell strings (docker/tmux) need a runnable command */
31
- const selfPath = path.join(basedir, "claudex");
28
+ /* the path used for self-invocation */
32
29
  const selfPathJS = path.join(basedir, "claudex.js");
33
30
  /* helper for displaying info messages */
34
31
  const info = (msg) => {
@@ -245,18 +242,18 @@ const actionInstall = async (capsula) => {
245
242
  await self("internal", "capsula", "sudo", "-E", "apt", "install", "-qq", "-y", "binutils", "gcc", "g++", "make");
246
243
  info("install Claude Code");
247
244
  await self("internal", "capsula", "bash", "-c", `PATH="${HOME}/.local/bin:$PATH"; curl -kfsSL https://claude.ai/install.sh | bash`);
248
- /* prune obsolete versions only after successful install */
249
- await self("internal", "capsula", "bash", "-c", "VERSIONS=\"$HOME/.local/share/claude/versions\"; " +
250
- "[ -d \"$VERSIONS\" ] || exit 0; " +
251
- "ACTIVE=$(\"$HOME/.local/bin/claude\" --version 2>/dev/null | awk '{print $1; exit}'); " +
252
- "[ -n \"$ACTIVE\" ] || exit 0; " +
253
- "find \"$VERSIONS\" -mindepth 1 -maxdepth 1 ! -name \"$ACTIVE\" -exec rm -rf {} +");
254
245
  info("install ANSI-Recolor");
255
246
  await self("internal", "capsula", "sudo", "-E", "npm", "install", "-y", "-g", "ansi-recolor");
256
247
  info("install TypeScript LS");
257
248
  await self("internal", "capsula", "sudo", "-E", "npm", "install", "-y", "-g", "typescript-language-server");
258
249
  info("install Claude wrapper");
259
250
  await self("internal", "capsula", "sudo", "install", "-c", "-m", "755", `${basedir}/claude`, "/usr/bin/claude");
251
+ /* prune obsolete versions only after successful install */
252
+ await self("internal", "capsula", "bash", "-c", "VERSIONS=\"$HOME/.local/share/claude/versions\"; " +
253
+ "[ -d \"$VERSIONS\" ] || exit 0; " +
254
+ "ACTIVE=$(\"$HOME/.local/bin/claude\" --version 2>/dev/null | awk '{print $1; exit}'); " +
255
+ "[ -n \"$ACTIVE\" ] || exit 0; " +
256
+ "find \"$VERSIONS\" -mindepth 1 -maxdepth 1 ! -name \"$ACTIVE\" -exec rm -rf {} +");
260
257
  }
261
258
  else {
262
259
  const platform = detectPlatform();
@@ -454,16 +451,29 @@ const actionUpdate = async (capsula) => {
454
451
  /* action: internal "tmux" -- spawn tmux with our generated configuration.
455
452
  The tmux.conf bind-keys for new claude panes embed the parent invocation's
456
453
  pass-through flags (e.g. "-R") so panes inherit the user's choice; flags
457
- are transported via the CLAUDEX_FLAGS env var (set by actionDefault when
458
- entering tmux mode). */
454
+ are transported via the CLAUDEX_FLAGS_PASSTHROUGH env var (set by
455
+ actionDefault when entering tmux mode). */
459
456
  const actionInternalTmux = (args) => {
460
457
  ensureTool("tmux");
461
- const claudexFlags = process.env.CLAUDEX_FLAGS ?? "";
458
+ const claudexFlags = process.env.CLAUDEX_FLAGS_PASSTHROUGH ?? "";
462
459
  const conf = fs.readFileSync(path.join(basedir, "tmux.conf"), "utf8")
463
- .replace(/@SELFPATH@/g, selfPath)
464
- .replace(/@CLAUDEX_FLAGS@/g, claudexFlags);
460
+ .replace(/@CLAUDEX@/g, `${shq(process.execPath)} ${shq(selfPathJS)}`)
461
+ .replace(/@CLAUDEX_FLAGS_PASSTHROUGH@/g, claudexFlags);
465
462
  const confFile = path.join(os.tmpdir(), `claudex-tmux-${process.pid}.conf`);
466
463
  fs.writeFileSync(confFile, conf, { mode: 0o600 });
464
+ /* ensure the temp config is removed on normal exit AND on signal-driven
465
+ termination (SIGINT/SIGTERM); SIGKILL and process panics remain
466
+ uncoverable. tmux.conf is read once at startup and not re-read via
467
+ source-file, so early removal is safe. */
468
+ const cleanup = () => {
469
+ try {
470
+ fs.unlinkSync(confFile);
471
+ }
472
+ catch (_e) { /* ignore */ }
473
+ };
474
+ process.on("exit", cleanup);
475
+ process.on("SIGINT", () => { cleanup(); process.exit(130); });
476
+ process.on("SIGTERM", () => { cleanup(); process.exit(143); });
467
477
  const r = execaSync("tmux", [
468
478
  "-f", confFile,
469
479
  ...args
@@ -472,12 +482,7 @@ const actionInternalTmux = (args) => {
472
482
  reject: false,
473
483
  windowsHide: false
474
484
  });
475
- try {
476
- fs.unlinkSync(confFile);
477
- }
478
- catch (_e) {
479
- /* ignore */
480
- }
485
+ cleanup();
481
486
  return process.exit(r.exitCode ?? 0);
482
487
  };
483
488
  /* action: internal "shell" -- spawn an interactive login shell */
@@ -649,27 +654,30 @@ const actionDefault = (opts, args) => {
649
654
  /* propagate the chosen pass-through flags to "internal tmux" so its
650
655
  tmux.conf bind-keys spawn new claude panes with the same flags */
651
656
  const claudexFlags = innerFlags.join(" ");
652
- process.env.CLAUDEX_FLAGS = claudexFlags;
657
+ process.env.CLAUDEX_FLAGS_PASSTHROUGH = claudexFlags;
653
658
  /* dispatch according to global options */
654
659
  if (opts.capsula) {
655
660
  /* enter/start container, then run tmux inside it */
656
661
  ensureTool("docker");
657
662
  const container = `capsula-${USER}-debian-claude-${session}`;
658
- const inspect = execaSync("docker", ["inspect", container], { reject: false, stdio: "ignore" });
663
+ const inspect = execaSync("docker", ["inspect", "-f", "{{.State.Running}}", container], { reject: false });
659
664
  if (inspect.exitCode === 0) {
665
+ /* start the container if it exists but is not running */
666
+ if (inspect.stdout.trim() !== "true")
667
+ execaSync("docker", ["start", container], { reject: false, stdio: "ignore" });
660
668
  /* enter already running container and run tmux */
661
669
  return execInherit("docker", [
662
670
  "exec", "-i", "-t", container,
663
671
  "bash", "-c",
664
- `TERM=${shq(TERM)} HOME=${shq(HOME)} CLAUDEX_FLAGS=${shq(claudexFlags)} sudo -E -u ${shq(USER)} ${shq(selfPath)} internal tmux new-session -A -s ${shq(session)}`
672
+ `TERM=${shq(TERM)} HOME=${shq(HOME)} CLAUDEX_FLAGS_PASSTHROUGH=${shq(claudexFlags)} sudo -E -u ${shq(USER)} ${shq(process.execPath)} ${shq(selfPathJS)} internal tmux new-session -A -s ${shq(session)}`
665
673
  ]);
666
674
  }
667
675
  else {
668
676
  /* start a new container and run tmux */
669
677
  return execInherit(process.execPath, [
670
678
  selfPathJS, "internal", "capsula",
671
- "-e", `CLAUDEX_FLAGS=${claudexFlags}`,
672
- "-C", container, selfPath, "internal", "tmux",
679
+ "-e", `CLAUDEX_FLAGS_PASSTHROUGH=${claudexFlags}`,
680
+ "-C", container, process.execPath, selfPathJS, "internal", "tmux",
673
681
  "new-session", "-A", "-s", session, "-n", "claude", inPane
674
682
  ]);
675
683
  }
@@ -688,20 +696,23 @@ const actionDefault = (opts, args) => {
688
696
  ensureTool("docker");
689
697
  const session = detectSessionName();
690
698
  const container = `capsula-${USER}-debian-claude-${session}`;
691
- const inspect = execaSync("docker", ["inspect", container], { reject: false, stdio: "ignore" });
699
+ const inspect = execaSync("docker", ["inspect", "-f", "{{.State.Running}}", container], { reject: false });
692
700
  if (inspect.exitCode === 0) {
701
+ /* start the container if it exists but is not running */
702
+ if (inspect.stdout.trim() !== "true")
703
+ execaSync("docker", ["start", container], { reject: false, stdio: "ignore" });
693
704
  /* enter already running container and run claude (single-quote shell-escape) */
694
705
  const passthru = [...innerFlags, ...args].map(shq).join(" ");
695
706
  return execInherit("docker", [
696
707
  "exec", "-i", "-t", container,
697
708
  "bash", "-c",
698
- `TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(selfPath)} ${passthru}`
709
+ `TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(process.execPath)} ${shq(selfPathJS)} ${passthru}`
699
710
  ]);
700
711
  }
701
712
  else {
702
713
  /* start a new container and run claude */
703
714
  return execInherit(process.execPath, [
704
- selfPathJS, "internal", "capsula", "-C", container, selfPath, ...innerFlags, ...args
715
+ selfPathJS, "internal", "capsula", "-C", container, process.execPath, selfPathJS, ...innerFlags, ...args
705
716
  ]);
706
717
  }
707
718
  }
@@ -867,6 +878,38 @@ const actionHelp = () => {
867
878
  };
868
879
  /* the main procedure -- builds and dispatches according to options and commands */
869
880
  const main = async () => {
881
+ /* honor the external CLAUDEX_FLAGS environment variable as a way to set
882
+ the top-level "-R"/"-C"/"-T"/"-A" flags by default. Merge env-derived
883
+ flags with the command-line flags (env first, command-line second, so
884
+ the user can extend or override on the command line). Skip for the
885
+ "internal" sub-dispatch (which uses CLAUDEX_FLAGS_PASSTHROUGH for
886
+ tmux.conf bind-key flag propagation), and skip flags that are already
887
+ present on argv to avoid duplicating boolean options. */
888
+ {
889
+ const topArgs = process.argv.slice(2);
890
+ const subcmd = topArgs.find((a) => !a.startsWith("-")) ?? "";
891
+ const envFlags = (process.env.CLAUDEX_FLAGS ?? "").trim();
892
+ if (envFlags !== "" && subcmd !== "internal") {
893
+ const aliases = {
894
+ "-R": "--recolor", "--recolor": "-R",
895
+ "-C": "--capsula", "--capsula": "-C",
896
+ "-T": "--tmux", "--tmux": "-T",
897
+ "-A": "--ase", "--ase": "-A"
898
+ };
899
+ const present = (tok) => {
900
+ if (topArgs.includes(tok))
901
+ return true;
902
+ const alt = aliases[tok];
903
+ if (alt !== undefined && topArgs.includes(alt))
904
+ return true;
905
+ return false;
906
+ };
907
+ const tokens = envFlags.split(/\s+/).filter((t) => t !== "");
908
+ const toInsert = tokens.filter((t) => !present(t));
909
+ if (toInsert.length > 0)
910
+ process.argv.splice(2, 0, ...toInsert);
911
+ }
912
+ }
870
913
  /* intercept top-level "-h/--help" before commander grabs it, so we can
871
914
  pass-through to "claude --help" and append our extension info */
872
915
  const topArgs = process.argv.slice(2);
@@ -888,7 +931,7 @@ const main = async () => {
888
931
  .helpOption(false)
889
932
  .option("-C, --capsula", "execute Claude Code inside a Capsula sandbox container")
890
933
  .option("-T, --tmux [session]", "wrap Claude Code in a Tmux terminal multiplexing session (optional session name)")
891
- .option("-R, --recolor", "wrap Claude Code with ANSI recoloing for improved theming")
934
+ .option("-R, --recolor", "wrap Claude Code with ANSI recoloring for improved theming")
892
935
  .option("-A, --ase", "enable ASE-specific Claude Code statusline and ASE_* environment variables")
893
936
  .argument("[args...]", "arguments passed unparsed to Claude Code")
894
937
  .action((args, opts) => {
package/claudex.ts CHANGED
@@ -31,10 +31,7 @@ const findBaseDir = (): string => {
31
31
  }
32
32
  const basedir = findBaseDir()
33
33
 
34
- /* the path used for self-invocation: always the POSIX-sh launcher
35
- next to the compiled JS, since the JS itself is not executable
36
- and embedded shell strings (docker/tmux) need a runnable command */
37
- const selfPath = path.join(basedir, "claudex")
34
+ /* the path used for self-invocation */
38
35
  const selfPathJS = path.join(basedir, "claudex.js")
39
36
 
40
37
  /* helper for displaying info messages */
@@ -286,15 +283,6 @@ const actionInstall = async (capsula: boolean): Promise<void> => {
286
283
  info("install Claude Code")
287
284
  await self("internal", "capsula", "bash", "-c", `PATH="${HOME}/.local/bin:$PATH"; curl -kfsSL https://claude.ai/install.sh | bash`)
288
285
 
289
- /* prune obsolete versions only after successful install */
290
- await self("internal", "capsula", "bash", "-c",
291
- "VERSIONS=\"$HOME/.local/share/claude/versions\"; " +
292
- "[ -d \"$VERSIONS\" ] || exit 0; " +
293
- "ACTIVE=$(\"$HOME/.local/bin/claude\" --version 2>/dev/null | awk '{print $1; exit}'); " +
294
- "[ -n \"$ACTIVE\" ] || exit 0; " +
295
- "find \"$VERSIONS\" -mindepth 1 -maxdepth 1 ! -name \"$ACTIVE\" -exec rm -rf {} +"
296
- )
297
-
298
286
  info("install ANSI-Recolor")
299
287
  await self("internal", "capsula", "sudo", "-E", "npm", "install", "-y", "-g", "ansi-recolor")
300
288
 
@@ -303,6 +291,15 @@ const actionInstall = async (capsula: boolean): Promise<void> => {
303
291
 
304
292
  info("install Claude wrapper")
305
293
  await self("internal", "capsula", "sudo", "install", "-c", "-m", "755", `${basedir}/claude`, "/usr/bin/claude")
294
+
295
+ /* prune obsolete versions only after successful install */
296
+ await self("internal", "capsula", "bash", "-c",
297
+ "VERSIONS=\"$HOME/.local/share/claude/versions\"; " +
298
+ "[ -d \"$VERSIONS\" ] || exit 0; " +
299
+ "ACTIVE=$(\"$HOME/.local/bin/claude\" --version 2>/dev/null | awk '{print $1; exit}'); " +
300
+ "[ -n \"$ACTIVE\" ] || exit 0; " +
301
+ "find \"$VERSIONS\" -mindepth 1 -maxdepth 1 ! -name \"$ACTIVE\" -exec rm -rf {} +"
302
+ )
306
303
  }
307
304
  else {
308
305
  const platform = detectPlatform()
@@ -526,16 +523,27 @@ const actionUpdate = async (capsula: boolean): Promise<void> => {
526
523
  /* action: internal "tmux" -- spawn tmux with our generated configuration.
527
524
  The tmux.conf bind-keys for new claude panes embed the parent invocation's
528
525
  pass-through flags (e.g. "-R") so panes inherit the user's choice; flags
529
- are transported via the CLAUDEX_FLAGS env var (set by actionDefault when
530
- entering tmux mode). */
526
+ are transported via the CLAUDEX_FLAGS_PASSTHROUGH env var (set by
527
+ actionDefault when entering tmux mode). */
531
528
  const actionInternalTmux = (args: string[]): never => {
532
529
  ensureTool("tmux")
533
- const claudexFlags = process.env.CLAUDEX_FLAGS ?? ""
530
+ const claudexFlags = process.env.CLAUDEX_FLAGS_PASSTHROUGH ?? ""
534
531
  const conf = fs.readFileSync(path.join(basedir, "tmux.conf"), "utf8")
535
- .replace(/@SELFPATH@/g, selfPath)
536
- .replace(/@CLAUDEX_FLAGS@/g, claudexFlags)
532
+ .replace(/@CLAUDEX@/g, `${shq(process.execPath)} ${shq(selfPathJS)}`)
533
+ .replace(/@CLAUDEX_FLAGS_PASSTHROUGH@/g, claudexFlags)
537
534
  const confFile = path.join(os.tmpdir(), `claudex-tmux-${process.pid}.conf`)
538
535
  fs.writeFileSync(confFile, conf, { mode: 0o600 })
536
+ /* ensure the temp config is removed on normal exit AND on signal-driven
537
+ termination (SIGINT/SIGTERM); SIGKILL and process panics remain
538
+ uncoverable. tmux.conf is read once at startup and not re-read via
539
+ source-file, so early removal is safe. */
540
+ const cleanup = (): void => {
541
+ try { fs.unlinkSync(confFile) }
542
+ catch (_e) { /* ignore */ }
543
+ }
544
+ process.on("exit", cleanup)
545
+ process.on("SIGINT", () => { cleanup(); process.exit(130) })
546
+ process.on("SIGTERM", () => { cleanup(); process.exit(143) })
539
547
  const r = execaSync("tmux", [
540
548
  "-f", confFile,
541
549
  ...args
@@ -544,12 +552,7 @@ const actionInternalTmux = (args: string[]): never => {
544
552
  reject: false,
545
553
  windowsHide: false
546
554
  })
547
- try {
548
- fs.unlinkSync(confFile)
549
- }
550
- catch (_e) {
551
- /* ignore */
552
- }
555
+ cleanup()
553
556
  return process.exit(r.exitCode ?? 0)
554
557
  }
555
558
 
@@ -735,28 +738,32 @@ const actionDefault = (opts: TopOpts, args: string[]): never => {
735
738
  /* propagate the chosen pass-through flags to "internal tmux" so its
736
739
  tmux.conf bind-keys spawn new claude panes with the same flags */
737
740
  const claudexFlags = innerFlags.join(" ")
738
- process.env.CLAUDEX_FLAGS = claudexFlags
741
+ process.env.CLAUDEX_FLAGS_PASSTHROUGH = claudexFlags
739
742
 
740
743
  /* dispatch according to global options */
741
744
  if (opts.capsula) {
742
745
  /* enter/start container, then run tmux inside it */
743
746
  ensureTool("docker")
744
747
  const container = `capsula-${USER}-debian-claude-${session}`
745
- const inspect = execaSync("docker", [ "inspect", container ], { reject: false, stdio: "ignore" })
748
+ const inspect = execaSync("docker", [ "inspect", "-f", "{{.State.Running}}", container ], { reject: false })
746
749
  if (inspect.exitCode === 0) {
750
+ /* start the container if it exists but is not running */
751
+ if (inspect.stdout.trim() !== "true")
752
+ execaSync("docker", [ "start", container ], { reject: false, stdio: "ignore" })
753
+
747
754
  /* enter already running container and run tmux */
748
755
  return execInherit("docker", [
749
756
  "exec", "-i", "-t", container,
750
757
  "bash", "-c",
751
- `TERM=${shq(TERM)} HOME=${shq(HOME)} CLAUDEX_FLAGS=${shq(claudexFlags)} sudo -E -u ${shq(USER)} ${shq(selfPath)} internal tmux new-session -A -s ${shq(session)}`
758
+ `TERM=${shq(TERM)} HOME=${shq(HOME)} CLAUDEX_FLAGS_PASSTHROUGH=${shq(claudexFlags)} sudo -E -u ${shq(USER)} ${shq(process.execPath)} ${shq(selfPathJS)} internal tmux new-session -A -s ${shq(session)}`
752
759
  ])
753
760
  }
754
761
  else {
755
762
  /* start a new container and run tmux */
756
763
  return execInherit(process.execPath, [
757
764
  selfPathJS, "internal", "capsula",
758
- "-e", `CLAUDEX_FLAGS=${claudexFlags}`,
759
- "-C", container, selfPath, "internal", "tmux",
765
+ "-e", `CLAUDEX_FLAGS_PASSTHROUGH=${claudexFlags}`,
766
+ "-C", container, process.execPath, selfPathJS, "internal", "tmux",
760
767
  "new-session", "-A", "-s", session, "-n", "claude", inPane
761
768
  ])
762
769
  }
@@ -776,20 +783,24 @@ const actionDefault = (opts: TopOpts, args: string[]): never => {
776
783
  ensureTool("docker")
777
784
  const session = detectSessionName()
778
785
  const container = `capsula-${USER}-debian-claude-${session}`
779
- const inspect = execaSync("docker", [ "inspect", container ], { reject: false, stdio: "ignore" })
786
+ const inspect = execaSync("docker", [ "inspect", "-f", "{{.State.Running}}", container ], { reject: false })
780
787
  if (inspect.exitCode === 0) {
788
+ /* start the container if it exists but is not running */
789
+ if (inspect.stdout.trim() !== "true")
790
+ execaSync("docker", [ "start", container ], { reject: false, stdio: "ignore" })
791
+
781
792
  /* enter already running container and run claude (single-quote shell-escape) */
782
793
  const passthru = [ ...innerFlags, ...args ].map(shq).join(" ")
783
794
  return execInherit("docker", [
784
795
  "exec", "-i", "-t", container,
785
796
  "bash", "-c",
786
- `TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(selfPath)} ${passthru}`
797
+ `TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(process.execPath)} ${shq(selfPathJS)} ${passthru}`
787
798
  ])
788
799
  }
789
800
  else {
790
801
  /* start a new container and run claude */
791
802
  return execInherit(process.execPath, [
792
- selfPathJS, "internal", "capsula", "-C", container, selfPath, ...innerFlags, ...args
803
+ selfPathJS, "internal", "capsula", "-C", container, process.execPath, selfPathJS, ...innerFlags, ...args
793
804
  ])
794
805
  }
795
806
  }
@@ -963,6 +974,39 @@ const actionHelp = (): never => {
963
974
 
964
975
  /* the main procedure -- builds and dispatches according to options and commands */
965
976
  const main = async (): Promise<void> => {
977
+ /* honor the external CLAUDEX_FLAGS environment variable as a way to set
978
+ the top-level "-R"/"-C"/"-T"/"-A" flags by default. Merge env-derived
979
+ flags with the command-line flags (env first, command-line second, so
980
+ the user can extend or override on the command line). Skip for the
981
+ "internal" sub-dispatch (which uses CLAUDEX_FLAGS_PASSTHROUGH for
982
+ tmux.conf bind-key flag propagation), and skip flags that are already
983
+ present on argv to avoid duplicating boolean options. */
984
+ {
985
+ const topArgs = process.argv.slice(2)
986
+ const subcmd = topArgs.find((a) => !a.startsWith("-")) ?? ""
987
+ const envFlags = (process.env.CLAUDEX_FLAGS ?? "").trim()
988
+ if (envFlags !== "" && subcmd !== "internal") {
989
+ const aliases: Record<string, string> = {
990
+ "-R": "--recolor", "--recolor": "-R",
991
+ "-C": "--capsula", "--capsula": "-C",
992
+ "-T": "--tmux", "--tmux": "-T",
993
+ "-A": "--ase", "--ase": "-A"
994
+ }
995
+ const present = (tok: string): boolean => {
996
+ if (topArgs.includes(tok))
997
+ return true
998
+ const alt = aliases[tok]
999
+ if (alt !== undefined && topArgs.includes(alt))
1000
+ return true
1001
+ return false
1002
+ }
1003
+ const tokens = envFlags.split(/\s+/).filter((t) => t !== "")
1004
+ const toInsert = tokens.filter((t) => !present(t))
1005
+ if (toInsert.length > 0)
1006
+ process.argv.splice(2, 0, ...toInsert)
1007
+ }
1008
+ }
1009
+
966
1010
  /* intercept top-level "-h/--help" before commander grabs it, so we can
967
1011
  pass-through to "claude --help" and append our extension info */
968
1012
  const topArgs = process.argv.slice(2)
@@ -985,7 +1029,7 @@ const main = async (): Promise<void> => {
985
1029
  .helpOption(false)
986
1030
  .option("-C, --capsula", "execute Claude Code inside a Capsula sandbox container")
987
1031
  .option("-T, --tmux [session]", "wrap Claude Code in a Tmux terminal multiplexing session (optional session name)")
988
- .option("-R, --recolor", "wrap Claude Code with ANSI recoloing for improved theming")
1032
+ .option("-R, --recolor", "wrap Claude Code with ANSI recoloring for improved theming")
989
1033
  .option("-A, --ase", "enable ASE-specific Claude Code statusline and ASE_* environment variables")
990
1034
  .argument("[args...]", "arguments passed unparsed to Claude Code")
991
1035
  .action((args: string[], opts: TopOpts) => {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@rse/claudex",
3
3
  "publishConfig": { "access": "public" },
4
- "version": "0.9.20",
4
+ "version": "0.9.21",
5
5
  "description": "Claude Code eXtended",
6
6
  "type": "module",
7
7
  "keywords": [ "claude", "code", "extension", "wrapper" ],
package/tmux.conf CHANGED
@@ -195,11 +195,13 @@ set-option -ga terminal-features ",*:hyperlinks"
195
195
  set-option -as terminal-overrides ",*:RGB"
196
196
  set-option -as terminal-overrides ',*:Tc:sitm=\E[3m:ritm=\E[23m'
197
197
 
198
- # claudeX runtime bind-keys (@SELFPATH@ and @CLAUDEXFLAGS@ are substituted at launch)
199
- bind-key c new-window -c "#{pane_current_path}" -n claude "@SELFPATH@ @CLAUDEX_FLAGS@"
200
- bind-key | split-window -c "#{pane_current_path}" -h "@SELFPATH@ @CLAUDEX_FLAGS@"
201
- bind-key - split-window -c "#{pane_current_path}" -v "@SELFPATH@ @CLAUDEX_FLAGS@"
202
- bind-key g display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Version Control (lazygit) #[noreverse]▶" "@SELFPATH@ @CLAUDEX_FLAGS@ internal lazygit"
203
- bind-key s display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Shell #[noreverse]▶" "@SELFPATH@ @CLAUDEX_FLAGS@ internal shell"
204
- bind-key q display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Task Edit (ase task edit) #[noreverse]▶" "@SELFPATH@ @CLAUDEX_FLAGS@ internal ase-task-edit"
198
+ # claudeX specifics
199
+ bind-key c new-window -c "#{pane_current_path}" -n claude "@CLAUDEX@ @CLAUDEX_FLAGS_PASSTHROUGH@"
200
+ bind-key | split-window -c "#{pane_current_path}" -h "@CLAUDEX@ @CLAUDEX_FLAGS_PASSTHROUGH@"
201
+ bind-key - split-window -c "#{pane_current_path}" -v "@CLAUDEX@ @CLAUDEX_FLAGS_PASSTHROUGH@"
202
+ bind-key g display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Version Control (lazygit) #[noreverse]▶" "@CLAUDEX@ @CLAUDEX_FLAGS_PASSTHROUGH@ internal lazygit"
203
+ bind-key s display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Shell #[noreverse]▶" "@CLAUDEX@ @CLAUDEX_FLAGS_PASSTHROUGH@ internal shell"
204
+ bind-key q display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Task Edit (ase task edit) #[noreverse]▶" "@CLAUDEX@ @CLAUDEX_FLAGS_PASSTHROUGH@ internal ase-task-edit"
205
+ bind-key t send-keys "/ase:ase-meta-task "
206
+ bind-key p send-keys "/ase:ase-meta-persona "
205
207
 
Binary file