better-codex 0.1.0 → 0.1.3

package/README.md

@@ -1,26 +1,79 @@
 # better-codex
 
-Consumer-friendly launcher for the Codex Hub web UI.
+better-codex is a Codex session hub: a web UI plus a local backend that supervises `codex app-server` to manage multiple accounts, sessions, reviews, and analytics in one place.
 
-## Install
+## Features
+- Multi-account hub with session list, threads, and model switching.
+- Reviews view backed by Codex review mode events.
+- Analytics + search (local SQLite indexes).
+- Zero-config `better-codex` launcher that boots backend + UI.
 
+## Project Layout
+- `apps/backend` Bun + Elysia hub server, Codex app-server supervisor.
+- `apps/web` React UI (Vite).
+- `scripts/` launcher scripts for local dev.
+- `bin/` CLI wrappers (`better-codex`).
+
+## Requirements
+- Bun: https://bun.sh
+- Codex CLI (`codex`) available in PATH.
+- Node 18+ for the npm package wrapper.
+
+## Install (npm)
 ```bash
 npm i -g better-codex
 ```
 
-Requires Bun: https://bun.sh
+## Run (zero-config)
+```bash
+better-codex
+```
 
-## Run
+Optional:
+```bash
+better-codex web --open
+```
 
+## Run from Source
 ```bash
+export PATH="$(pwd)/bin:$PATH"
 better-codex
 ```
 
-`better-codex web` works too (same command).
+## Manual Dev (backend + UI)
+```bash
+cd apps/backend
+bun install
+bun run dev
+```
+
+```bash
+cd apps/web
+VITE_CODEX_HUB_URL=http://127.0.0.1:7711 \
+VITE_CODEX_HUB_TOKEN=<token from backend log> \
+bun install
+bun run dev
+```
+
+## Configuration
+### Backend env vars
+- `CODEX_HUB_HOST` (default `127.0.0.1`)
+- `CODEX_HUB_PORT` (default `7711`)
+- `CODEX_HUB_TOKEN` (auto-generated by launcher)
+- `CODEX_BIN` (default `codex`)
+- `CODEX_FLAGS`, `CODEX_FLAGS_JSON`
+- `CODEX_APP_SERVER_FLAGS`, `CODEX_APP_SERVER_FLAGS_JSON`
+- `CODEX_HUB_DEFAULT_CWD` (default repo root)
+- `CODEX_HUB_DATA_DIR` (default `~/.codex-hub`)
+- `CODEX_HUB_PROFILES_DIR` (default `~/.codex/profiles`)
+- `CODEX_HUB_DEFAULT_CODEX_HOME` (default `~/.codex`)
+
+### Web env vars
+- `VITE_CODEX_HUB_URL` (default `http://127.0.0.1:7711`)
+- `VITE_CODEX_HUB_TOKEN`
 
-Options:
-- `--root PATH` set the repo root (defaults to current dir or parent lookup).
-- `--host 127.0.0.1` host for backend + UI.
-- `--backend-port 7711` backend port.
-- `--web-port 5173` UI port.
-- `--open` open the UI in your browser after startup.
+## Troubleshooting
+- `bun: command not found`: install Bun and reopen your terminal.
+- `codex: command not found`: install Codex CLI and ensure it is in PATH.
+- Port already in use: pass `--backend-port` or `--web-port`.
+- UI can’t connect: token mismatch or backend not running; restart and copy the token.

package/bin/better-codex.cjs

@@ -5,6 +5,73 @@ const { existsSync } = require('node:fs');
 const { dirname, join, resolve } = require('node:path');
 const { randomUUID } = require('node:crypto');
 
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m',
+  blue: '\x1b[34m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+  brightCyan: '\x1b[96m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightMagenta: '\x1b[95m',
+};
+
+const symbols = {
+  tick: '✔',
+  cross: '✖',
+  pointer: '▶',
+  dot: '●',
+  line: '─',
+  arrow: '→',
+  rocket: '◆',
+  sparkles: '✦',
+  globe: '◎',
+  server: '⚡',
+  info: 'ℹ',
+};
+
+const BANNER = `
+${c.brightCyan}${c.bold}    ____       __  __              ______          __         
+   / __ )___  / /_/ /____  _____  / ____/___  ____/ /__  _  __
+  / __  / _ \\/ __/ __/ _ \\/ ___/ / /   / __ \\/ __  / _ \\| |/_/
+ / /_/ /  __/ /_/ /_/  __/ /    / /___/ /_/ / /_/ /  __/>  <  
+/_____/\\___/\\__/\\__/\\___/_/     \\____/\\____/\\__,_/\\___/_/|_|  
+${c.reset}
+${c.dim}${c.italic}    A modern web interface for Codex${c.reset}
+`;
+
+const log = {
+  info: (msg) => console.log(`${c.cyan}${symbols.info}${c.reset} ${msg}`),
+  success: (msg) => console.log(`${c.green}${symbols.tick}${c.reset} ${msg}`),
+  warn: (msg) => console.log(`${c.yellow}⚠${c.reset} ${msg}`),
+  error: (msg) => console.log(`${c.red}${symbols.cross}${c.reset} ${msg}`),
+  step: (msg) => console.log(`${c.magenta}${symbols.pointer}${c.reset} ${msg}`),
+  dim: (msg) => console.log(`${c.dim}  ${msg}${c.reset}`),
+};
+
+const box = (lines, color = c.cyan) => {
+  // Calculate display width (ANSI codes = 0 width)
+  const displayWidth = (str) => str.replace(/\x1b\[[0-9;]*m/g, '').length;
+
+  const maxLen = Math.max(...lines.map(displayWidth));
+  const top = `${color}╭${'─'.repeat(maxLen + 2)}╮${c.reset}`;
+  const bottom = `${color}╰${'─'.repeat(maxLen + 2)}╯${c.reset}`;
+  const padded = lines.map((l) => {
+    const width = displayWidth(l);
+    return `${color}│${c.reset} ${l}${' '.repeat(maxLen - width)} ${color}│${c.reset}`;
+  });
+  return [top, ...padded, bottom].join('\n');
+};
+
 const DEFAULTS = {
   host: '127.0.0.1',
   backendPort: 7711,
@@ -13,18 +80,39 @@ const DEFAULTS = {
 };
 
 const printHelp = () => {
-  console.log(`better-codex
-
-Usage:
-  better-codex web [--root PATH] [--host 127.0.0.1] [--backend-port 7711] [--web-port 5173] [--open]
-`);
+  console.log(BANNER);
+  console.log(`${c.bold}USAGE${c.reset}`);
+  console.log(`  ${c.cyan}better-codex${c.reset} ${c.dim}[command]${c.reset} ${c.dim}[options]${c.reset}`);
+  console.log('');
+  console.log(`${c.bold}COMMANDS${c.reset}`);
+  console.log(`  ${c.green}web${c.reset}       Start the web interface ${c.dim}(default)${c.reset}`);
+  console.log('');
+  console.log(`${c.bold}OPTIONS${c.reset}`);
+  console.log(`  ${c.yellow}--root${c.reset} ${c.dim}<path>${c.reset}         Path to project root`);
+  console.log(`  ${c.yellow}--host${c.reset} ${c.dim}<host>${c.reset}         Host to bind ${c.dim}(default: 127.0.0.1)${c.reset}`);
+  console.log(`  ${c.yellow}--backend-port${c.reset} ${c.dim}<n>${c.reset}   Backend port ${c.dim}(default: 7711)${c.reset}`);
+  console.log(`  ${c.yellow}--web-port${c.reset} ${c.dim}<n>${c.reset}       Web UI port ${c.dim}(default: 5173)${c.reset}`);
+  console.log(`  ${c.yellow}--open${c.reset}                Open browser automatically`);
+  console.log(`  ${c.yellow}--help, -h${c.reset}            Show this help message`);
+  console.log('');
+  console.log(`${c.bold}EXAMPLES${c.reset}`);
+  console.log(`  ${c.dim}$${c.reset} better-codex`);
+  console.log(`  ${c.dim}$${c.reset} better-codex web --open`);
+  console.log(`  ${c.dim}$${c.reset} better-codex --host 0.0.0.0 --web-port 3000`);
+  console.log('');
 };
 
 const parseArgs = () => {
   const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
   const options = { ...DEFAULTS, root: undefined };
   const command = args[0] && !args[0].startsWith('-') ? args[0] : 'web';
-  const flagArgs = command === 'web' ? args.slice(1) : args;
+  const flagArgs = command === args[0] ? args.slice(1) : args;
 
   for (let i = 0; i < flagArgs.length; i += 1) {
     const arg = flagArgs[i];
@@ -52,55 +140,85 @@ const parseArgs = () => {
       options.open = true;
       continue;
     }
-    if (arg === '--help' || arg === '-h') {
-      printHelp();
-      process.exit(0);
-    }
-    console.error(`Unknown option: ${arg}`);
-    printHelp();
+    log.error(`Unknown option: ${c.yellow}${arg}${c.reset}`);
+    console.log(`Run ${c.cyan}better-codex --help${c.reset} for usage.`);
     process.exit(1);
   }
 
   return { command, options };
 };
 
+const isRoot = (dir) =>
+  existsSync(join(dir, 'apps', 'backend', 'package.json')) &&
+  existsSync(join(dir, 'apps', 'web', 'package.json'));
+
 const findRoot = (explicit) => {
-  let current = resolve(explicit ?? process.cwd());
+  if (explicit) {
+    const resolved = resolve(explicit);
+    if (isRoot(resolved)) {
+      return resolved;
+    }
+    throw new Error(`Specified root does not contain apps/: ${explicit}`);
+  }
+
+  let current = resolve(process.cwd());
   for (let depth = 0; depth < 8; depth += 1) {
     if (isRoot(current)) {
       return current;
     }
     const parent = dirname(current);
-    if (parent === current) {
-      break;
-    }
+    if (parent === current) break;
     current = parent;
   }
+
+  const bundledRoot = resolve(dirname(__filename), '..');
+  if (isRoot(bundledRoot)) {
+    return bundledRoot;
+  }
+
+  const npmGlobalRoot = resolve(dirname(__filename), '..', '..');
+  const npmPackageRoot = join(npmGlobalRoot, 'better-codex');
+  if (isRoot(npmPackageRoot)) {
+    return npmPackageRoot;
+  }
+
   throw new Error(
-    'Could not locate. Run from the repo root or pass --root.'
+    `Could not locate Better Codex apps.\n` +
+      `The bundled apps may be missing. Try reinstalling:\n` +
+      `  ${c.cyan}npm install -g better-codex${c.reset}`
   );
 };
 
-const isRoot = (dir) =>
-  existsSync(join(dir, 'apps', 'backend', 'package.json')) &&
-  existsSync(join(dir, 'apps', 'web', 'package.json'));
-
 const ensureBun = () => {
-  const result = spawnSync('bun', ['--version'], { stdio: 'ignore' });
+  const result = spawnSync('bun', ['--version'], { stdio: 'pipe' });
   if (result.status !== 0) {
-    throw new Error('bun is required. Install it first: https://bun.sh');
+    console.log('');
+    log.error(`${c.bold}Bun is required but not installed${c.reset}`);
+    console.log('');
+    console.log(`  Install Bun: ${c.cyan}${c.underline}https://bun.sh${c.reset}`);
+    console.log('');
+    console.log(`  ${c.dim}# Quick install:${c.reset}`);
+    console.log(`  ${c.dim}$${c.reset} curl -fsSL https://bun.sh/install | bash`);
+    console.log('');
+    process.exit(1);
   }
+  const version = result.stdout?.toString().trim() || 'unknown';
+  return version;
 };
 
-const ensureDeps = (cwd) => {
+const ensureDeps = (cwd, name) => {
   const nodeModules = join(cwd, 'node_modules');
   if (existsSync(nodeModules)) {
-    return;
+    return true;
   }
-  const result = spawnSync('bun', ['install'], { cwd, stdio: 'inherit' });
+  log.step(`Installing dependencies for ${c.cyan}${name}${c.reset}...`);
+  const result = spawnSync('bun', ['install'], { cwd, stdio: 'ignore' });
   if (result.status !== 0) {
-    throw new Error(`bun install failed in ${cwd}`);
+    log.error(`Failed to install dependencies in ${cwd}`);
+    process.exit(1);
   }
+  log.success(`Dependencies installed for ${c.cyan}${name}${c.reset}`);
+  return true;
 };
 
 const openUrl = (url) => {
@@ -115,16 +233,28 @@ const openUrl = (url) => {
 };
 
 const runWeb = (options) => {
-  ensureBun();
+  console.log(BANNER);
+
+  const bunVersion = ensureBun();
+  log.success(`Bun ${c.dim}v${bunVersion}${c.reset}`);
+
   const root = findRoot(options.root);
+  log.success(`Project root: ${c.dim}${root}${c.reset}`);
+
   const backendDir = join(root, 'apps', 'backend');
   const webDir = join(root, 'apps', 'web');
   const token = randomUUID();
   const backendUrl = `http://${options.host}:${options.backendPort}`;
   const webUrl = `http://${options.host}:${options.webPort}`;
 
-  ensureDeps(backendDir);
-  ensureDeps(webDir);
+  console.log('');
+
+  ensureDeps(backendDir, 'backend');
+  ensureDeps(webDir, 'web');
+
+  console.log('');
+  log.step(`Starting servers...`);
+  console.log('');
 
   const backend = spawn('bun', ['run', 'dev'], {
     cwd: backendDir,
@@ -133,9 +263,10 @@ const runWeb = (options) => {
       CODEX_HUB_HOST: options.host,
       CODEX_HUB_PORT: String(options.backendPort),
       CODEX_HUB_TOKEN: token,
-      CODEX_HUB_DEFAULT_CWD: root,
+      CODEX_HUB_DEFAULT_CWD: process.cwd(),
     },
-    stdio: 'inherit',
+    stdio: 'pipe',
+    detached: false,
   });
 
   const web = spawn(
@@ -148,27 +279,50 @@ const runWeb = (options) => {
         VITE_CODEX_HUB_URL: backendUrl,
         VITE_CODEX_HUB_TOKEN: token,
       },
-      stdio: 'inherit',
+      stdio: 'pipe',
+      detached: false,
     }
   );
 
-  console.log('');
-  console.log('Codex Web running:');
-  console.log(`  UI: ${webUrl}`);
-  console.log(`  Backend: ${backendUrl}`);
-  console.log('');
+  backend.stdout?.resume();
+  backend.stderr?.resume();
+  web.stdout?.resume();
+  web.stderr?.resume();
 
-  if (options.open) {
-    openUrl(webUrl);
-  }
+  setTimeout(() => {
+    console.log('');
+    console.log(
+      box(
+        [
+          `${c.bold}Better Codex is running${c.reset}`,
+          '',
+          `  Web UI    ${c.cyan}${c.underline}${webUrl}${c.reset}`,
+          `  Backend   ${c.dim}${backendUrl}${c.reset}`,
+          '',
+          `  ${c.dim}Press ${c.reset}${c.bold}Ctrl+C${c.reset}${c.dim} to stop${c.reset}`,
+        ],
+        c.green
+      )
+    );
+    console.log('');
+
+    if (options.open) {
+      log.info(`Opening browser...`);
+      openUrl(webUrl);
+    }
+  }, 1500);
 
   const shutdown = () => {
+    console.log('');
+    log.info('Shutting down...');
     backend.kill();
     web.kill();
   };
 
   process.on('SIGINT', () => {
     shutdown();
+    log.success('Goodbye! 👋');
+    console.log('');
     process.exit(0);
   });
 
@@ -178,13 +332,15 @@ const runWeb = (options) => {
   });
 
   const onExit = (name) => (code) => {
-    console.error(`${name} exited with code ${code}`);
+    if (code !== 0 && code !== null) {
+      log.error(`${name} exited with code ${code}`);
+    }
     shutdown();
     process.exit(code ?? 0);
   };
 
-  backend.on('exit', onExit('backend'));
-  web.on('exit', onExit('web'));
+  backend.on('exit', onExit('Backend'));
+  web.on('exit', onExit('Web'));
 };
 
 const main = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-codex",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Web launcher for Codex Hub",
   "bin": {
     "better-codex": "bin/better-codex.cjs"