@rse/claudex 0.9.13 → 0.9.14
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/.claude/CLAUDE.md +1 -0
- package/AGENTS.md +69 -0
- package/README.md +16 -13
- package/claude +4 -11
- package/claudex +1 -0
- package/claudex.js +728 -569
- package/claudex.ts +782 -596
- package/package.json +3 -2
- package/tmux.conf +8 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@../AGENTS.md
|
package/AGENTS.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
|
|
2
|
+
# AGENTS.md
|
|
3
|
+
|
|
4
|
+
This file provides guidance to AI agents when working with code in this repository.
|
|
5
|
+
|
|
6
|
+
## Project
|
|
7
|
+
|
|
8
|
+
**claudeX** (aka `@rse/claudex`) is an opinionated wrapper around Claude
|
|
9
|
+
Code (the `claude` CLI) for macOS, Linux, and Windows. It bundles
|
|
10
|
+
theming (via `ansi-recolor`), terminal multiplexing (via `tmux`),
|
|
11
|
+
optional sandboxed execution (via `capsula` Docker containers), and
|
|
12
|
+
modal companion tools (LazyGit, Bash) into a single `claudex` command.
|
|
13
|
+
|
|
14
|
+
## Build / Lint
|
|
15
|
+
|
|
16
|
+
The project is written in TypeScript and built via the `stx` task runner (config in `stx.conf`).
|
|
17
|
+
|
|
18
|
+
- `npm start build` — runs the build procedcure: `eslint` + `tsc`.
|
|
19
|
+
- `npm start clean` — remove generated `claudex.js` and `tsc.tsbuildinfo`.
|
|
20
|
+
- `npm start clean-dist` — also remove `node_modules` and `package-lock.json`.
|
|
21
|
+
|
|
22
|
+
There are no tests in this repository.
|
|
23
|
+
|
|
24
|
+
The compiled `claudex.js` is the published entry point (`bin.claudex` in `package.json`); the
|
|
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 ...`.
|
|
28
|
+
|
|
29
|
+
## Architecture
|
|
30
|
+
|
|
31
|
+
The entire program is a single file, `claudex.ts`, dispatched as a `switch (cmd)` in `main()`.
|
|
32
|
+
Subcommands:
|
|
33
|
+
|
|
34
|
+
- `version` — print version from `package.json`.
|
|
35
|
+
- `install` — 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`).
|
|
38
|
+
- `update` — update those same components.
|
|
39
|
+
- `session` — 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` — like `session` but without tmux: just `claudex claude` (optionally inside Capsula).
|
|
44
|
+
- `shell` — 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` — 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` — 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).
|
|
54
|
+
|
|
55
|
+
### Self-invocation
|
|
56
|
+
|
|
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.
|
|
62
|
+
|
|
63
|
+
### Sandbox detection
|
|
64
|
+
|
|
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.
|
|
69
|
+
|
package/README.md
CHANGED
|
@@ -7,15 +7,6 @@ environment for macOS and Linux. It mainly provides a thin `claudex` (claude eXt
|
|
|
7
7
|
wrapper command which provides the following distinct features on top of the regular
|
|
8
8
|
Claude Code command:
|
|
9
9
|
|
|
10
|
-
- **Encapsulated Runtime**: It uses the companion tool
|
|
11
|
-
[capsula](https://github.com/rse/capsula), also from RSE, for
|
|
12
|
-
executing `claude` inside a cleverly established Docker container,
|
|
13
|
-
which mimicks the host environment (filesystem layout, user/group
|
|
14
|
-
name/id, etc) as close as possible.
|
|
15
|
-
|
|
16
|
-
*Rationale*: Prevents any programs `claude` spawns from
|
|
17
|
-
damaging more than the current working directory.
|
|
18
|
-
|
|
19
10
|
- **Adjusted Theme**: It uses the companion tool [ansi-recolor](https://github.com/rse/ansi-recolor),
|
|
20
11
|
also from RSE, to on-the-fly re-color Claude Code's terminal UI
|
|
21
12
|
(configured to run in regular light theme) into the RSE brown/blue
|
|
@@ -34,6 +25,15 @@ Claude Code command:
|
|
|
34
25
|
*Rationale*: Allow one to easily run multiple Claude Code sessions in
|
|
35
26
|
parallel with full terminal interaction.
|
|
36
27
|
|
|
28
|
+
- **Encapsulated Runtime**: It optionally uses the companion tool
|
|
29
|
+
[capsula](https://github.com/rse/capsula), also from RSE, for
|
|
30
|
+
executing `claude` inside a cleverly established Docker container,
|
|
31
|
+
which mimicks the host environment (filesystem layout, user/group
|
|
32
|
+
name/id, etc) as close as possible.
|
|
33
|
+
|
|
34
|
+
*Rationale*: Prevents any programs `claude` spawns from
|
|
35
|
+
damaging more than the current working directory.
|
|
36
|
+
|
|
37
37
|
- **Companion Tools**: It allows you to execute (visually in a modal window on top
|
|
38
38
|
of Claude Code with the help of tmux popups) the companion tools
|
|
39
39
|
[LazyGit](https://github.com/jesseduffield/lazygit) (for Git version
|
|
@@ -50,15 +50,15 @@ The following is a main view of the macOS Terminal with a **claudeX**
|
|
|
50
50
|
session running. Three Claude Code instances are running in separate
|
|
51
51
|
panes of the screen.
|
|
52
52
|
|
|
53
|
-

|
|
53
|
+

|
|
54
54
|
|
|
55
55
|
This is with LazyGit opened in a modal window:
|
|
56
56
|
|
|
57
|
-

|
|
57
|
+

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

|
|
61
|
+

|
|
62
62
|
|
|
63
63
|
Installation
|
|
64
64
|
------------
|
|
@@ -72,7 +72,10 @@ Usage
|
|
|
72
72
|
-----
|
|
73
73
|
|
|
74
74
|
```sh
|
|
75
|
-
$ claudex session
|
|
75
|
+
$ claudex -T # tmux session (formerly: claudex session)
|
|
76
|
+
$ claudex # plain claude (formerly: claudex naked)
|
|
77
|
+
$ claudex -R # claude wrapped with ansi-recolor
|
|
78
|
+
$ claudex -C -T # tmux session inside a Capsula sandbox
|
|
76
79
|
```
|
|
77
80
|
|
|
78
81
|
See Also
|
package/claude
CHANGED
|
@@ -1,15 +1,8 @@
|
|
|
1
1
|
#!/bin/sh
|
|
2
|
+
|
|
2
3
|
if [ ".$CLAUDEX" != . ]; then
|
|
3
4
|
PATH="$CLAUDEX:$PATH"
|
|
4
5
|
fi
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
sandbox="-s"
|
|
9
|
-
fi
|
|
10
|
-
if [ ".$1" = .session ]; then
|
|
11
|
-
shift
|
|
12
|
-
exec claudex $sandbox session ${1+"$@"}
|
|
13
|
-
else
|
|
14
|
-
exec claudex $sandbox naked ${1+"$@"}
|
|
15
|
-
fi
|
|
6
|
+
|
|
7
|
+
exec claudex $capsula ${1+"$@"}
|
|
8
|
+
|