@mmmbuto/nexuscrew 0.2.1 → 0.2.2

package/README.md

@@ -1,122 +1,177 @@
-# NexusCrew
+## Overview
 
-Mobile-first `tmux` cockpit for local and remote AI CLI sessions.
+NexusCrew is a **tmux-based** AI cockpit that orchestrates Claude Code, Codex CLI, Gemini CLI, and Qwen Code through persistent tmux sessions.
 
-NexusCrew is built for `Termux` and smartphone-first workflows, but also runs on Linux and macOS. It keeps CLI sessions alive inside `tmux`, exposes them through a web UI, and lets you switch between local and SSH hosts without reopening everything by hand.
+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** so sessions survive server restarts and can be accessed directly from the terminal.
 
-## Highlights
+> **Status**: Beta — experimental, API may change
 
-- Persistent `tmux` sessions for Claude, Codex, Gemini and Qwen
-- Local + SSH host switching from one mobile-first UI
-- Remote streaming via `tmux capture-pane`
-- File and image attachments, including remote SSH staging
-- Local STT with `whisper.cpp`, browser fallback, system TTS
-- Dark/light theme
-- Installable web app shell with mobile icon/manifest
-- Termux-oriented CLI with setup, start, status and host management
+> **Disclaimer**: This project is experimental. The automation pipeline is fast enough that it may be generated, tested, and published before I finish thinking about it. Expect incomplete features, mistakes, and breaking changes.
+
+---
+
+## 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 | Experimental host registry |
+| Native deps | node-pty required | SQLite native addon |
+| Session recovery | Manual | Automatic |
+
+---
+
+## Features
+
+- **Persistent sessions** — standalone tmux sessions survive server restarts
+- **Multi-engine** — Claude Code, Codex CLI, Gemini CLI, Qwen Code
+- **Auto-discovery** — detects installed CLIs plus live shell aliases/functions and generic shell config fallbacks
+- **Explicit tmux creation** — create a new tmux session only from a detected runnable launcher
+- **Unified web UI** — attach chat to real active tmux sessions
+- **SSE streaming** — real-time output from tmux sessions
+- **Cross-platform** — Linux, macOS, Termux (Android)
+
+---
+
+## Engine Discovery
+
+NexusCrew automatically detects:
+
+1. **PATH binaries** — `claude`, `codex`, `gemini`, `qwen` when present in the runtime PATH
+2. **Live shell wrappers** — aliases/functions available in the current login shell
+3. **Shell-file fallbacks** — wrappers detected from `.zshrc`, `.bashrc`, `.profile`, and optional extra shell sources
+
+Launchers detected only from shell files are shown as detected metadata but are not treated as runnable until they are verified in the active shell context.
+
+---
 
 ## Install
 
 ```bash
 npm install -g @mmmbuto/nexuscrew
-nexuscrew setup
-nexuscrew start
 ```
 
-`nexuscrew start` runs the server in background, waits for health, and can open the browser for you.
+Then initialize:
+
+```bash
+nexuscrew init
+```
 
-Default URL:
+And start:
 
-```text
-http://localhost:41820
+```bash
+nexuscrew start
 ```
 
-## Termux
+Open `http://localhost:41820` in your browser.
 
-Recommended base packages:
+### Termux (Android)
 
 ```bash
-pkg install nodejs tmux openssh termux-services
+pkg install tmux nodejs
 npm install -g @mmmbuto/nexuscrew
-nexuscrew setup
+nexuscrew init
+nexuscrew start
 ```
 
-The setup wizard can also:
+---
 
-- prepare `Termux:Boot`
-- create and enable the native `runit` service via `termux-services`
-- configure SSH hosts
-- prepare local STT checks for `whisper.cpp`
+## Hosts Registry
 
-## Core Commands
+You can store SSH host definitions for later work:
 
 ```bash
-nexuscrew setup
-nexuscrew start
-nexuscrew stop
-nexuscrew status
-nexuscrew attach
-nexuscrew sessions
-nexuscrew hosts list
-nexuscrew hosts add --name mybox --host example.com --user dag
-nexuscrew stt doctor
+nexuscrew hosts add --name vps1 --host example.com --user user
+nexuscrew hosts add --name vps2 --host 192.168.1.10 --user admin --port 2222
 ```
 
-## How It Works
+Host storage and connectivity tests are available, but the current UI and default session flow are local tmux-first. Treat remote execution as experimental until it is revalidated end-to-end.
 
-```text
-Browser/WebView  <->  Express API  <->  tmux session/windows  <->  AI CLI processes
-                                      |
-                                      +-> local machine
-                                      +-> SSH hosts
-```
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `nexuscrew init` | First-time setup (config, hosts, tmux check) |
+| `nexuscrew start` | Start server |
+| `nexuscrew stop` | Stop server |
+| `nexuscrew status` | Server + tmux + hosts status |
+| `nexuscrew engines` | Discover available AI CLIs and aliases |
+| `nexuscrew sessions` | List tmux sessions |
+| `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 |
 
-Each conversation runs in its own `tmux` window. Local sessions stream from log watchers; remote sessions stream from incremental pane capture.
+---
 
 ## Configuration
 
-Main config:
+Config stored in `~/.nexuscrew/config.json`:
 
-```text
-~/.nexuscrew/config.json
+```json
+{
+  "port": 41820,
+  "logDir": "~/.nexuscrew/logs",
+  "autoDiscovery": true,
+  "preferredShell": "",
+  "extraShellSources": []
+}
 ```
 
-Host registry:
+Hosts stored in `~/.nexuscrew/hosts.json`:
 
-```text
-~/.nexuscrew/hosts.json
+```json
+[
+  { "name": "local", "type": "local", "default": true },
+  { "name": "vps1", "type": "ssh", "host": "example.com", "user": "user", "port": "22" }
+]
 ```
 
-Important defaults include:
+---
 
-- `server.port`
-- `tmuxSession`
-- `hosts.default`
-- `workspaces.default`
-- `stt.provider`
-- `termux.boot_start`
-- `termux.service_enabled`
+## Network
 
-## Authentication
+| Protocol | Default Port | Use Case |
+|----------|--------------|----------|
+| HTTP | `41820` | Local access |
 
-Localhost use is optimized for local device workflows.
+---
 
-For remote or network exposure, review and configure authentication before relying on the instance outside localhost. Do not expose an unreviewed dev setup directly to the public internet.
+## Architecture
+
+```
+Browser ←SSE→ Express Server ←tmux→ active tmux sessions
+                                      ├─ session: claude-work
+                                      ├─ session: codex-debug
+                                      └─ session: qwen-sandbox
+```
+
+Each AI session = one standalone tmux session. Output is piped to log files, parsed by the watcher, and streamed to the UI via SSE.
+
+---
 
 ## Development
 
 ```bash
-git clone https://github.com/DioNanos/nexuscrew
+git clone https://github.com/dionanos/nexuscrew
 cd nexuscrew
 npm install
-npm run build
+cd frontend && npm install && npm run build && cd ..
 npm run dev
 ```
 
-## Related
+---
+
+## Relation to NexusCLI
+
+NexusCrew is a **study branch** inspired by [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli). It shares the same web UI direction but replaces PTY-based process management with tmux-based persistent sessions. The goal is to explore whether tmux provides a simpler, more robust foundation for local AI CLI orchestration and crash recovery.
 
-- [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli) - PTY-based sibling project
+---
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE).