@hellix-ai/cubes 0.2.1 → 0.2.2

package/README.md

@@ -23,8 +23,15 @@ use is never touched), so close the terminal and run `cubes` again to land right
 - **The list** is grouped like the web's Sessions page, with a session's spawned sessions nested under it
   and a coloured dot for its state: working, idle, **needs you**, starting, ended.
 - **Above the session**, a header says which one it is: name · group · runner · state.
-- **Keys:** `⏎` (or a click) opens a session · `Ctrl-]` in a session jumps back to the list · `l` live only
-  · `m` mine only · `/` find · `←` `→` fold a session's children · `q` quits (sessions keep running).
+- **Browsing:** `⏎` (or a click) shows a session on the right and leaves you in the list, so `↑` `↓` and
+  `⏎` again show the next one.
+- **`F1` switches** between the list and the session, from either side. It is the one single key Claude
+  Code does not use (in a session every other key, `Ctrl-]` included, goes to Claude). On a MacBook the
+  top row sends it with `fn` held, unless *Use F1, F2, etc. keys as standard function keys* is on. From
+  the list, `⏎` on the session already showing (or `Tab`) goes in too, and a click on either side moves
+  you there.
+- **Other keys:** `l` live only · `m` mine only · `/` find · `←` `→` fold a session's children · `q` quits
+  (sessions keep running).
 
 ## While attached
 

package/dist/attach.js

@@ -46,7 +46,7 @@ export function wsUrlFor(host, id) {
 }
 export function attach(deps, session, opts = {}) {
     const { api, stdin, stdout, stderr } = deps;
-    const filter = new InputFilter({ pasteImage: !opts.view });
+    const filter = new InputFilter({ pasteImage: !opts.view, detach: opts.detachKey !== false });
     const enc = new TextEncoder();
     return new Promise((resolve) => {
         let ws = null;
@@ -218,10 +218,6 @@ export function attach(deps, session, opts = {}) {
         function onData(chunk) {
             for (const a of filter.feed(chunk)) {
                 if (a.kind === "detach") {
-                    if (opts.onDetachKey) {
-                        opts.onDetachKey();
-                        continue;
-                    }
                     finish(0, "detached", "detached");
                     return;
                 }

package/dist/cli.js

@@ -49,8 +49,9 @@ selecting). Claude Code's own copy, like the c on its login URL, lands there too
 
 If the connection drops, nothing reconnects on its own: you are told why, and r reconnects.
 
-In the split view: ⏎ or a click opens a session, Ctrl-] in a session jumps back to the list, l / m
-show only live / your sessions, / finds, ←→ fold a session's children, q quits (sessions keep running).
+In the split view: ⏎ or a click shows a session on the right and leaves you in the list, so you can
+keep browsing; F1 switches between the list and the session (a second ⏎ goes in too). l / m show
+only live / your sessions, / finds, ←→ fold a session's children, q quits (sessions keep running).
 
 Attaching takes the keyboard from any browser tab on the same session (it becomes read-only) and
 fits the session to this window. --view watches without taking it.
@@ -288,7 +289,7 @@ async function main(argv) {
     }
     // No command at all, in a terminal: the split view. Piped or scripted, still the help.
     if (!a.cmd && !a.flags.has("help") && isTTY())
-        return launchTui({ org: str(a.flags, "org") });
+        return launchTui({ org: str(a.flags, "org"), version: VERSION });
     if (!a.cmd || a.cmd === "help" || a.flags.has("help")) {
         process.stdout.write(HELP);
         return a.cmd || a.flags.has("help") ? 0 : 1;

package/dist/keys.js

@@ -3,8 +3,9 @@
 // Ctrl-C all reach `claude` exactly as they would locally.
 //
 // Two bytes are ours:
-//   • Ctrl-]  (0x1d) DETACH - the telnet/`docker attach` key, chosen because neither Claude Code nor
-//             tmux binds it, so taking it costs the session nothing.
+//   • Ctrl-]  (0x1d) DETACH - the telnet/`docker attach` key. ⚠ Claude Code now binds it too ("open
+//             artifact", 2.1.x), so taking it costs the session that; the split view, which has F1 for
+//             leaving, sends it through (`detach: false`).
 //   • Ctrl-V  (0x16) PASTE AN IMAGE - Claude Code's own image-paste key. Locally it reads the
 //             clipboard of the machine it runs on; here that is a pod with no clipboard, so the CLI
 //             reads YOURS, uploads it, and types the path (what the web terminal does on paste).
@@ -25,10 +26,10 @@ function matchAt(buf, i, seq) {
     return true;
 }
 export class InputFilter {
-    opts;
     inPaste = false;
-    constructor(opts = { pasteImage: true }) {
-        this.opts = opts;
+    opts;
+    constructor(opts = {}) {
+        this.opts = { pasteImage: opts.pasteImage ?? true, detach: opts.detach ?? true };
     }
     feed(chunk) {
         const out = [];
@@ -51,7 +52,7 @@ export class InputFilter {
                 continue;
             }
             const b = chunk[i];
-            if (b === DETACH_BYTE) {
+            if (b === DETACH_BYTE && this.opts.detach) {
                 flush(i);
                 out.push({ kind: "detach" });
                 return out; // whatever was typed after the detach key is not the session's

package/dist/tui/launch.js

@@ -13,8 +13,8 @@ const OPTIONS = [
     ["mouse", "on"],
     ["status", "off"],
     // ⚠ NO PREFIX. tmux's Ctrl-B is Claude Code's "run in background", and the session's own tmux (the
-    // one in the pod) has none either, so nothing here may eat a keystroke. Focus moves by mouse, by
-    // Ctrl-] from the session pane, and by Enter/Tab from the list.
+    // one in the pod) has none either, so nothing here may eat a keystroke Claude Code uses. Focus moves
+    // by mouse, by the SWITCH key below, and by Tab / a second Enter from the list.
     ["prefix", "None"],
     ["prefix2", "None"],
     // Escape must reach Claude Code at once: tmux's default 500 ms makes every Esc feel broken.
@@ -32,13 +32,29 @@ const OPTIONS = [
     ["visual-bell", "off"],
     ["allow-passthrough", "on"],
 ];
+/**
+ * The key that moves focus between the list and the session, from either side. Bound in tmux's root
+ * table so it works whatever the pane is doing (attached, resuming, showing "Disconnected").
+ *
+ * ⚠ It never reaches the session, so it must be a key Claude Code does not use - and it uses every
+ * plain key (Esc interrupts, Tab, Shift-Tab, the arrows, Enter, any character a prompt can hold) and
+ * most Ctrl ones, Ctrl-] included ("open artifact", 2.1.x; checked against its default keybindings).
+ * F1 is the one single key left: Claude Code binds no function key. On a MacBook the top row sends F1
+ * with fn held, unless "Use F1, F2, etc. keys as standard function keys" is on.
+ */
+const SWITCH_KEYS = ["F1"];
+function bindKeys() {
+    // `:.+` is the other pane: there are exactly two.
+    for (const key of SWITCH_KEYS)
+        tmux(["bind-key", "-n", key, "select-pane", "-t", ":.+"]);
+}
 function attachClient() {
     const env = { ...process.env };
     delete env.TMUX; // inside the person's own tmux: nest on purpose rather than refuse
     const r = spawnSync("tmux", ["-L", SOCKET, "attach-session", "-t", SESSION], { stdio: "inherit", env });
     return r.status ?? 0;
 }
-function build(org) {
+function build(org, version) {
     const cols = process.stdout.columns ?? 160;
     const rows = process.stdout.rows ?? 48;
     const env = org ? ["-e", `CUBES_ORG=${org}`] : [];
@@ -49,6 +65,7 @@ function build(org) {
     const left = created.out;
     for (const [k, v] of OPTIONS)
         tmux(["set-option", "-g", "-q", k, v]);
+    bindKeys();
     // ⚠ The same fix the session's own tmux carries (server Tmux.clientDefaults): without `ech`, tmux
     // draws gaps as real spaces. Warp left stale letters in every gap drawn with ECH. A SERVER option,
     // read when a client attaches, so it is set before ours does.
@@ -62,6 +79,7 @@ function build(org) {
         throw new CliError(`could not split the window: ${right.err || right.code}`);
     tmux(["set-option", "-t", SESSION, "@cubes_left", left]);
     tmux(["set-option", "-t", SESSION, "@cubes_right", right.out]);
+    tmux(["set-option", "-t", SESSION, "@cubes_version", version]);
     tmux(["select-pane", "-t", left]);
 }
 /**
@@ -78,6 +96,21 @@ function heal() {
         tmux(["respawn-pane", "-k", "-t", id, selfCommand(id === left ? ["_list"] : ["_pane"])]);
     }
 }
+/**
+ * A layout an older cubes built keeps running that version's list (the tmux outlives an upgrade), so
+ * bring it up to date: settings and keys, and a fresh list. The session pane is left alone - restarting
+ * it would reconnect, and resume a session that has ended - and runs the new code from the next open.
+ */
+function upgradeLayout(version) {
+    for (const [k, v] of OPTIONS)
+        tmux(["set-option", "-g", "-q", k, v]);
+    bindKeys();
+    tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]);
+    const left = tmux(["show-options", "-v", "-q", "-t", SESSION, "@cubes_left"]).out;
+    if (left)
+        tmux(["respawn-pane", "-k", "-t", left, selfCommand(["_list"])]);
+    tmux(["set-option", "-t", SESSION, "@cubes_version", version]);
+}
 export async function launchTui(opts) {
     const v = tmuxVersion();
     if (v === null) {
@@ -90,9 +123,10 @@ export async function launchTui(opts) {
     await currentSession({ org: opts.org }).token();
     if (tmux(["has-session", "-t", SESSION]).code === 0) {
         heal();
-        tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]); // a layout built by an older cubes
+        if (tmux(["show-options", "-v", "-q", "-t", SESSION, "@cubes_version"]).out !== opts.version)
+            upgradeLayout(opts.version);
     }
     else
-        build(opts.org);
+        build(opts.org, opts.version);
     return attachClient();
 }

package/dist/tui/listApp.js

@@ -1,5 +1,9 @@
 // The left pane of the split view: every session, grouped and nested, with its state, filterable,
 // and one keystroke (or click) from being open on the right.
+//
+// Opening SHOWS the session and leaves the keyboard here, so you can keep browsing: Enter on the next
+// one shows that instead. Going into the session is its own step - Tab, F1, or Enter again on the one
+// already showing.
 import { makeApi } from "../api.js";
 import { currentSession } from "../auth.js";
 import { age, listSessions, LIVE } from "../sessions.js";
@@ -12,7 +16,7 @@ const ACCENT = 62;
 /** As many WHOLE key hints as fit, in order of how much they are needed - never one cut in half -
  *  and the way out always last. */
 export function hints(width) {
-    const all = ["⏎ open", "l live", "m mine", "/ find", "^] back here", "←→ fold", "r refresh"];
+    const all = ["⏎ show", "F1 switch", "l live", "m mine", "/ find", "←→ fold", "r refresh"];
     const quit = "q quit";
     let out = "";
     for (const h of all) {
@@ -141,7 +145,17 @@ export async function runList() {
         const next = list[Math.max(0, Math.min(list.length - 1, at + delta))];
         st.selectedId = next.row.id;
     };
+    const goIn = () => {
+        const right = getSessionOption("@cubes_right");
+        if (right)
+            tmux(["select-pane", "-t", right]);
+    };
+    /** Show `id` on the right; the keyboard stays in the list. The one already showing is gone INTO. */
     const open = (id) => {
+        if (id === st.current) {
+            goIn();
+            return;
+        }
         const right = getSessionOption("@cubes_right");
         if (!right) {
             flash("the session pane is gone - run cubes again");
@@ -152,7 +166,6 @@ export async function runList() {
             flash(`could not open it: ${r.err || r.code}`);
             return;
         }
-        tmux(["select-pane", "-t", right]);
         st.current = id;
         setSessionOption("@cubes_current", id);
     };
@@ -209,12 +222,9 @@ export async function runList() {
                     open(st.selectedId);
                 break;
             case "tab":
-            case "ctrl-]": {
-                const right = getSessionOption("@cubes_right");
-                if (right)
-                    tmux(["select-pane", "-t", right]);
+            case "ctrl-]":
+                goIn();
                 break;
-            }
             case "right":
                 if (st.selectedId && !toggleFold(st.selectedId, true)) { /* a leaf: nothing to open */ }
                 break;
@@ -300,7 +310,7 @@ export async function runList() {
         const it = items[st.top + k.y - 2];
         if (!it || it.kind !== "session")
             return;
-        // A click on the fold arrow folds; anywhere else on the row opens it.
+        // A click on the fold arrow folds; anywhere else on the row shows it (and on the one showing, goes in).
         const arrowCol = 1 + strWidth(treePrefix(it)) + 1;
         if (it.children > 0 && k.x === arrowCol) {
             st.selectedId = it.row.id;

package/dist/tui/paneApp.js

@@ -1,8 +1,9 @@
 // The right pane of the split view: the session itself, under a header (tmux's pane border) that says
 // which one it is - name, group, runner, state - and stays current while you work in it.
 //
-// The list replaces this process (`respawn-pane -k`) to open another session, so it only ever holds
-// one. When an attach ends it SAYS so and waits: there is no automatic reconnect, by decision ("never
+// The list replaces this process (`respawn-pane -k`) to show another session, so it only ever holds
+// one - and it does that while the keyboard stays in the list, so this pane must never need focus to
+// get going. When an attach ends it SAYS so and waits: there is no automatic reconnect, by decision ("never
 // keep retrying to reattach a session") - `r` reconnects when the person chooses to.
 import { makeApi } from "../api.js";
 import { attach } from "../attach.js";
@@ -19,7 +20,7 @@ const focusList = () => {
     if (left)
         tmux(["select-pane", "-t", left]);
 };
-/** The header: `● Title · Group · runner · state`, as a tmux format (styles via #[...]). */
+/** The header: `● Title · Group · runner · state · F1 list`, as a tmux format (styles via #[...]). */
 export function headerFor(r, override) {
     const s = override ?? statusOf({ status: r.status ?? "running", activity_status: r.activity_status ?? null });
     const parts = [
@@ -27,6 +28,7 @@ export function headerFor(r, override) {
         fmtText(printable(r.group_name || r.package_name || "no group")),
         fmtText(printable(r.runner_name || "-")),
         `#[fg=colour${s.color}]${s.label}#[default]`,
+        "#[fg=colour240]F1 list#[default]", // the way back, where you look when you want it
     ];
     return parts.join(" #[fg=colour240]·#[default] ");
 }
@@ -125,7 +127,7 @@ async function sessionPane(id) {
                 readClipboardImage: () => readClipboardImage(),
                 clipboard: copyCmd ? { write: (text) => writeClipboard(copyCmd, text) } : null,
             }, row, {
-                onDetachKey: focusList,
+                detachKey: false, // ^] is Claude Code's; F1 (tmux) is the way back to the list
                 onCopied: (text) => {
                     setPaneOption("@cubes_header", `#[fg=colour78]✓ Copied ${[...text].length} characters to your clipboard#[default]`);
                     setTimeout(() => setHeader(row), 1500);
@@ -142,9 +144,10 @@ async function sessionPane(id) {
             { text: words.head, style: ESC.bold + ESC.fg(words.color) },
             { text: result.message, style: ESC.dim },
             { text: "" },
-            { text: `r  ${words.key}     ^]  back to the list` },
+            { text: `r  ${words.key}     F1  back to the list` },
         ]);
-        // Wait for the person: `r` goes round again, ^] / Esc / Tab hand focus back to the list.
+        // Wait for the person: `r` goes round again; Esc / Tab / ^] hand focus back to the list (as does
+        // F1, which tmux takes before it gets here). Nothing is attached now, so no key is Claude's.
         for (;;) {
             const k = await waitKey((k) => (k.kind === "char" && (k.ch === "r" || k.ch === "R")) || k.kind === "enter"
                 || k.kind === "ctrl-]" || k.kind === "escape" || k.kind === "tab");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellix-ai/cubes",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Attach to your Cubes sessions from your own terminal (Warp, iTerm, Ghostty, anything).",
   "type": "module",
   "bin": {