@bramblex/codex-workbench 0.1.9 → 0.1.11

package/README.md

@@ -1,140 +1,199 @@
 # codex-workbench
 
-A small terminal workbench for browsing and managing Codex sessions.
+> Terminal workbench for browsing, organizing, and resuming [Codex](https://github.com/openai/codex) sessions — locally and across SSH remotes.
 
-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.
+[![npm version](https://img.shields.io/npm/v/@bramblex/codex-workbench)](https://www.npmjs.com/package/@bramblex/codex-workbench)
+[![license](https://img.shields.io/npm/l/@bramblex/codex-workbench)](LICENSE)
+[![node](https://img.shields.io/node/v/@bramblex/codex-workbench)](package.json)
 
-## Install
+---
 
-```sh
+## What is it?
+
+codex-workbench gives you a fast, keyboard-driven terminal UI over your Codex sessions. It reads session JSONL files from the Codex sessions directory and lets you **inspect, rename, annotate, fork, archive, hide, and delete** sessions without digging through `~/.codex/sessions/` by hand.
+
+It also aggregates sessions from **remote machines over SSH** — so you can manage Codex sessions across all your servers from one terminal.
+
+Run it without arguments to open the interactive TUI, or use the CLI subcommands for scripting and automation.
+
+---
+
+## Features
+
+- **Interactive TUI** — three-pane layout: sources/projects → sessions → details
+- **Remote SSH sources** — browse and manage sessions on distant machines with zero remote dependencies beyond `codex-workbench` itself
+- **Session metadata** — assign custom names and notes, hide stale sessions without deleting them
+- **One-key actions** — resume, fork, archive, or delete sessions from the keyboard
+- **Directory picker** — navigate the filesystem to start new sessions in any project
+- **JSON output** — pipe `list --json` into `jq` or other tools
+- **Short aliases** — installed as both `codex-workbench` and `cwb`
+
+---
+
+## Quick start
+
+```bash
 npm install -g @bramblex/codex-workbench
 ```
 
-codex-workbench expects the Codex CLI to be available from your shell. You can check what executable will be used with:
+Make sure Codex is available in your shell `PATH`. Verify everything is wired up:
 
-```sh
+```bash
 codex-workbench doctor
 ```
 
-For local development:
+Then open the workbench:
 
-```sh
-npm install
+```bash
+codex-workbench
+# or just:
+cwb
 ```
 
-Then run the CLI through Node:
+---
 
-```sh
-node bin/codex-workbench --help
-```
+## CLI commands
 
-To expose the `codex-workbench` command locally:
+### Browse sessions
 
-```sh
-npm link
-codex-workbench list
+```bash
+codex-workbench list                          # human-readable, grouped by source + project
+codex-workbench list --json                   # machine-readable full output
+codex-workbench list --json --compact         # omit message history (faster for scripting)
+codex-workbench list --cwd ~/projects/foo     # filter to one working directory
+codex-workbench list --all                    # include archived and hidden sessions
 ```
 
-## Usage
+### Inspect a session
 
-```sh
-codex-workbench [ui]
-codex-workbench doctor
-codex-workbench list [--json] [--compact] [--cwd <dir>] [--all]
+```bash
 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>
+```
+
+`<session>` can be a full session id, a unique prefix, a saved custom name, or a session filename.
+
+### Manage sessions
+
+```bash
+codex-workbench rename <session> "fix the auth bug"
+codex-workbench note <session> "investigated JWT expiry, seems to be clock skew"
 codex-workbench archive <session>
 codex-workbench unarchive <session>
-codex-workbench hide <session>
+codex-workbench hide <session>         # remove from default list but keep on disk
 codex-workbench unhide <session>
-codex-workbench delete <session> [--force] [--file]
+codex-workbench fork <session>
+codex-workbench delete <session> --force
 ```
 
-Run without arguments to open the interactive UI:
+### Start and resume
 
-```sh
-codex-workbench
+```bash
+codex-workbench new --cwd ~/projects/foo "Summarize this repo"
+codex-workbench resume <session> "what was the conclusion about the rate limiter?"
 ```
 
-The package also installs the short alias:
+When you run `new` or `resume`, Codex takes over the terminal. When it exits, codex-workbench returns.
 
-```sh
-cwb
+### Directories
+
+```bash
+codex-workbench dirs --cwd ~/projects
+codex-workbench dirs --json
+codex-workbench mkdir ~/projects my-new-feature
 ```
 
-Use `list` to find sessions:
+### Diagnostics
 
-```sh
-codex-workbench list
-codex-workbench list --json
-codex-workbench list --json --compact
-codex-workbench list --cwd /path/to/project
-codex-workbench list --all
+```bash
+codex-workbench doctor
 ```
 
-Use `--compact` with `--json` when another tool only needs session summaries. It omits the full message history and keeps remote SSH listings small.
-
-Use `new` to start a fresh Codex session in a project directory:
+### Force-delete a broken session file
 
-```sh
-codex-workbench new --cwd /path/to/project
-codex-workbench new --cwd /path/to/project "Summarize this repo"
+```bash
+codex-workbench delete <session> --file
 ```
 
-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`:
+Only use `--file` when Codex itself cannot remove the session. It deletes the JSONL file directly without going through the Codex CLI.
 
-```sh
-codex-workbench hide <session>
-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:
+## Interactive TUI
+
+Run `cwb` with no arguments to open the TUI:
 
-```sh
-codex-workbench delete <session> --file
+```
+┌─ Codex Workbench ───────────────────────────────────────────────────┐
+│  12/57 visible  Local: ~/projects/api                              │
+├──────────────┬──────────────────────────────────────────────────────┤
+│ > Sources    │ > Sessions                                           │
+│              │                                                      │
+│ 0 All (57)   │ a1b2c3d4e5f6g  23t  2025-03-15 14:22  fix auth bug  │
+│ = host-a (5) │ c8d9e0f1a2b3c  12t  2025-03-14 09:15  refactor db   │
+│   api (3)    │ d4e5f6g7h8i9j   5t  2025-03-13 16:48  add tests      │
+│   web (2)    │ ...                                                  │
+│ = host-b (7) │                                                      │
+│   data (4)   ├──────────────────────────────────────────────────────┤
+│   infra (3)  │ > Details                                            │
+│              │                                                      │
+│              │ fix auth bug                                         │
+│              │ id:       a1b2c3d4e5f6g7...                          │
+│              │ source:   Local                                      │
+│              │ cwd:      ~/projects/api                             │
+│              │ ...                                                  │
+├──────────────┴──────────────────────────────────────────────────────┤
+│ Sessions: ↑/↓ select  Enter resume  r rename  n new  d delete  q quit│
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
-Use `doctor` to check which Codex executable the CLI will launch:
+### Keyboard shortcuts
 
-```sh
-codex-workbench doctor
-```
+| Key | Action |
+|-----|--------|
+| `Enter` | Resume selected session in Codex |
+| `Tab` / `S-Tab` | Switch focus between panes |
+| `←` `→` / `h` `l` | Move between sources, sessions, and details |
+| `↑` `↓` / `j` `k` | Move selection up/down |
+| `0` | Show all sources |
+| `1`–`9` | Jump to source |
+| `[` `]` | Previous / next source |
+| `n` | New session (picks directory from active project) |
+| `f` | Fork selected session |
+| `r` | Rename selected session |
+| `o` | Add or edit note |
+| `a` | Archive selected session |
+| `d` | Delete selected session |
+| `v` | Print session details to stdout and exit |
+| `q` / `Esc` / `Ctrl+C` | Quit |
 
-Most commands accept a full session id, a unique prefix, a saved name, or a session filename.
+### Directory picker
 
-## Interactive UI
+When creating a new session, the directory picker opens:
 
-The UI groups sessions by source and working directory, with sources/projects on the left, sessions on the upper right, and details below. Local sessions render immediately, while remote SSH sources load in the background. When you start or resume a session, Codex temporarily takes over the terminal; when Codex exits, codex-workbench redraws the UI.
+| Key | Action |
+|-----|--------|
+| `↑` `↓` / `j` `k` | Move selection |
+| `←` / `h` | Go to parent directory |
+| `→` / `l` | Enter child directory |
+| `n` | Create a new subdirectory |
+| `Enter` | Choose selected directory |
+| `q` / `Esc` | Cancel |
 
-Common keys:
+---
 
-- `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
-- `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 projects, sessions, and details
-- `Left`/`Right` or `h`/`l`: move between panes
-- `0`: show all sources
-- `1`-`9`: jump to a source
-- `[`/`]`: switch to the previous or next source
-- `q`, `Esc`, or `Ctrl+C`: quit
+## Remote SSH sources
 
-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.
+codex-workbench can show sessions from remote machines by running `cwb` over SSH.
 
-## Remote Servers
+### Requirements
 
-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.
+The remote machine must have `codex-workbench` installed and the `cwb` command available in the **non-interactive SSH PATH** (not just your interactive shell). Test it:
+
+```bash
+ssh user@host 'cwb list --json'
+```
+
+### Configuration
 
 Create `~/.codex/codex-workbench.config.json`:
 
@@ -142,14 +201,14 @@ Create `~/.codex/codex-workbench.config.json`:
 {
   "servers": [
     {
-      "id": "a",
-      "label": "A server",
-      "target": "user@example.com"
+      "id": "devbox",
+      "label": "Dev box",
+      "target": "user@dev.example.com"
     },
     {
-      "id": "b",
-      "label": "B server",
-      "target": "b-host",
+      "id": "gpu",
+      "label": "GPU server",
+      "target": "gpu-host",
       "command": "/usr/local/bin/cwb",
       "sshArgs": ["-p", "2222"]
     }
@@ -157,46 +216,131 @@ Create `~/.codex/codex-workbench.config.json`:
 }
 ```
 
-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`.
+| Field | Required | Description |
+|-------|----------|-------------|
+| `target` | Yes | SSH destination (`user@host` or hostname) |
+| `id` | No | Short identifier (defaults to sanitized target) |
+| `label` | No | Display name in the UI |
+| `command` | No | Path to `cwb` on the remote (default: `cwb`) |
+| `sshArgs` | No | Extra SSH flags, e.g. `["-p", "2222"]` |
+
+Remote sources appear alongside `Local` in the TUI and load asynchronously in the background. Most operations (rename, note, hide, new, resume, fork, archive, delete) are forwarded to the remote `cwb`.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEX_HOME` | `~/.codex` | Codex data directory |
+| `CODEX_SESSIONS_DIR` | `$CODEX_HOME/sessions` | Session JSONL files |
+| `CODEX_WORKBENCH_META` | `$CODEX_HOME/codex-workbench.json` | Workbench metadata (names, notes) |
+| `CODEX_WORKBENCH_CONFIG` | `$CODEX_HOME/codex-workbench.config.json` | SSH remote sources config |
+| `CODEX_BIN` | auto-detected | Force a specific Codex executable |
+
+By default, codex-workbench discovers the `codex` binary through your login shell's `PATH`. Set `CODEX_BIN` to override.
+
+---
+
+## Troubleshooting
 
-You can verify a remote source directly with:
+### "Could not find the codex executable"
 
-```sh
-ssh user@example.com 'cwb list --json'
+Run `codex-workbench doctor` to see where codex-workbench is looking. Common fixes:
+
+- Run `npm install -g @openai/codex` to install Codex globally
+- Set `CODEX_BIN=/path/to/codex` to point directly at the executable
+- Make sure your shell profile (`~/.zshrc`, `~/.bashrc`) adds Codex to `PATH`
+
+### No sessions appear
+
+Make sure you've run Codex at least once. Sessions are stored as `.jsonl` files under `$CODEX_SESSIONS_DIR`. Run `ls ~/.codex/sessions/` to verify.
+
+### Remote source shows an error
+
+Verify the remote is reachable and has `cwb` in its non-interactive PATH:
+
+```bash
+ssh user@host 'cwb list --json --compact'
 ```
 
-## Environment
+If that fails, set the `command` field in your config to the full path:
 
-```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
+```json
+{ "command": "/home/user/.nvm/versions/node/v20/bin/cwb" }
 ```
 
-`CODEX_WORKBENCH_META` stores local workbench metadata such as custom names and notes. Session content remains in the Codex sessions directory.
+### TUI rendering issues
 
-`CODEX_WORKBENCH_CONFIG` points to the optional local configuration file for SSH remote sources.
+codex-workbench uses [blessed](https://github.com/chjj/blessed) for terminal rendering. If you see garbled output, try a different terminal emulator (iTerm2, Kitty, WezTerm, and the built-in macOS Terminal all work well).
 
-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
 
-```sh
+```bash
+git clone https://github.com/bramblex/codex-workbench.git
+cd codex-workbench
+npm install
+```
+
+Run the CLI directly:
+
+```bash
+node bin/codex-workbench --help
+```
+
+Or link it locally:
+
+```bash
+npm link
+cwb list
+```
+
+### Project layout
+
+```
+bin/codex-workbench          # executable entry point
+src/
+  cli.js                     # CLI argument parsing and command dispatch
+  cli-output.js              # terminal output formatters
+  codex-bin.js               # Codex binary discovery (PATH, shell, fallback)
+  config.js                  # environment-derived path constants
+  model/
+    session-store.js         # session JSONL parsing and metadata persistence
+    format.js                # id/time/text formatting helpers
+    directories.js           # filesystem directory listing and creation
+    workbench-config.js      # SSH remote source config loader
+  services/
+    codex-runner.js          # spawn Codex processes (new, resume, fork, etc.)
+    session-sources.js       # aggregates local + remote session lists
+    ssh-runner.js            # runs cwb commands over SSH (sync + async)
+  ui/
+    blessed-compat.js        # blessed terminfo compatibility patch
+    workbench.js             # interactive TUI (blessed-based three-pane layout)
+    directory-picker.js      # TUI filesystem directory picker
+test/
+  smoke.js                   # end-to-end CLI smoke test
+  codex-bin.test.js          # binary discovery unit tests
+  session-sources.test.js    # session source aggregation tests
+  blessed-compat.test.js     # terminfo patch verification
+scripts/
+  pty-codex.js               # PTY-based Codex runner prototype
+  tui-pty-codex.js           # PTY + blessed integration prototype
+  blessed-xterm-codex.js     # xterm + blessed integration prototype
+```
+
+### Tests
+
+```bash
 npm test
-npm pack --dry-run
 ```
 
-Project layout:
+This runs syntax checks on all source files and executes the test suite.
 
-```text
-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
+### Publishing
+
+```bash
+npm pack --dry-run
+npm publish --access public
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bramblex/codex-workbench",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Terminal workbench for browsing and managing local and SSH Codex sessions.",
   "license": "MIT",
   "repository": {

package/src/ui/workbench.js

@@ -629,12 +629,13 @@ async function runWorkbench() {
     updateFocusStyles();
   });
 
-  projectsList.key(['j', 'down'], () => {
+  // blessed handles up/down natively via keys:true; only bind j/k
+  projectsList.key(['j'], () => {
     if (promptOpen()) return;
     selectGroup(groupIndex + 1);
   });
 
-  projectsList.key(['k', 'up'], () => {
+  projectsList.key(['k'], () => {
     if (promptOpen()) return;
     selectGroup(groupIndex - 1);
   });