@mmmbuto/nexuscrew 0.1.0-beta.1 → 0.2.1

package/README.md

@@ -1,175 +1,122 @@
-## Overview
+# NexusCrew
 
-NexusCrew is a **tmux-based** AI cockpit that orchestrates Claude Code, Codex CLI, Gemini CLI, and Qwen Code through persistent tmux sessions.
+Mobile-first `tmux` cockpit for local and remote AI CLI 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.
+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.
 
-> **Status**: Beta — experimental, API may change
+## Highlights
 
----
-
-## 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
-
----
+- 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
 
 ## Install
 
 ```bash
 npm install -g @mmmbuto/nexuscrew
+nexuscrew setup
+nexuscrew start
 ```
 
-Then initialize:
-
-```bash
-nexuscrew init
-```
+`nexuscrew start` runs the server in background, waits for health, and can open the browser for you.
 
-And start:
+Default URL:
 
-```bash
-nexuscrew start
+```text
+http://localhost:41820
 ```
 
-Open `http://localhost:41820` in your browser.
+## Termux
 
-### Termux (Android)
+Recommended base packages:
 
 ```bash
-pkg install tmux nodejs
+pkg install nodejs tmux openssh termux-services
 npm install -g @mmmbuto/nexuscrew
-nexuscrew init
-nexuscrew start
+nexuscrew setup
 ```
 
----
+The setup wizard can also:
 
-## Remote Hosts
+- prepare `Termux:Boot`
+- create and enable the native `runit` service via `termux-services`
+- configure SSH hosts
+- prepare local STT checks for `whisper.cpp`
 
-Add SSH hosts to manage tmux sessions on remote machines:
+## Core Commands
 
 ```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
+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
 ```
 
-Hosts appear in the UI's model selector. Sessions created on a remote host open a tmux window there via SSH.
+## How It Works
 
----
-
-## 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 |
+```text
+Browser/WebView  <->  Express API  <->  tmux session/windows  <->  AI CLI processes
+                                      |
+                                      +-> local machine
+                                      +-> SSH hosts
+```
 
----
+Each conversation runs in its own `tmux` window. Local sessions stream from log watchers; remote sessions stream from incremental pane capture.
 
 ## Configuration
 
-Config stored in `~/.nexuscrew/config.json`:
+Main config:
 
-```json
-{
-  "port": 41820,
-  "tmuxSession": "nexuscrew",
-  "logDir": "~/.nexuscrew/logs",
-  "autoDiscovery": true,
-  "providersPath": "~/Dev/providers.zsh"
-}
+```text
+~/.nexuscrew/config.json
 ```
 
-Hosts stored in `~/.nexuscrew/hosts.json`:
+Host registry:
 
-```json
-[
-  { "name": "local", "type": "local", "default": true },
-  { "name": "vps1", "type": "ssh", "host": "example.com", "user": "user", "port": "22" }
-]
+```text
+~/.nexuscrew/hosts.json
 ```
 
----
+Important defaults include:
 
-## Network
+- `server.port`
+- `tmuxSession`
+- `hosts.default`
+- `workspaces.default`
+- `stt.provider`
+- `termux.boot_start`
+- `termux.service_enabled`
 
-| Protocol | Default Port | Use Case |
-|----------|--------------|----------|
-| HTTP | `41820` | Local access |
+## Authentication
 
----
+Localhost use is optimized for local device workflows.
 
-## 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.
-
----
+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.
 
 ## Development
 
 ```bash
-git clone https://github.com/dionanos/nexuscrew
+git clone https://github.com/DioNanos/nexuscrew
 cd nexuscrew
 npm install
-cd frontend && npm install && npm run build && cd ..
+npm run build
 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.
+## Related
 
----
+- [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli) - PTY-based sibling project
 
 ## License
 
-MIT License. See [LICENSE](LICENSE).
+MIT