@rse/claudex 0.9.19 → 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 +81 -32
- package/CHANGELOG.md +23 -0
- package/README.md +1 -5
- package/claudex.js +80 -32
- package/claudex.ts +84 -35
- package/package.json +1 -1
- package/tmux.conf +9 -7
- package/doc/screenshot-3.png +0 -0
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
|
|
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`
|
|
27
|
-
|
|
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
|
|
32
|
-
|
|
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>...]` — 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` — run inside a per-user/per-session Capsula Docker container
|
|
41
|
+
(`capsula-${USER}-debian-claude-${session}`).
|
|
42
|
+
- `-T, --tmux [session]` — 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` — pipe Claude Code through `ansi-recolor` using `ansi-recolor.conf`.
|
|
46
|
+
- `-A, --ase` — 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` — print version from `package.json`.
|
|
35
64
|
- `install` — install host-side deps (tmux, lazygit, git, node, ansi-recolor,
|
|
36
|
-
typescript-language-server, claude) via the platform's package manager
|
|
37
|
-
|
|
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` — update those same components.
|
|
39
|
-
- `
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
`
|
|
50
|
-
|
|
51
|
-
- `
|
|
52
|
-
|
|
53
|
-
|
|
70
|
+
- `internal <util> [args...]` — internal sub-dispatch, used by re-entrant
|
|
71
|
+
self-invocation (tmux bind-keys, container `docker exec` strings, etc.). Utilities:
|
|
72
|
+
- `internal tmux <tmux-args>` — 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...]` — spawn an interactive login shell
|
|
77
|
+
(`$SHELL -l ...` on POSIX; PowerShell or `$ComSpec` on Windows).
|
|
78
|
+
- `internal ase-task-edit` — read `#{@ase_task_id}` from the current tmux pane and
|
|
79
|
+
run `ase task edit <tid>`.
|
|
80
|
+
- `internal lazygit [args...]` — spawn `lazygit -ucf lazygit.yaml`, optionally
|
|
81
|
+
wrapped by `ansi-recolor` when `-R` is in effect.
|
|
82
|
+
- `internal capsula [args...]` — 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 (
|
|
58
|
-
strings).
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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 — 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
|
-
|
|
66
|
-
`
|
|
67
|
-
|
|
68
|
-
|
|
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,29 @@
|
|
|
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
|
+
|
|
18
|
+
0.9.20 (2026-05-09)
|
|
19
|
+
-------------------
|
|
20
|
+
|
|
21
|
+
- BUGFIX: try to workaround problems again in self-reference under Windows
|
|
22
|
+
|
|
23
|
+
0.9.19 (2026-05-09)
|
|
24
|
+
-------------------
|
|
25
|
+
|
|
26
|
+
- BUGFIX: try to workaround problems again in self-reference under Windows
|
|
27
|
+
|
|
5
28
|
0.9.18 (2026-05-09)
|
|
6
29
|
-------------------
|
|
7
30
|
|
package/README.md
CHANGED
|
@@ -52,14 +52,10 @@ panes of the screen.
|
|
|
52
52
|
|
|
53
53
|

|
|
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
|

|
|
58
58
|
|
|
59
|
-
This is with Bash opened in a modal window:
|
|
60
|
-
|
|
61
|
-

|
|
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
|
|
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
|
|
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.
|
|
458
|
+
const claudexFlags = process.env.CLAUDEX_FLAGS_PASSTHROUGH ?? "";
|
|
462
459
|
const conf = fs.readFileSync(path.join(basedir, "tmux.conf"), "utf8")
|
|
463
|
-
.replace(/@
|
|
464
|
-
.replace(/@
|
|
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
|
-
|
|
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 */
|
|
@@ -639,32 +644,40 @@ const actionDefault = (opts, args) => {
|
|
|
639
644
|
else
|
|
640
645
|
session = detectSessionName();
|
|
641
646
|
const rest = args;
|
|
642
|
-
/* build the in-pane self-invocation shell string
|
|
643
|
-
const inPane = [
|
|
647
|
+
/* build the in-pane self-invocation shell string */
|
|
648
|
+
const inPane = [
|
|
649
|
+
shq(process.execPath),
|
|
650
|
+
shq(selfPathJS),
|
|
651
|
+
...innerFlags.map(shq),
|
|
652
|
+
...rest.map(shq)
|
|
653
|
+
].join(" ");
|
|
644
654
|
/* propagate the chosen pass-through flags to "internal tmux" so its
|
|
645
655
|
tmux.conf bind-keys spawn new claude panes with the same flags */
|
|
646
656
|
const claudexFlags = innerFlags.join(" ");
|
|
647
|
-
process.env.
|
|
657
|
+
process.env.CLAUDEX_FLAGS_PASSTHROUGH = claudexFlags;
|
|
648
658
|
/* dispatch according to global options */
|
|
649
659
|
if (opts.capsula) {
|
|
650
660
|
/* enter/start container, then run tmux inside it */
|
|
651
661
|
ensureTool("docker");
|
|
652
662
|
const container = `capsula-${USER}-debian-claude-${session}`;
|
|
653
|
-
const inspect = execaSync("docker", ["inspect", container], { reject: false
|
|
663
|
+
const inspect = execaSync("docker", ["inspect", "-f", "{{.State.Running}}", container], { reject: false });
|
|
654
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" });
|
|
655
668
|
/* enter already running container and run tmux */
|
|
656
669
|
return execInherit("docker", [
|
|
657
670
|
"exec", "-i", "-t", container,
|
|
658
671
|
"bash", "-c",
|
|
659
|
-
`TERM=${shq(TERM)} HOME=${shq(HOME)}
|
|
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)}`
|
|
660
673
|
]);
|
|
661
674
|
}
|
|
662
675
|
else {
|
|
663
676
|
/* start a new container and run tmux */
|
|
664
677
|
return execInherit(process.execPath, [
|
|
665
678
|
selfPathJS, "internal", "capsula",
|
|
666
|
-
"-e", `
|
|
667
|
-
"-C", container,
|
|
679
|
+
"-e", `CLAUDEX_FLAGS_PASSTHROUGH=${claudexFlags}`,
|
|
680
|
+
"-C", container, process.execPath, selfPathJS, "internal", "tmux",
|
|
668
681
|
"new-session", "-A", "-s", session, "-n", "claude", inPane
|
|
669
682
|
]);
|
|
670
683
|
}
|
|
@@ -683,20 +696,23 @@ const actionDefault = (opts, args) => {
|
|
|
683
696
|
ensureTool("docker");
|
|
684
697
|
const session = detectSessionName();
|
|
685
698
|
const container = `capsula-${USER}-debian-claude-${session}`;
|
|
686
|
-
const inspect = execaSync("docker", ["inspect", container], { reject: false
|
|
699
|
+
const inspect = execaSync("docker", ["inspect", "-f", "{{.State.Running}}", container], { reject: false });
|
|
687
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" });
|
|
688
704
|
/* enter already running container and run claude (single-quote shell-escape) */
|
|
689
705
|
const passthru = [...innerFlags, ...args].map(shq).join(" ");
|
|
690
706
|
return execInherit("docker", [
|
|
691
707
|
"exec", "-i", "-t", container,
|
|
692
708
|
"bash", "-c",
|
|
693
|
-
`TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(
|
|
709
|
+
`TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(process.execPath)} ${shq(selfPathJS)} ${passthru}`
|
|
694
710
|
]);
|
|
695
711
|
}
|
|
696
712
|
else {
|
|
697
713
|
/* start a new container and run claude */
|
|
698
714
|
return execInherit(process.execPath, [
|
|
699
|
-
selfPathJS, "internal", "capsula", "-C", container,
|
|
715
|
+
selfPathJS, "internal", "capsula", "-C", container, process.execPath, selfPathJS, ...innerFlags, ...args
|
|
700
716
|
]);
|
|
701
717
|
}
|
|
702
718
|
}
|
|
@@ -862,6 +878,38 @@ const actionHelp = () => {
|
|
|
862
878
|
};
|
|
863
879
|
/* the main procedure -- builds and dispatches according to options and commands */
|
|
864
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
|
+
}
|
|
865
913
|
/* intercept top-level "-h/--help" before commander grabs it, so we can
|
|
866
914
|
pass-through to "claude --help" and append our extension info */
|
|
867
915
|
const topArgs = process.argv.slice(2);
|
|
@@ -883,7 +931,7 @@ const main = async () => {
|
|
|
883
931
|
.helpOption(false)
|
|
884
932
|
.option("-C, --capsula", "execute Claude Code inside a Capsula sandbox container")
|
|
885
933
|
.option("-T, --tmux [session]", "wrap Claude Code in a Tmux terminal multiplexing session (optional session name)")
|
|
886
|
-
.option("-R, --recolor", "wrap Claude Code with ANSI
|
|
934
|
+
.option("-R, --recolor", "wrap Claude Code with ANSI recoloring for improved theming")
|
|
887
935
|
.option("-A, --ase", "enable ASE-specific Claude Code statusline and ASE_* environment variables")
|
|
888
936
|
.argument("[args...]", "arguments passed unparsed to Claude Code")
|
|
889
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
|
|
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
|
|
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.
|
|
530
|
+
const claudexFlags = process.env.CLAUDEX_FLAGS_PASSTHROUGH ?? ""
|
|
534
531
|
const conf = fs.readFileSync(path.join(basedir, "tmux.conf"), "utf8")
|
|
535
|
-
.replace(/@
|
|
536
|
-
.replace(/@
|
|
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
|
-
|
|
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
|
|
|
@@ -724,34 +727,43 @@ const actionDefault = (opts: TopOpts, args: string[]): never => {
|
|
|
724
727
|
session = detectSessionName()
|
|
725
728
|
const rest = args
|
|
726
729
|
|
|
727
|
-
/* build the in-pane self-invocation shell string
|
|
728
|
-
const inPane = [
|
|
730
|
+
/* build the in-pane self-invocation shell string */
|
|
731
|
+
const inPane = [
|
|
732
|
+
shq(process.execPath),
|
|
733
|
+
shq(selfPathJS),
|
|
734
|
+
...innerFlags.map(shq),
|
|
735
|
+
...rest.map(shq)
|
|
736
|
+
].join(" ")
|
|
729
737
|
|
|
730
738
|
/* propagate the chosen pass-through flags to "internal tmux" so its
|
|
731
739
|
tmux.conf bind-keys spawn new claude panes with the same flags */
|
|
732
740
|
const claudexFlags = innerFlags.join(" ")
|
|
733
|
-
process.env.
|
|
741
|
+
process.env.CLAUDEX_FLAGS_PASSTHROUGH = claudexFlags
|
|
734
742
|
|
|
735
743
|
/* dispatch according to global options */
|
|
736
744
|
if (opts.capsula) {
|
|
737
745
|
/* enter/start container, then run tmux inside it */
|
|
738
746
|
ensureTool("docker")
|
|
739
747
|
const container = `capsula-${USER}-debian-claude-${session}`
|
|
740
|
-
const inspect = execaSync("docker", [ "inspect", container ], { reject: false
|
|
748
|
+
const inspect = execaSync("docker", [ "inspect", "-f", "{{.State.Running}}", container ], { reject: false })
|
|
741
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
|
+
|
|
742
754
|
/* enter already running container and run tmux */
|
|
743
755
|
return execInherit("docker", [
|
|
744
756
|
"exec", "-i", "-t", container,
|
|
745
757
|
"bash", "-c",
|
|
746
|
-
`TERM=${shq(TERM)} HOME=${shq(HOME)}
|
|
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)}`
|
|
747
759
|
])
|
|
748
760
|
}
|
|
749
761
|
else {
|
|
750
762
|
/* start a new container and run tmux */
|
|
751
763
|
return execInherit(process.execPath, [
|
|
752
764
|
selfPathJS, "internal", "capsula",
|
|
753
|
-
"-e", `
|
|
754
|
-
"-C", container,
|
|
765
|
+
"-e", `CLAUDEX_FLAGS_PASSTHROUGH=${claudexFlags}`,
|
|
766
|
+
"-C", container, process.execPath, selfPathJS, "internal", "tmux",
|
|
755
767
|
"new-session", "-A", "-s", session, "-n", "claude", inPane
|
|
756
768
|
])
|
|
757
769
|
}
|
|
@@ -771,20 +783,24 @@ const actionDefault = (opts: TopOpts, args: string[]): never => {
|
|
|
771
783
|
ensureTool("docker")
|
|
772
784
|
const session = detectSessionName()
|
|
773
785
|
const container = `capsula-${USER}-debian-claude-${session}`
|
|
774
|
-
const inspect = execaSync("docker", [ "inspect", container ], { reject: false
|
|
786
|
+
const inspect = execaSync("docker", [ "inspect", "-f", "{{.State.Running}}", container ], { reject: false })
|
|
775
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
|
+
|
|
776
792
|
/* enter already running container and run claude (single-quote shell-escape) */
|
|
777
793
|
const passthru = [ ...innerFlags, ...args ].map(shq).join(" ")
|
|
778
794
|
return execInherit("docker", [
|
|
779
795
|
"exec", "-i", "-t", container,
|
|
780
796
|
"bash", "-c",
|
|
781
|
-
`TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(
|
|
797
|
+
`TERM=${shq(TERM)} HOME=${shq(HOME)} sudo -E -u ${shq(USER)} ${shq(process.execPath)} ${shq(selfPathJS)} ${passthru}`
|
|
782
798
|
])
|
|
783
799
|
}
|
|
784
800
|
else {
|
|
785
801
|
/* start a new container and run claude */
|
|
786
802
|
return execInherit(process.execPath, [
|
|
787
|
-
selfPathJS, "internal", "capsula", "-C", container,
|
|
803
|
+
selfPathJS, "internal", "capsula", "-C", container, process.execPath, selfPathJS, ...innerFlags, ...args
|
|
788
804
|
])
|
|
789
805
|
}
|
|
790
806
|
}
|
|
@@ -958,6 +974,39 @@ const actionHelp = (): never => {
|
|
|
958
974
|
|
|
959
975
|
/* the main procedure -- builds and dispatches according to options and commands */
|
|
960
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
|
+
|
|
961
1010
|
/* intercept top-level "-h/--help" before commander grabs it, so we can
|
|
962
1011
|
pass-through to "claude --help" and append our extension info */
|
|
963
1012
|
const topArgs = process.argv.slice(2)
|
|
@@ -980,7 +1029,7 @@ const main = async (): Promise<void> => {
|
|
|
980
1029
|
.helpOption(false)
|
|
981
1030
|
.option("-C, --capsula", "execute Claude Code inside a Capsula sandbox container")
|
|
982
1031
|
.option("-T, --tmux [session]", "wrap Claude Code in a Tmux terminal multiplexing session (optional session name)")
|
|
983
|
-
.option("-R, --recolor", "wrap Claude Code with ANSI
|
|
1032
|
+
.option("-R, --recolor", "wrap Claude Code with ANSI recoloring for improved theming")
|
|
984
1033
|
.option("-A, --ase", "enable ASE-specific Claude Code statusline and ASE_* environment variables")
|
|
985
1034
|
.argument("[args...]", "arguments passed unparsed to Claude Code")
|
|
986
1035
|
.action((args: string[], opts: TopOpts) => {
|
package/package.json
CHANGED
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
|
|
199
|
-
bind-key c new-window -c "#{pane_current_path}" -n claude "@
|
|
200
|
-
bind-key | split-window -c "#{pane_current_path}" -h "@
|
|
201
|
-
bind-key - split-window -c "#{pane_current_path}" -v "@
|
|
202
|
-
bind-key g display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Version Control (lazygit) #[noreverse]▶" "@
|
|
203
|
-
bind-key s display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Shell #[noreverse]▶" "@
|
|
204
|
-
bind-key q display-popup -E -w 95% -h 95% -T "─◀#[reverse] ⧉ Task Edit (ase task edit) #[noreverse]▶" "@
|
|
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
|
|
package/doc/screenshot-3.png
DELETED
|
Binary file
|