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:

npm install -g @mmmbuto/nexuscrew

Initialize local config:

nexuscrew init

Start the server:

nexuscrew start

Open:

http://localhost:41820

Termux Quick Start

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

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:

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
• Configuration Guide
• Current State
• Changelog

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

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.