Nexus

Your agent workspace, anywhere.

A gateway that connects your browser to tmux sessions running AI coding agents. Desktop gets a full terminal. Phone gets a chat interface.

Nexus is a three-tier agent orchestration system:

Browser / Phone  ──→  Gateway  ──→  tmux Client
(UI)                  (route)        (agent runner)

The gateway routes messages between browser UIs and tmux client agents. Each tmux client manages local tmux sessions where AI coding agents (Claude Code, Codex, Gemini CLI, etc.) run. You interact with them through a browser — xterm.js on desktop, chat bubbles on mobile.

┌─────────────────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│  Browser                 │     │  Gateway (:3879)  │     │  tmux Client          │
│  ┌────────────────────┐  │     │                   │     │  ┌─────────────────┐  │
│  │ Desktop: xterm.js  │──┼─────┼── REST + WS ──────┼─────┼──│ tmux session 1  │  │
│  │ Mobile: chat view  │  │     │  • client registry │     │  │ (Claude Code)   │  │
│  └────────────────────┘  │     │  • session routing │     │  ├─────────────────┤  │
└─────────────────────────┘     │  • output buffering │     │  │ tmux session 2  │  │
                                └──────────────────┘     │  │ (Codex)         │  │
                                                          │  └─────────────────┘  │
                                                          └──────────────────────┘

• Gateway — central routing hub. REST API + WebSocket. Zero knowledge of user code.
• tmux Client — runs on the machine with your code and agent CLIs. Manages tmux sessions.
• Browser — single HTML page. Auto-detects desktop vs mobile, renders xterm.js or chat UI.

# 1. Start the gateway
go run ./cmd/nexusd
# → http://localhost:3879

# 2. Start a tmux client agent
go run ./cmd/nexus-agent

# 3. Open the browser
open http://localhost:3879

Or via Make:

make test          # 16 tests
make build         # → bin/nexusd, bin/nexus-agent
make run-gateway   # → :3879
make run-agent     # connects to :3879

# Self-hosted: gateway on your cloud VM
ssh your-server
git clone https://github.com/zzszmyf/nexus
cd nexus && go run ./cmd/nexusd -addr :443
# Then connect a tmux agent from any machine:
go run ./cmd/nexus-agent -gateway wss://your-server/ws/client

# Or just run everything locally:
# Terminal 1: go run ./cmd/nexusd
# Terminal 2: go run ./cmd/nexus-agent
# Browser:    http://localhost:3879

go test ./...        # run all tests
go build ./cmd/...   # build binaries

Requirements: Go ≥1.24, tmux (on agent machines).

Open the same URL on your phone. The UI auto-switches to chat mode:

• ☰ → sidebar with sessions and create form
• Chat bubbles → agent output (ANSI stripped, clean text)
• Text input → send messages to the agent
• Typing indicator → shows when waiting for output

Most AI coding agents are CLI tools. You need a terminal to use them. Nexus gives you that terminal in a browser — plus a chat interface for your phone.

• tmux handles terminal multiplexing — battle-tested, no custom PTY code
• Go for the gateway and client — single static binary, zero runtime dependencies
• Browser as the UI — zero install, works on desktop and phone
• Three-tier architecture — gateway never touches your code, tmux sessions run wherever you want

This project was born out of conversations with CJ 老师, whose insights shaped the three-tier architecture, the tmux-as-backend approach, and the mobile chat paradigm. The core idea — "把云上的 tmux 扔到一个 gateway, 本地浏览器通过 API 请求 gateway 渲染" — came directly from those discussions.

CJ 老师's key contributions to the design:

• tmux as the terminal backend — let tmux handle session management and terminal multiplexing. A single insight that keeps the entire system free of native dependencies.
• Gateway decoupling — the gateway routes messages but never sees user code. Code stays where the tmux client runs.
• Mobile as chat, not terminal — phones shouldn't try to render a full terminal emulator. A chat-style interface with message bubbles and a simple input bar is the right UX for mobile AI agent interaction.
• Client–gateway terminology — the tmux client is a thin worker that manages tmux sessions and talks to the gateway. The gateway is the central hub. The browser is just one possible UI.
• Ubuntu as the deployment target — when the agent runtime is cloud-native, you target one platform and the browser handles everything else.

Thank you, CJ 老师.

Apache-2.0