@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.
@@ -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
- ![screenshot](screenshot-1.png)
53
+ ![screenshot](doc/screenshot-1.png)
54
54
 
55
55
  This is with LazyGit opened in a modal window:
56
56
 
57
- ![screenshot](screenshot-2.png)
57
+ ![screenshot](doc/screenshot-2.png)
58
58
 
59
59
  This is with Bash opened in a modal window:
60
60
 
61
- ![screenshot](screenshot-3.png)
61
+ ![screenshot](doc/screenshot-3.png)
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
- sandbox=""
6
- if [ $# -ge 1 ] && [ ".$1" = ".-s" ]; then
7
- shift
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
+
package/claudex CHANGED
@@ -19,5 +19,6 @@ while [ -L "$self" ]; do
19
19
  done
20
20
  basedir=$(cd "$(dirname "$self")" && pwd)
21
21
 
22
+ # pass-through execution
22
23
  exec node "$basedir/claudex.js" "$@"
23
24