@mmmbuto/nexuscrew 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide A. Guglielmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+## Overview
+
+NexusCrew is a **tmux-based** AI cockpit that orchestrates Claude Code, Codex CLI, Gemini CLI, and Qwen Code through persistent tmux sessions.
+
+This is a **study project** exploring an alternative approach to AI CLI orchestration, based on experience with [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli). Instead of managing PTY processes in-memory, NexusCrew delegates session lifecycle to **tmux** — sessions survive server restarts, can be accessed directly from the terminal, and extend to remote hosts via SSH.
+
+> **Status**: Beta — experimental, API may change
+
+---
+
+## Why tmux?
+
+| Problem | NexusCLI (PTY) | NexusCrew (tmux) |
+|---------|---------------|-------------------|
+| Server crash | All sessions die | Sessions survive |
+| Direct access | Web UI only | Web UI + `tmux attach` |
+| Remote machines | Not supported | SSH to any host |
+| Native deps | node-pty required | Zero native deps |
+| Session recovery | Manual | Automatic |
+
+---
+
+## Features
+
+- **Persistent sessions** — tmux windows survive server restarts
+- **Multi-engine** — Claude Code, Codex CLI, Gemini CLI, Qwen Code
+- **Auto-discovery** — detects installed CLIs + parses shell aliases/functions from `providers.zsh`
+- **Remote hosts** — manage tmux sessions on any machine via SSH
+- **Unified web UI** — same interface across all engines and hosts
+- **SSE streaming** — real-time output from tmux sessions
+- **Zero native deps** — no node-pty, no compilation required
+- **Cross-platform** — Linux, macOS, Termux (Android)
+
+---
+
+## Engine Discovery
+
+NexusCrew automatically detects:
+
+1. **Standard CLIs** — `claude`, `codex`, `gemini`, `qwen` via PATH and common install paths
+2. **Shell aliases** — parses `~/Dev/providers.zsh` (or configured path) for wrapper functions like:
+   - `claude-glm-a`, `codex-alibaba-qwen35`, `claude-minimax27`, etc.
+   - Each alias becomes available as a custom lane in the model selector
+
+---
+
+## Install
+
+```bash
+npm install -g @mmmbuto/nexuscrew
+```
+
+Then initialize:
+
+```bash
+nexuscrew init
+```
+
+And start:
+
+```bash
+nexuscrew start
+```
+
+Open `http://localhost:41820` in your browser.
+
+### Termux (Android)
+
+```bash
+pkg install tmux nodejs
+npm install -g @mmmbuto/nexuscrew
+nexuscrew init
+nexuscrew start
+```
+
+---
+
+## Remote Hosts
+
+Add SSH hosts to manage tmux sessions on remote machines:
+
+```bash
+nexuscrew hosts add --name vps1 --host example.com --user user
+nexuscrew hosts add --name vps2 --host 192.168.1.10 --user admin --port 2222
+```
+
+Hosts appear in the UI's model selector. Sessions created on a remote host open a tmux window there via SSH.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexuscrew init` | First-time setup (config, hosts, tmux check) |
+| `nexuscrew start` | Start server + tmux session |
+| `nexuscrew stop` | Stop server |
+| `nexuscrew status` | Server + tmux + hosts status |
+| `nexuscrew engines` | Discover available AI CLIs and aliases |
+| `nexuscrew sessions` | List tmux windows |
+| `nexuscrew attach` | Attach to tmux session directly |
+| `nexuscrew config` | View/edit configuration |
+| `nexuscrew hosts list` | List configured hosts |
+| `nexuscrew hosts add` | Add remote SSH host |
+| `nexuscrew hosts remove` | Remove a host |
+
+---
+
+## Configuration
+
+Config stored in `~/.nexuscrew/config.json`:
+
+```json
+{
+  "port": 41820,
+  "tmuxSession": "nexuscrew",
+  "logDir": "~/.nexuscrew/logs",
+  "autoDiscovery": true,
+  "providersPath": "~/Dev/providers.zsh"
+}
+```
+
+Hosts stored in `~/.nexuscrew/hosts.json`:
+
+```json
+[
+  { "name": "local", "type": "local", "default": true },
+  { "name": "vps1", "type": "ssh", "host": "example.com", "user": "user", "port": "22" }
+]
+```
+
+---
+
+## Network
+
+| Protocol | Default Port | Use Case |
+|----------|--------------|----------|
+| HTTP | `41820` | Local access |
+
+---
+
+## Architecture
+
+```
+Browser ←SSE→ Express Server ←tmux→ tmux session "nexuscrew"
+                                      ├─ window: nc-abc12345 (claude)
+                                      ├─ window: nc-def67890 (codex)
+                                      └─ window: nc-ghi11111 (gemini)
+```
+
+Each AI session = one tmux window. Output captured via `tee` to log files, parsed by engine-specific parsers, and streamed to the UI via SSE.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/dionanos/nexuscrew
+cd nexuscrew
+npm install
+cd frontend && npm install && npm run build && cd ..
+npm run dev
+```
+
+---
+
+## Relation to NexusCLI
+
+NexusCrew is a **study branch** inspired by [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli). It shares the same web UI but replaces the PTY-based process management with tmux-based persistent sessions. The goal is to explore whether tmux provides a simpler, more robust foundation for AI CLI orchestration — especially for remote hosts and crash recovery.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/bin/nexuscrew.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+const CONFIG_DIR = path.join(process.env.HOME || '', '.nexuscrew');
+const DB_PATH = path.join(CONFIG_DIR, 'nexuscrew.db');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const HOSTS_PATH = path.join(CONFIG_DIR, 'hosts.json');
+const TMUX_SESSION = 'nexuscrew';
+
+const program = new Command();
+program
+  .name('nexuscrew')
+  .description('tmux-based AI cockpit')
+  .version('0.1.0');
+
+// --- init ---
+program.command('init')
+  .description('First-time setup')
+  .action(() => {
+    if (!fs.existsSync(CONFIG_DIR)) {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true });
+      console.log('Created ~/.nexuscrew/');
+    }
+
+    // Default config
+    if (!fs.existsSync(CONFIG_PATH)) {
+      fs.writeFileSync(CONFIG_PATH, JSON.stringify({
+        port: 41820,
+        tmuxSession: TMUX_SESSION,
+        logDir: path.join(CONFIG_DIR, 'logs'),
+        autoDiscovery: true,
+        providersPath: ''
+      }, null, 2));
+      console.log('Created config.json');
+    }
+
+    // Default hosts
+    if (!fs.existsSync(HOSTS_PATH)) {
+      fs.writeFileSync(HOSTS_PATH, JSON.stringify([
+        { name: 'local', type: 'local', default: true }
+      ], null, 2));
+      console.log('Created hosts.json');
+    }
+
+    // Log dir
+    const logDir = path.join(CONFIG_DIR, 'logs');
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    // Check tmux
+    try {
+      execSync('which tmux', { stdio: 'pipe' });
+      console.log('tmux: OK');
+    } catch {
+      console.error('tmux not found! Install: apt install tmux (or pkg install tmux)');
+    }
+
+    console.log('\nDone! Run: nexuscrew start');
+  });
+
+// --- start ---
+program.command('start')
+  .description('Start the server')
+  .option('-p, --port <port>', 'Port', '41820')
+  .option('-d, --dev', 'Dev mode (no frontend)')
+  .action((opts) => {
+    // Ensure tmux master session exists
+    try {
+      execSync(`tmux has-session -t ${TMUX_SESSION} 2>/dev/null`);
+    } catch {
+      execSync(`tmux new-session -d -s ${TMUX_SESSION} -x 200 -y 50`);
+      console.log(`Created tmux session: ${TMUX_SESSION}`);
+    }
+
+    const env = { ...process.env, PORT: opts.port };
+    if (opts.dev) env.NEXUSCREW_DEV = '1';
+
+    const args = [path.join(__dirname, '..', 'lib', 'server', 'server.js')];
+    const child = require('child_process').spawn('node', args, {
+      env,
+      stdio: 'inherit',
+      detached: false
+    });
+    child.on('exit', (code) => process.exit(code || 0));
+  });
+
+// --- stop ---
+program.command('stop')
+  .description('Stop the server')
+  .action(() => {
+    try {
+      const pid = execSync(`lsof -ti :41820 2>/dev/null`).toString().trim();
+      if (pid) {
+        execSync(`kill ${pid}`);
+        console.log('Server stopped');
+      } else {
+        console.log('Server not running');
+      }
+    } catch {
+      console.log('Server not running');
+    }
+  });
+
+// --- status ---
+program.command('status')
+  .description('Show server and tmux status')
+  .action(() => {
+    console.log('=== NexusCrew Status ===\n');
+
+    // Server
+    try {
+      const pid = execSync(`lsof -ti :41820 2>/dev/null`).toString().trim();
+      console.log(`Server: RUNNING (pid ${pid})`);
+    } catch {
+      console.log('Server: STOPPED');
+    }
+
+    // tmux
+    try {
+      const windows = execSync(`tmux list-windows -t ${TMUX_SESSION} -F '#{window_name} #{?window_active,*, }' 2>/dev/null`).toString().trim();
+      console.log(`\ntmux session "${TMUX_SESSION}":`);
+      windows.split('\n').forEach(w => console.log(`  ${w}`));
+    } catch {
+      console.log(`\ntmux session "${TMUX_SESSION}": NOT FOUND`);
+    }
+
+    // Hosts
+    if (fs.existsSync(HOSTS_PATH)) {
+      const hosts = JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'));
+      console.log('\nHosts:');
+      hosts.forEach(h => {
+        if (h.type === 'local') {
+          console.log(`  ${h.name}: local`);
+        } else {
+          const status = testSSH(h) ? 'OK' : 'UNREACHABLE';
+          console.log(`  ${h.name}: ${h.user}@${h.host}${h.port ? ':' + h.port : ''} [${status}]`);
+        }
+      });
+    }
+  });
+
+// --- attach ---
+program.command('attach')
+  .description('Attach to tmux session')
+  .option('-w, --window <name>', 'Attach to specific window')
+  .action((opts) => {
+    const target = opts.window ? `${TMUX_SESSION}:${opts.window}` : TMUX_SESSION;
+    try {
+      execSync(`tmux attach -t ${target}`, { stdio: 'inherit' });
+    } catch {
+      console.error(`Session/window not found: ${target}`);
+    }
+  });
+
+// --- sessions ---
+program.command('sessions')
+  .description('List tmux windows')
+  .action(() => {
+    try {
+      const out = execSync(
+        `tmux list-windows -t ${TMUX_SESSION} -F '#{window_index}: #{window_name} [#{window_width}x#{window_height}] #{?window_active,(active),}' 2>/dev/null`
+      ).toString().trim();
+      console.log(out);
+    } catch {
+      console.log('No tmux session found');
+    }
+  });
+
+// --- config ---
+program.command('config')
+  .description('View/edit configuration')
+  .option('-l, --list', 'Show current config')
+  .option('-s, --set <key=value>', 'Set a config value')
+  .action((opts) => {
+    if (!fs.existsSync(CONFIG_PATH)) {
+      console.error('Run nexuscrew init first');
+      return;
+    }
+    const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+
+    if (opts.set) {
+      const [key, ...rest] = opts.set.split('=');
+      const value = rest.join('=');
+      config[key] = isNaN(value) ? value : Number(value);
+      fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+      console.log(`Set ${key} = ${value}`);
+    } else {
+      console.log(JSON.stringify(config, null, 2));
+    }
+  });
+
+// --- hosts ---
+const hostsCmd = program.command('hosts').description('Manage remote hosts');
+
+hostsCmd.command('list')
+  .description('List configured hosts')
+  .action(() => {
+    if (!fs.existsSync(HOSTS_PATH)) {
+      console.log('No hosts configured. Run nexuscrew init.');
+      return;
+    }
+    const hosts = JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'));
+    hosts.forEach((h, i) => {
+      const status = h.type === 'local' ? 'local' : (testSSH(h) ? 'OK' : 'UNREACHABLE');
+      console.log(`[${i}] ${h.name} (${h.type}) ${h.host || ''} [${status}]${h.default ? ' *default*' : ''}`);
+    });
+  });
+
+hostsCmd.command('add')
+  .description('Add a remote host')
+  .requiredOption('-n, --name <name>', 'Host name')
+  .requiredOption('-h, --host <host>', 'Hostname or IP')
+  .option('-u, --user <user>', 'SSH user', 'dag')
+  .option('-p, --port <port>', 'SSH port', '22')
+  .option('-k, --key <path>', 'SSH key path')
+  .action((opts) => {
+    const hosts = fs.existsSync(HOSTS_PATH)
+      ? JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'))
+      : [];
+    hosts.push({
+      name: opts.name,
+      type: 'ssh',
+      host: opts.host,
+      user: opts.user,
+      port: opts.port,
+      key: opts.key || undefined
+    });
+    fs.writeFileSync(HOSTS_PATH, JSON.stringify(hosts, null, 2));
+    console.log(`Added host: ${opts.name}`);
+  });
+
+hostsCmd.command('remove')
+  .description('Remove a host')
+  .requiredOption('-n, --name <name>', 'Host name')
+  .action((opts) => {
+    let hosts = fs.existsSync(HOSTS_PATH)
+      ? JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'))
+      : [];
+    hosts = hosts.filter(h => h.name !== opts.name);
+    fs.writeFileSync(HOSTS_PATH, JSON.stringify(hosts, null, 2));
+    console.log(`Removed host: ${opts.name}`);
+  });
+
+// --- engines ---
+program.command('engines')
+  .description('Discover available AI CLIs')
+  .action(() => {
+    const engines = discoverEngines();
+    console.log('\nDiscovered Engines:\n');
+    for (const [name, info] of Object.entries(engines)) {
+      console.log(`  ${name}: ${info.available ? 'OK' : 'NOT FOUND'}`);
+      if (info.path) console.log(`    path: ${info.path}`);
+      if (info.aliases.length) {
+        console.log(`    aliases: ${info.aliases.join(', ')}`);
+      }
+    }
+    console.log('');
+  });
+
+// --- helpers ---
+function testSSH(host) {
+  try {
+    const keyOpt = host.key ? `-i ${host.key}` : '';
+    const portOpt = host.port && host.port !== '22' ? `-p ${host.port}` : '';
+    execSync(`ssh -o ConnectTimeout=3 -o BatchMode=yes ${keyOpt} ${portOpt} ${host.user}@${host.host} echo ok`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function discoverEngines() {
+  const engines = {
+    claude: { available: false, path: null, aliases: [], type: 'interactive' },
+    codex: { available: false, path: null, aliases: [], type: 'exec' },
+    gemini: { available: false, path: null, aliases: [], type: 'interactive' },
+    qwen: { available: false, path: null, aliases: [], type: 'interactive' }
+  };
+
+  // Direct CLI discovery
+  const cliPaths = {
+    claude: [
+      path.join(process.env.HOME, '.local/bin/claude'),
+      path.join(process.env.HOME, '.claude/local/claude'),
+      '/usr/local/bin/claude'
+    ],
+    codex: [
+      path.join(process.env.HOME, '.local/codex-lts/bin/codex'),
+      path.join(process.env.HOME, '.local/codex-lts/node_modules/.bin/codex')
+    ],
+    gemini: [
+      path.join(process.env.HOME, '.local/bin/gemini'),
+      path.join(process.env.HOME, '.gemini/bin/gemini')
+    ],
+    qwen: [
+      path.join(process.env.HOME, '.local/bin/qwen'),
+      path.join(process.env.HOME, '.qwen/bin/qwen')
+    ]
+  };
+
+  for (const [engine, paths] of Object.entries(cliPaths)) {
+    for (const p of paths) {
+      try {
+        if (fs.existsSync(p) && fs.statSync(p).mode & 0o111) {
+          engines[engine].available = true;
+          engines[engine].path = p;
+          break;
+        }
+      } catch {}
+    }
+    // Fallback: check PATH
+    if (!engines[engine].available) {
+      try {
+        const which = execSync(`which ${engine} 2>/dev/null`).toString().trim();
+        if (which) {
+          engines[engine].available = true;
+          engines[engine].path = which;
+        }
+      } catch {}
+    }
+  }
+
+  // Parse providers file for aliases (if configured)
+  const configPath = path.join(process.env.HOME || '', '.nexuscrew', 'config.json');
+  let providersPath = '';
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    providersPath = cfg.providersPath || '';
+  } catch {}
+  if (providersPath && fs.existsSync(providersPath)) {
+    const content = fs.readFileSync(providersPath, 'utf8');
+    const funcRegex = /^(codex-[a-z0-9-]+|claude-[a-z0-9-]+|gemini-[a-z0-9-]+|qwen-[a-z0-9-]+)\(\)/gm;
+    let match;
+    while ((match = funcRegex.exec(content)) !== null) {
+      const alias = match[1];
+      const baseEngine = alias.split('-')[0];
+      const engine = baseEngine === 'codex' ? 'codex' : baseEngine === 'claude' ? 'claude' : baseEngine === 'gemini' ? 'gemini' : 'qwen';
+      if (engines[engine]) {
+        engines[engine].aliases.push(alias);
+      }
+    }
+  }
+
+  return engines;
+}
+
+program.parse();