@bramblex/codex-workbench 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,8 @@
 # codex-workbench
 
-A small terminal workbench for browsing and managing local Codex sessions.
+A small terminal workbench for browsing and managing Codex sessions.
 
-It reads Codex session JSONL files, groups sessions by project directory, and lets you inspect, rename, annotate, resume, fork, archive, unarchive, or delete sessions from either a command-line interface or an interactive terminal UI.
+It reads local Codex session JSONL files, can aggregate compatible remote workbenches over SSH, groups sessions by source and project directory, and lets you inspect, rename, annotate, resume, fork, archive, unarchive, or delete sessions from either a command-line interface or an interactive terminal UI.
 
 ## Install
 
@@ -44,13 +44,16 @@ codex-workbench list [--json] [--cwd <dir>] [--all]
 codex-workbench show <session>
 codex-workbench rename <session> <name>
 codex-workbench note <session> <note>
+codex-workbench new [--cwd <dir>] [prompt...]
+codex-workbench dirs [--cwd <dir>] [--json]
+codex-workbench mkdir [--cwd <dir>] <name> [--json]
 codex-workbench resume <session> [prompt...]
 codex-workbench fork <session>
 codex-workbench archive <session>
 codex-workbench unarchive <session>
 codex-workbench hide <session>
 codex-workbench unhide <session>
-codex-workbench delete <session> [--force]
+codex-workbench delete <session> [--force] [--file]
 ```
 
 Run without arguments to open the interactive UI:
@@ -74,6 +77,13 @@ codex-workbench list --cwd /path/to/project
 codex-workbench list --all
 ```
 
+Use `new` to start a fresh Codex session in a project directory:
+
+```sh
+codex-workbench new --cwd /path/to/project
+codex-workbench new --cwd /path/to/project "Summarize this repo"
+```
+
 Use `hide` for sessions that Codex itself can no longer resume, archive, or delete. Hidden sessions are removed from the default list but remain visible with `--all`:
 
 ```sh
@@ -82,6 +92,12 @@ codex-workbench unhide <session>
 codex-workbench list --all
 ```
 
+Use `delete --file` only for broken sessions that Codex can no longer remove. It deletes the local session JSONL file directly:
+
+```sh
+codex-workbench delete <session> --file
+```
+
 Use `doctor` to check which Codex executable the CLI will launch:
 
 ```sh
@@ -92,32 +108,71 @@ Most commands accept a full session id, a unique prefix, a saved name, or a sess
 
 ## Interactive UI
 
-The UI groups sessions by working directory, with sessions above and details below. When you resume a session, Codex temporarily takes over the terminal; when Codex exits, codex-workbench redraws the UI.
+The UI groups sessions by source and working directory, with sources/projects on the left, sessions on the upper right, and details below. When you start or resume a session, Codex temporarily takes over the terminal; when Codex exits, codex-workbench redraws the UI.
 
 Common keys:
 
-- `Enter` or `r`: resume the selected session in Codex
+- `Enter`: resume the selected session in Codex
+- `n`: create a new project/session from Projects, or a new session from Sessions/Details
 - `f`: fork the selected session
 - `v`: print session details and exit
-- `n`: rename the selected session
+- `r`: rename the selected session
 - `o`: add or edit a note
 - `a`: archive the selected session
 - `d`: delete the selected session
-- `Tab`: switch focus between the session list and details pane
-- `Left`/`Right` or `h`/`l`: switch project group
+- `Tab`: switch focus between projects, sessions, and details
+- `Left`/`Right` or `h`/`l`: move between panes
 - `q`, `Esc`, or `Ctrl+C`: quit
 
+In the directory picker, use `Up`/`Down` or `j`/`k` to move, `Left`/`h` for the parent directory, `Right`/`l` for the selected child directory, `n` to create a child directory, and `Enter` to choose the selected directory.
+
+## Remote Servers
+
+codex-workbench can show remote sessions in the interactive UI by calling `cwb` over SSH. The remote server must have `codex-workbench` installed and the configured `cwb` command available to SSH non-interactive commands.
+
+Create `~/.codex/codex-workbench.config.json`:
+
+```json
+{
+  "servers": [
+    {
+      "id": "a",
+      "label": "A server",
+      "target": "user@example.com"
+    },
+    {
+      "id": "b",
+      "label": "B server",
+      "target": "b-host",
+      "command": "/usr/local/bin/cwb",
+      "sshArgs": ["-p", "2222"]
+    }
+  ]
+}
+```
+
+The UI will render `Local`, `A server`, and `B server` as source groups. Remote list, rename, note, hide, directory browsing, new session, resume, fork, archive, and delete commands are executed as SSH calls to the remote `cwb`.
+
+You can verify a remote source directly with:
+
+```sh
+ssh user@example.com 'cwb list --json'
+```
+
 ## Environment
 
 ```sh
 CODEX_HOME            # default: ~/.codex
 CODEX_SESSIONS_DIR    # default: $CODEX_HOME/sessions
 CODEX_WORKBENCH_META  # default: $CODEX_HOME/codex-workbench.json
+CODEX_WORKBENCH_CONFIG # default: $CODEX_HOME/codex-workbench.config.json
 CODEX_BIN             # default: codex from shell PATH
 ```
 
 `CODEX_WORKBENCH_META` stores local workbench metadata such as custom names and notes. Session content remains in the Codex sessions directory.
 
+`CODEX_WORKBENCH_CONFIG` points to the optional local configuration file for SSH remote sources.
+
 By default, codex-workbench launches `codex` through your shell so your normal shell `PATH` applies. Set `CODEX_BIN` if you want to force a specific executable path.
 
 ## Development
@@ -130,8 +185,12 @@ npm pack --dry-run
 Project layout:
 
 ```text
-bin/codex-workbench  # executable entrypoint
-src/cli.js           # main CLI and UI implementation
-src/codex-bin.js     # Codex executable discovery
-test/smoke.js        # smoke tests
+bin/codex-workbench       # executable entrypoint
+src/cli.js                # thin CLI router
+src/cli-output.js         # terminal output presenters
+src/codex-bin.js          # Codex executable discovery
+src/model/                # session parsing, metadata, config, and format helpers
+src/services/             # Codex process runners and session source adapters
+src/ui/                   # interactive UI and components
+test/                     # smoke and service tests
 ```

package/bin/codex-workbench

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 'use strict';
 
-require('../src/cli');
+require('../src/cli').run();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bramblex/codex-workbench",
-  "version": "0.1.2",
-  "description": "Terminal workbench for browsing and managing local Codex sessions.",
+  "version": "0.1.4",
+  "description": "Terminal workbench for browsing and managing local and SSH Codex sessions.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,12 +32,19 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --check src/cli.js && node --check src/codex-bin.js && node test/codex-bin.test.js && node test/smoke.js"
+    "test": "node -e \"const fs=require('fs'),{spawnSync}=require('child_process');function files(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>e.isDirectory()?files(d+'/'+e.name):e.name.endsWith('.js')?[d+'/'+e.name]:[])}for(const f of files('src')){const r=spawnSync(process.execPath,['--check',f],{stdio:'inherit'});if(r.status)process.exit(r.status)}\" && node --check bin/codex-workbench && node --check scripts/pty-codex.js && node --check scripts/tui-pty-codex.js && node --check scripts/blessed-xterm-codex.js && node test/codex-bin.test.js && node test/session-sources.test.js && node test/smoke.js",
+    "pty:codex": "node scripts/pty-codex.js",
+    "tui:codex": "node scripts/tui-pty-codex.js",
+    "xterm:codex": "node scripts/blessed-xterm-codex.js"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
     "blessed": "^0.1.81"
+  },
+  "devDependencies": {
+    "blessed-xterm": "^1.5.1",
+    "node-pty": "^1.2.0-beta.13"
   }
 }

package/src/cli-output.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const path = require('path');
+const { inspectCodexBin } = require('./codex-bin');
+const { localTime, shortId, truncate } = require('./model/format');
+
+function usage() {
+  console.log(`codex-workbench
+
+Usage:
+  codex-workbench [ui]
+  codex-workbench doctor
+  codex-workbench list [--json] [--cwd <dir>] [--all]
+  codex-workbench show <session>
+  codex-workbench rename <session> <name>
+  codex-workbench note <session> <note>
+  codex-workbench new [--cwd <dir>] [prompt...]
+  codex-workbench dirs [--cwd <dir>] [--json]
+  codex-workbench mkdir [--cwd <dir>] <name> [--json]
+  codex-workbench resume <session> [prompt...]
+  codex-workbench fork <session>
+  codex-workbench archive <session>
+  codex-workbench unarchive <session>
+  codex-workbench hide <session>
+  codex-workbench unhide <session>
+  codex-workbench delete <session> [--force] [--file]
+
+Environment:
+  CODEX_HOME            default: ~/.codex
+  CODEX_SESSIONS_DIR    default: $CODEX_HOME/sessions
+  CODEX_WORKBENCH_META  default: $CODEX_HOME/codex-workbench.json
+  CODEX_WORKBENCH_CONFIG default: $CODEX_HOME/codex-workbench.config.json
+  CODEX_BIN             default: codex from shell PATH
+`);
+}
+
+function printList(sessions, opts = {}) {
+  const filtered = sessions.filter((session) => {
+    if (!opts.all && (session.archived || session.hidden)) return false;
+    if (opts.cwd) return path.resolve(session.cwd) === path.resolve(opts.cwd);
+    return true;
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(filtered, null, 2));
+    return;
+  }
+  const groups = new Map();
+  for (const session of filtered) {
+    const source = session.sourceLabel || '';
+    const key = `${source}\0${session.cwd}`;
+    if (!groups.has(key)) groups.set(key, { source, cwd: session.cwd, sessions: [] });
+    groups.get(key).sessions.push(session);
+  }
+  for (const group of groups.values()) {
+    console.log(`\n${group.source ? `${group.source}: ` : ''}${group.cwd}`);
+    for (const session of group.sessions) {
+      const label = session.name || truncate(session.first || session.last || '(no prompt)', 56);
+      const flags = [session.archived ? 'archived' : '', session.hidden ? 'hidden' : '', session.note ? 'note' : ''].filter(Boolean).join(',');
+      console.log(`  ${shortId(session.id)}  ${localTime(session.updatedAt)}  ${String(session.turns).padStart(2)} turns  ${flags ? `[${flags}] ` : ''}${label}`);
+    }
+  }
+  if (!filtered.length) console.log('No sessions found.');
+}
+
+function printShow(session) {
+  console.log(`${session.name || '(unnamed)'} ${session.archived ? '[archived]' : ''}${session.hidden ? '[hidden]' : ''}`);
+  console.log(`id:       ${session.id}`);
+  if (session.sourceLabel) console.log(`source:   ${session.sourceLabel}`);
+  console.log(`cwd:      ${session.cwd}`);
+  console.log(`started:  ${localTime(session.startedAt)}`);
+  console.log(`updated:  ${localTime(session.updatedAt)}`);
+  if (session.file) console.log(`file:     ${session.file}`);
+  console.log(`turns:    ${session.turns}`);
+  if (session.note) console.log(`note:     ${session.note}`);
+  console.log('\nMessages:');
+  for (const msg of session.messages) {
+    if (msg.role === 'developer') continue;
+    const prefix = msg.role === 'assistant' ? 'A' : msg.role === 'user' ? 'U' : msg.role.slice(0, 1).toUpperCase();
+    console.log(`  ${prefix}: ${truncate(msg.text, 180)}`);
+  }
+}
+
+function printDoctor() {
+  const result = inspectCodexBin();
+  console.log('codex-workbench doctor');
+  console.log(`status: ${result.ok ? 'ok' : 'error'}`);
+  if (result.path) console.log(`codex:  ${result.path}`);
+  if (result.source) console.log(`source: ${result.source}`);
+  if (result.error) console.log(`error:  ${result.error}`);
+  console.log('\nChecks:');
+  for (const check of result.checks) {
+    const parts = [
+      check.source,
+      check.mode ? `mode=${check.mode}` : '',
+      check.shell ? `shell=${check.shell}` : '',
+      check.path ? `path=${check.path}` : '',
+      `executable=${check.executable ? 'yes' : 'no'}`,
+    ].filter(Boolean);
+    console.log(`  - ${parts.join(' ')}`);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+module.exports = {
+  printDoctor,
+  printList,
+  printShow,
+  usage,
+};