@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 +81 -32
- package/CHANGELOG.md +13 -0
- package/README.md +1 -5
- package/claudex.js +73 -30
- package/claudex.ts +77 -33
- 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,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
|

|
|
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 */
|
|
@@ -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.
|
|
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
|
|
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)}
|
|
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", `
|
|
672
|
-
"-C", container,
|
|
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
|
|
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(
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
|
@@ -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.
|
|
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
|
|
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)}
|
|
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", `
|
|
759
|
-
"-C", container,
|
|
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
|
|
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(
|
|
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,
|
|
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
|
|
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
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
|