@bramblex/codex-workbench 0.1.13 → 0.1.15

package/README.md

@@ -1,6 +1,6 @@
 # codex-workbench
 
-> Terminal workbench for browsing, organizing, and resuming [Codex](https://github.com/openai/codex) sessions — locally and across SSH remotes.
+> A keyboard-driven terminal UI for browsing, organizing, and resuming coding-agent sessions — locally and across SSH remotes.
 
 [![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)
@@ -8,25 +8,19 @@
 
 ---
 
-## What is it?
+![Screenshot of codex-workbench interactive TUI showing local, staging, and production sessions](assets/screenshot.png)
 
-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.
+## What is it?
 
-Run it without arguments to open the interactive TUI, or use the CLI subcommands for scripting and automation.
+codex-workbench is an **interactive terminal UI** for coding-agent sessions. Instead of digging through backend-specific session directories by hand, you get a fast, keyboard-driven interface to **browse, search, rename, annotate, fork, archive, and delete** sessions — all without leaving the terminal.
 
----
+It also connects to **remote machines over SSH**, so you can manage sessions across all your servers from a single pane of glass.
 
-## Features
+Built-in backends currently include [Codex](https://github.com/openai/codex) and pi. The backend layer is intentionally provider-based so additional agents can be added without changing the TUI workflow.
 
-- **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`
+A handful of CLI subcommands are available for scripting, but the TUI is the product.
 
 ---
 
@@ -36,106 +30,35 @@ Run it without arguments to open the interactive TUI, or use the CLI subcommands
 npm install -g @bramblex/codex-workbench
 ```
 
-Make sure Codex is available in your shell `PATH`. Verify everything is wired up:
+Verify your backends are reachable, then open the workbench:
 
 ```bash
 codex-workbench doctor
-```
-
-Then open the workbench:
-
-```bash
-codex-workbench
-# or just:
 cwb
 ```
 
----
-
-## CLI commands
-
-### Browse sessions
-
-```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
-```
-
-### Inspect a session
-
-```bash
-codex-workbench show <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>         # remove from default list but keep on disk
-codex-workbench unhide <session>
-codex-workbench fork <session>
-codex-workbench delete <session> --force
-```
-
-### Start and resume
-
-```bash
-codex-workbench new --cwd ~/projects/foo "Summarize this repo"
-codex-workbench resume <session> "what was the conclusion about the rate limiter?"
-```
-
-When you run `new` or `resume`, Codex takes over the terminal. When it exits, codex-workbench returns.
-
-### Directories
-
-```bash
-codex-workbench dirs --cwd ~/projects
-codex-workbench dirs --json
-codex-workbench mkdir ~/projects my-new-feature
-```
-
-### Diagnostics
-
-```bash
-codex-workbench doctor
-```
-
-### Force-delete a broken session file
-
-```bash
-codex-workbench delete <session> --file
-```
-
-Only use `--file` when Codex itself cannot remove the session. It deletes the JSONL file directly without going through the Codex CLI.
+That's it. `cwb` with no arguments opens the TUI.
 
 ---
 
 ## Interactive TUI
 
-Run `cwb` with no arguments to open the TUI:
+The TUI has three panes: **sources & projects** on the left, **sessions** on the upper right, and **session details** below. Local sessions load instantly; remote SSH sources stream in asynchronously.
 
-![Screenshot of codex-workbench interactive TUI showing local, staging, and production sessions](assets/screenshot.png)
+When you resume or start a session, the selected backend takes over the terminal. When it exits, the workbench redraws.
 
 ### Keyboard shortcuts
 
 | Key | Action |
 |-----|--------|
-| `Enter` | Resume selected session in Codex |
+| `Enter` | Resume selected session in its backend |
 | `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) |
+| `n` | New session (opens directory picker) |
 | `f` | Fork selected session |
 | `r` | Rename selected session |
 | `o` | Add or edit note |
@@ -146,8 +69,6 @@ Run `cwb` with no arguments to open the TUI:
 
 ### Directory picker
 
-When creating a new session, the directory picker opens:
-
 | Key | Action |
 |-----|--------|
 | `↑` `↓` / `j` `k` | Move selection |
@@ -161,11 +82,11 @@ When creating a new session, the directory picker opens:
 
 ## Remote SSH sources
 
-codex-workbench can show sessions from remote machines by running `cwb` over SSH.
+codex-workbench can show sessions from remote machines by running `cwb` over SSH. Remote sources appear alongside `Local` in the TUI and load asynchronously.
 
 ### Requirements
 
-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:
+The remote must have `codex-workbench` installed and `cwb` available in the **non-interactive SSH PATH**. Test it:
 
 ```bash
 ssh user@host 'cwb list --json'
@@ -173,19 +94,19 @@ ssh user@host 'cwb list --json'
 
 ### Configuration
 
-Create `~/.codex/codex-workbench.config.json`:
+Create `~/.cwb/config.json`:
 
 ```json
 {
   "servers": [
     {
       "id": "devbox",
-      "label": "Dev box",
+      "label": "SSH · Dev Box",
       "target": "user@dev.example.com"
     },
     {
       "id": "gpu",
-      "label": "GPU server",
+      "label": "SSH · GPU Server",
       "target": "gpu-host",
       "command": "/usr/local/bin/cwb",
       "sshArgs": ["-p", "2222"]
@@ -197,12 +118,63 @@ Create `~/.codex/codex-workbench.config.json`:
 | Field | Required | Description |
 |-------|----------|-------------|
 | `target` | Yes | SSH destination (`user@host` or hostname) |
+| `label` | No | Display name in the TUI |
 | `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`.
+Operations like rename, note, new, resume, fork, archive, and delete are forwarded to the remote `cwb` transparently.
+
+Remote backends are supported as long as the remote `cwb` can read them.
+
+---
+
+## Backends
+
+codex-workbench auto-detects installed backends by checking their session directories.
+
+| Backend | Sessions | Binary override | Notes |
+|---------|----------|-----------------|-------|
+| `codex` | `$CODEX_SESSIONS_DIR` or `~/.codex/sessions` | `CODEX_BIN` | Uses the Codex CLI for new, resume, fork, archive, unarchive, and delete. |
+| `pi` | `$PI_CODING_AGENT_SESSION_DIR` or `$PI_CODING_AGENT_DIR/sessions` | `PI_BIN` | Uses the pi CLI for new, resume, and fork. Archive/unarchive use workbench metadata; delete removes the session file. |
+
+Session metadata such as custom names, notes, and archive state is stored in workbench's own metadata file, not inside backend session files.
+
+---
+
+## CLI commands
+
+The TUI is the primary interface, but every action is also available as a CLI subcommand for scripting and automation.
+
+```bash
+cwb list                           # human-readable, grouped by source + project
+cwb list --json --compact          # machine-readable, omits message history
+cwb list --cwd ~/projects/foo      # filter to one working directory
+cwb list --all                     # include archived sessions
+cwb backends --json                # list detected local backends
+
+cwb show <session>                 # full session details
+cwb rename <session> "fix auth"    # give a session a memorable name
+cwb note <session> "clock skew"    # attach a persistent note
+cwb archive <session>              # archive without deleting
+cwb unarchive <session>
+cwb fork <session>
+cwb delete <session> --force
+
+cwb new --cwd ~/projects/foo --backend codex "Summarize this repo"
+cwb new --cwd ~/projects/foo --backend pi "Summarize this repo"
+cwb resume <session> "what was the conclusion about the rate limiter?"
+
+cwb dirs --cwd ~/projects
+cwb mkdir ~/projects my-new-feature
+
+cwb doctor                         # check available backends and binaries
+cwb delete <session> --file        # force-delete broken session file
+```
+
+`<session>` can be a full session id, a unique prefix, a saved custom name, or a session filename.
+
+When you run `new` or `resume`, the selected backend takes over the terminal. When it exits, codex-workbench returns. In the TUI, `n` scans the current source for available backends; local sources are scanned directly and remote sources are scanned with `cwb backends --json` over SSH.
 
 ---
 
@@ -210,14 +182,24 @@ Remote sources appear alongside `Local` in the TUI and load asynchronously in th
 
 | Variable | Default | Description |
 |----------|---------|-------------|
+| `CWB_HOME` | `~/.cwb` | codex-workbench data directory |
+| `CWB_META` | `$CWB_HOME/metadata.json` | Workbench metadata (names, notes, archive state) |
+| `CWB_CONFIG` | `$CWB_HOME/config.json` | SSH remote sources config |
 | `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 |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi coding agent data directory |
+| `PI_CODING_AGENT_SESSION_DIR` | `$PI_CODING_AGENT_DIR/sessions` | pi session JSONL files |
+| `CODEX_WORKBENCH_META` | unset | Legacy override for `CWB_META` |
+| `CODEX_WORKBENCH_CONFIG` | unset | Legacy override for `CWB_CONFIG` |
 | `CODEX_BIN` | auto-detected | Force a specific Codex executable |
+| `PI_BIN` | auto-detected | Force a specific pi executable |
 
 By default, codex-workbench discovers the `codex` binary through your login shell's `PATH`. Set `CODEX_BIN` to override.
 
+`cwb doctor` reports every backend it can see.
+
+On first run, workbench moves legacy config files from `~/.codex/` into `~/.cwb/` if the new files do not exist yet.
+
 ---
 
 ## Troubleshooting
@@ -230,10 +212,18 @@ Run `codex-workbench doctor` to see where codex-workbench is looking. Common fix
 - 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
+### No Codex 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.
 
+### No pi sessions appear
+
+Make sure you've run the pi coding agent at least once. Sessions are stored as `.jsonl` files under `$PI_CODING_AGENT_SESSION_DIR` or `$PI_CODING_AGENT_DIR/sessions`. Run `ls ~/.pi/agent/sessions/` to verify.
+
+### A backend is missing from doctor
+
+Backends appear only when their session directory exists. For a new backend integration, add a provider under `src/providers/` with session discovery, parsing, binary discovery, and command routing.
+
 ### Remote source shows an error
 
 Verify the remote is reachable and has `cwb` in its non-interactive PATH:
@@ -282,15 +272,20 @@ 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)
+  codex-bin.js               # legacy Codex binary discovery wrapper
   config.js                  # environment-derived path constants
   model/
-    session-store.js         # session JSONL parsing and metadata persistence
+    metadata.js              # workbench-owned metadata persistence
+    session-store.js         # provider session aggregation and metadata merge
     format.js                # id/time/text formatting helpers
     directories.js           # filesystem directory listing and creation
     workbench-config.js      # SSH remote source config loader
+  providers/
+    codex.js                 # Codex provider
+    pi.js                    # pi provider
+    index.js                 # provider registry
   services/
-    codex-runner.js          # spawn Codex processes (new, resume, fork, etc.)
+    codex-runner.js          # backward-compatible provider runner wrapper
     session-sources.js       # aggregates local + remote session lists
     ssh-runner.js            # runs cwb commands over SSH (sync + async)
   ui/
@@ -314,8 +309,6 @@ scripts/
 npm test
 ```
 
-This runs syntax checks on all source files and executes the test suite.
-
 ### Publishing
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bramblex/codex-workbench",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Terminal workbench for browsing and managing local and SSH Codex sessions.",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "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/blessed-compat.test.js && node test/session-sources.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/blessed-compat.test.js && node test/config-paths.test.js && node test/session-sources.test.js && node test/workbench-config.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"

package/src/cli-output.js

@@ -1,7 +1,8 @@
 'use strict';
 
 const path = require('path');
-const { inspectCodexBin } = require('./codex-bin');
+const codex = require('./providers/codex');
+const { getAvailableProviders } = require('./providers');
 const { localTime, shortId, truncate } = require('./model/format');
 
 function usage() {
@@ -10,33 +11,35 @@ function usage() {
 Usage:
   codex-workbench [ui]
   codex-workbench doctor
+  codex-workbench backends [--json]
   codex-workbench list [--json] [--compact] [--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 new [--cwd <dir>] [--backend <backend>] [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:
+  CWB_HOME              default: ~/.cwb
+  CWB_META              default: $CWB_HOME/metadata.json
+  CWB_CONFIG            default: $CWB_HOME/config.json
   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_WORKBENCH_META  legacy override for CWB_META
+  CODEX_WORKBENCH_CONFIG legacy override for CWB_CONFIG
   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.all && session.archived) return false;
     if (opts.cwd) return path.resolve(session.cwd) === path.resolve(opts.cwd);
     return true;
   });
@@ -55,8 +58,8 @@ function printList(sessions, opts = {}) {
   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(',');
+      const label = session.name || truncate(session.first || session.last || '(no prompt)', 52);
+      const flags = [session.backend || '', session.archived ? 'archived' : '', session.note ? 'note' : ''].filter(Boolean).join(',');
       console.log(`  ${shortId(session.id)}  ${localTime(session.updatedAt)}  ${String(session.turns).padStart(2)} turns  ${flags ? `[${flags}] ` : ''}${label}`);
     }
   }
@@ -69,8 +72,9 @@ function compactSession(session) {
 }
 
 function printShow(session) {
-  console.log(`${session.name || '(unnamed)'} ${session.archived ? '[archived]' : ''}${session.hidden ? '[hidden]' : ''}`);
+  console.log(`${session.name || '(unnamed)'} ${session.archived ? '[archived]' : ''}`);
   console.log(`id:       ${session.id}`);
+  console.log(`backend:  ${session.backend || 'unknown'}`);
   if (session.sourceLabel) console.log(`source:   ${session.sourceLabel}`);
   console.log(`cwd:      ${session.cwd}`);
   console.log(`started:  ${localTime(session.startedAt)}`);
@@ -87,24 +91,32 @@ function printShow(session) {
 }
 
 function printDoctor() {
-  const result = inspectCodexBin();
+  const providers = getAvailableProviders();
+
   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(' ')}`);
+  console.log(`\nBackends detected: ${providers.length ? providers.map((p) => p.label).join(', ') : 'none'}`);
+
+  for (const provider of providers) {
+    console.log(`\n-- ${provider.label} --`);
+    const bin = provider.resolveBin();
+    if (bin) {
+      console.log(`  binary:   ${bin}`);
+    } else {
+      console.log(`  binary:   not found`);
+      try { provider.resolveBin(); } catch (err) { console.log(`  error:    ${err.message}`); }
+    }
+    try {
+      const files = provider.getSessionFiles();
+      console.log(`  sessions: ${files.length} file${files.length === 1 ? '' : 's'}`);
+    } catch (err) {
+      console.log(`  sessions: error - ${err.message}`);
+    }
+  }
+
+  if (!providers.length) {
+    console.log('\nNo backends available. Install Codex CLI or pi coding agent.');
+    process.exitCode = 1;
   }
-  if (!result.ok) process.exitCode = 1;
 }
 
 module.exports = {

package/src/cli.js

@@ -18,6 +18,9 @@ const {
   runNewCodexSession,
   usableCwd,
 } = require('./services/codex-runner');
+const { defaultBackend } = require('./services/session-sources');
+const { listLocalBackends } = require('./services/session-sources');
+const { getProvider } = require('./providers');
 const { runWorkbench } = require('./ui/workbench');
 const { createChildDirectory, listDirectories } = require('./model/directories');
 
@@ -34,6 +37,10 @@ function parseFlags(args) {
       if (i + 1 >= args.length) throw new Error('--cwd requires a directory.');
       out.cwd = args[++i];
     }
+    else if (arg === '--backend') {
+      if (i + 1 >= args.length) throw new Error('--backend requires a backend id.');
+      out.backend = args[++i];
+    }
     else out._.push(arg);
   }
   return out;
@@ -45,6 +52,12 @@ async function main() {
 
   const flags = parseFlags(rest);
   if (cmd === 'doctor') return printDoctor();
+  if (cmd === 'backends') {
+    const backends = listLocalBackends();
+    if (flags.json) console.log(JSON.stringify(backends, null, 2));
+    else backends.forEach((backend) => console.log(`${backend.id}\t${backend.label}`));
+    return undefined;
+  }
   if (cmd === 'dirs') {
     const payload = listDirectories(flags.cwd || process.cwd(), usableCwd);
     if (flags.json) console.log(JSON.stringify(payload, null, 2));
@@ -68,13 +81,15 @@ async function main() {
   if (cmd === 'show') return printShow(resolveSession(flags._[0], sessions));
   if (cmd === 'rename') return updateMetadata(resolveSession(flags._[0], sessions), { name: flags._.slice(1).join(' ') });
   if (cmd === 'note') return updateMetadata(resolveSession(flags._[0], sessions), { note: flags._.slice(1).join(' ') });
-  if (cmd === 'new' || cmd === 'start') return runNewCodexSession(flags.cwd || process.cwd(), flags._, true);
+  if (cmd === 'new' || cmd === 'start') {
+    const backend = flags.backend || defaultBackend();
+    getProvider(backend);
+    return runNewCodexSession(flags.cwd || process.cwd(), flags._, true, backend);
+  }
   if (cmd === 'resume') return runCodexCommand('resume', resolveSession(flags._[0], sessions), flags._.slice(1), true);
   if (cmd === 'fork') return runCodexCommand('fork', resolveSession(flags._[0], sessions), [], true);
   if (cmd === 'archive') return runCodexCommand('archive', resolveSession(flags._[0], sessions));
   if (cmd === 'unarchive') return runCodexCommand('unarchive', resolveSession(flags._[0], sessions));
-  if (cmd === 'hide') return updateMetadata(resolveSession(flags._[0], sessions), { hidden: true });
-  if (cmd === 'unhide') return updateMetadata(resolveSession(flags._[0], sessions), { hidden: false });
   if (cmd === 'delete') {
     const session = resolveSession(flags._[0], sessions);
     if (flags.file) return deleteSessionFile(session);

package/src/config.js

@@ -1,18 +1,58 @@
 'use strict';
 
+const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
 const HOME = os.homedir();
+
+// Codex paths (backward compatible env vars)
 const CODEX_HOME = process.env.CODEX_HOME || path.join(HOME, '.codex');
-const SESSIONS_DIR = process.env.CODEX_SESSIONS_DIR || path.join(CODEX_HOME, 'sessions');
-const META_PATH = process.env.CODEX_WORKBENCH_META || process.env.CSM_META || path.join(CODEX_HOME, 'codex-workbench.json');
-const CONFIG_PATH = process.env.CODEX_WORKBENCH_CONFIG || path.join(CODEX_HOME, 'codex-workbench.config.json');
+const CODEX_SESSIONS_DIR = process.env.CODEX_SESSIONS_DIR || path.join(CODEX_HOME, 'sessions');
+
+// Workbench-owned paths. Keep separate from provider-owned directories.
+const CWB_HOME = process.env.CWB_HOME || path.join(HOME, '.cwb');
+
+// pi coding agent paths
+const PI_CODING_AGENT_DIR = process.env.PI_CODING_AGENT_DIR || path.join(HOME, '.pi', 'agent');
+const PI_SESSIONS_DIR = process.env.PI_CODING_AGENT_SESSION_DIR || path.join(PI_CODING_AGENT_DIR, 'sessions');
+
+function migrateLegacyFile(legacyPath, nextPath) {
+  if (!legacyPath || !nextPath || legacyPath === nextPath) return;
+  if (fs.existsSync(nextPath) || !fs.existsSync(legacyPath)) return;
+  fs.mkdirSync(path.dirname(nextPath), { recursive: true });
+  fs.renameSync(legacyPath, nextPath);
+}
+
+const LEGACY_META_PATH = path.join(CODEX_HOME, 'codex-workbench.json');
+const LEGACY_CONFIG_PATH = path.join(CODEX_HOME, 'codex-workbench.config.json');
+
+const META_PATH = process.env.CWB_META ||
+  process.env.CODEX_WORKBENCH_META ||
+  process.env.CSM_META ||
+  path.join(CWB_HOME, 'metadata.json');
+
+const CONFIG_PATH = process.env.CWB_CONFIG ||
+  process.env.CODEX_WORKBENCH_CONFIG ||
+  path.join(CWB_HOME, 'config.json');
+
+if (!process.env.CWB_META && !process.env.CODEX_WORKBENCH_META && !process.env.CSM_META) {
+  migrateLegacyFile(LEGACY_META_PATH, META_PATH);
+}
+if (!process.env.CWB_CONFIG && !process.env.CODEX_WORKBENCH_CONFIG) {
+  migrateLegacyFile(LEGACY_CONFIG_PATH, CONFIG_PATH);
+}
 
 module.exports = {
   HOME,
+  CWB_HOME,
   CODEX_HOME,
+  CODEX_SESSIONS_DIR,
+  LEGACY_CONFIG_PATH,
+  LEGACY_META_PATH,
+  PI_CODING_AGENT_DIR,
+  PI_SESSIONS_DIR,
   CONFIG_PATH,
-  SESSIONS_DIR,
+  SESSIONS_DIR: CODEX_SESSIONS_DIR, // backward compat: default sessions dir (legacy)
   META_PATH,
 };

package/src/model/metadata.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { META_PATH } = require('../config');
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function loadMeta() {
+  const data = readJson(META_PATH, { sessions: {} });
+  if (!data.sessions) data.sessions = {};
+  return data;
+}
+
+function updateMetadata(session, patch) {
+  const meta = loadMeta();
+  meta.sessions[session.id] = { ...(meta.sessions[session.id] || {}), ...patch };
+  meta.updatedAt = new Date().toISOString();
+  writeJson(META_PATH, meta);
+}
+
+function removeMetadata(session) {
+  const meta = loadMeta();
+  delete meta.sessions[session.id];
+  meta.updatedAt = new Date().toISOString();
+  writeJson(META_PATH, meta);
+}
+
+module.exports = {
+  loadMeta,
+  removeMetadata,
+  updateMetadata,
+};