## 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** so sessions survive server restarts and can be accessed directly from the terminal.

> **Status**: Beta — experimental, API may change

> **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
```

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
```

---

## Hosts Registry

You can store SSH host definitions for later work:

```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
```

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.

---

## 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 |

---

## Configuration

Config stored in `~/.nexuscrew/config.json`:

```json
{
  "port": 41820,
  "logDir": "~/.nexuscrew/logs",
  "autoDiscovery": true,
  "preferredShell": "",
  "extraShellSources": []
}
```

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→ 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
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 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.

---

## License

MIT License. See [LICENSE](LICENSE).
