npm package: @mmmbuto/nexuscrew
Description: tmux-based AI cockpit for real active sessions and launcher discovery across Termux, Linux, and macOS
Author: DioNanos
Latest version: 0.2.5

# NexusCrew

[![npm](https://img.shields.io/npm/v/@mmmbuto/nexuscrew?style=flat-square&logo=npm)](https://www.npmjs.org/package/@mmmbuto/nexuscrew)

NexusCrew is a tmux-first AI cockpit for Claude Code, Codex CLI, Gemini CLI, and Qwen Code.

It is built around one core rule: chat targets real tmux sessions that already exist, or new tmux sessions that are created explicitly from launchers detected on the current machine.

---

## About

- Runtime model: active tmux sessions + explicit tmux creation
- Launcher discovery: runtime-driven, shell-agnostic, user-agnostic
- Primary verified environment: Termux on Android
- Linux/macOS: supported by design, not yet fully revalidated in the current cycle
- Remote hosts: registry and connectivity exist, but end-to-end remote session flow is still experimental

## Project Scope

### What It Does

- Lists real active tmux sessions on the host
- Lets the UI attach chat to an existing tmux session
- Detects runnable launchers from:
  - PATH binaries
  - live shell aliases/functions
  - generic shell config fallbacks
- Creates a new standalone tmux session only when you explicitly ask for it
- Stores conversation state locally in SQLite
- Streams output back through SSE

### What It Does Not Do

- It does not create hidden tmux master sessions
- It does not keep a hardcoded list of AI models or wrappers
- It does not assume a user-specific home like `/home/dag`
- It does not treat shell-file-only detections as runnable unless the active shell confirms them

---

## Installation

### Quick Start

Install:

```bash
npm install -g @mmmbuto/nexuscrew
```

Initialize local config:

```bash
nexuscrew init
```

Start the server:

```bash
nexuscrew start
```

Open:

```text
http://localhost:41820
```

### Termux Quick Start

```bash
pkg install tmux nodejs
npm install -g @mmmbuto/nexuscrew
nexuscrew init
nexuscrew start
```

Notes:

- the package uses a Termux-compatible SQLite dependency path during install
- detailed install notes live in [docs/INSTALLATION.md](docs/INSTALLATION.md)

---

## Runtime Model

NexusCrew now works with standalone tmux sessions.

That means:

- one AI runtime = one tmux session
- chat sends to an existing tmux session
- new tmux sessions are created explicitly from a detected launcher
- session output is piped to log files and watched by the server

Architecture:

```text
Browser <--SSE--> Express server <--tmux--> active tmux sessions
                                           |- claude-work
                                           |- codex-debug
                                           `- qwen-sandbox
```

---

## Launcher Discovery

Discovery is environment-agnostic and shell-agnostic.

Sources, in order:

1. live shell introspection
2. generic shell files such as `.zshrc`, `.bashrc`, `.profile`
3. PATH binaries

Detection families are inferred from what is actually present, not from a static product catalog.

Current launcher families:

- `claude`
- `codex`
- `gemini`
- `qwen`
- `custom`

Important distinction:

- `runnable: true` means the launcher is valid for explicit tmux creation now
- `runnable: false` means it was detected from shell config metadata only

---

## Commands

| Command | Description |
|---------|-------------|
| `nexuscrew init` | Create config, hosts file, and logs directory |
| `nexuscrew start` | Start the web server |
| `nexuscrew stop` | Stop the server |
| `nexuscrew status` | Show server, tmux, and host status |
| `nexuscrew sessions` | List active tmux sessions |
| `nexuscrew attach -s <name>` | Attach to a tmux session directly |
| `nexuscrew engines` | Print discovered launchers |
| `nexuscrew config --list` | Show config |
| `nexuscrew config --set key=value` | Update config |
| `nexuscrew hosts list` | List stored hosts |
| `nexuscrew hosts add ...` | Add an SSH host entry |
| `nexuscrew hosts remove ...` | Remove an SSH host entry |

---

## Documentation

- [Installation Guide](docs/INSTALLATION.md)
- [Configuration Guide](docs/CONFIGURATION.md)
- [Current State](docs/CURRENT_STATE.md)
- [Changelog](CHANGELOG.md)

---

## Support Matrix

| Area | State |
|------|----------------|
| Local tmux session listing | Verified |
| Explicit local tmux creation | Verified |
| Runtime launcher discovery | Verified |
| Bucketed launcher discovery | Verified |
| Shell-file-only launcher gating | Verified |
| Host-scoped tmux/session selection | Implemented |
| SSE send flow | Improved, basic smoke tested |
| Interrupt flow | Improved, not deeply stress-tested |
| Remote host registry | Present |
| Remote host execution | Implemented, pending live smoke |

---

## Development

```bash
git clone https://github.com/DioNanos/nexuscrew
cd nexuscrew
npm install
npm run build
npm run dev
```

---

## Known Gaps

- remote tmux workflows still need live multi-host smoke before being advertised as stable
- send/interrupt should still be stress-tested against long-running CLI pauses

---

## License

MIT. See `LICENSE`.