feat: replace tmux/ttyd with built-in PTY multiplexer

Replace the tmux + ttyd terminal architecture with a native PTY
multiplexer built into the server binary. This eliminates two external
dependencies and enables a unified WebSocket protocol for terminal
panes across web, mobile, and CLI.

Key changes:
- Add nomadflow-pty crate with PTY actor, pane manager, snapshot
  system, and binary WS protocol
- Add multiplexed pane WebSocket route and REST pane endpoints
- Add Unix socket listener for local CLI attach
- Replace WebView-based terminal on mobile with bundled HTML +
  typed message protocol bridge
- Migrate web dashboard to xterm.js with shared WS context hook
- Add file tree browser (web + mobile) and syntax highlighting
- Add Basic Auth support with WWW-Authenticate header
- Remove tmux, ttyd, and session picker dependencies
- Add language toggle (en/fr), voice dictation on mobile
- CWD-based agent state tracking (replaces session-ID based)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: fab-uleuh

.github/workflows/build-setup.yml

@@ -7,4 +7,4 @@
   with:
     version: 9
 - name: Build web dashboard
-  run: cd nomadflowcode && pnpm install --frozen-lockfile && npx expo export --platform web
+  run: cd nomadflowcode && pnpm install --frozen-lockfile && pnpm run build:terminal-html && npx expo export --platform web

.github/workflows/release.yml

@@ -136,7 +136,7 @@ jobs:
         with:
           "version": 9
       - name: "Build web dashboard"
-        run: "cd nomadflowcode && pnpm install --frozen-lockfile && npx expo export --platform web"
+        run: "cd nomadflowcode && pnpm install --frozen-lockfile && pnpm run build:terminal-html && npx expo export --platform web"
       - name: Install dist
         run: ${{ matrix.install_dist.run }}
       # Get the dist-manifest

Makefile

@@ -12,7 +12,6 @@ bump:
 	if [ -z "$$VERSION" ]; then echo "Aborted."; exit 1; fi && \
 	echo "Updating to $$VERSION..." && \
 	sed -i '' 's/"version": "[0-9]*\.[0-9]*\.[0-9]*"/"version": "'$$VERSION'"/' nomadflowcode/app.json && \
-	sed -i '' 's/"runtimeVersion": "[0-9]*\.[0-9]*\.[0-9]*"/"runtimeVersion": "'$$VERSION'"/' nomadflowcode/app.json && \
 	sed -i '' 's/"version": "[0-9]*\.[0-9]*\.[0-9]*"/"version": "'$$VERSION'"/' nomadflowcode/package.json && \
 	sed -i '' 's/"version": "[0-9]*\.[0-9]*\.[0-9]*"/"version": "'$$VERSION'"/' docs/package.json && \
 	for f in nomadflow-rs/Cargo.toml \

README.md

@@ -2,7 +2,7 @@
 
 **Code from anywhere — mobile terminal & workflow manager for nomad developers**
 
-NomadFlow is an open-source platform that turns your phone into a full development environment. A single Rust binary manages git worktrees, tmux sessions, and a web terminal, while the React Native app lets you seamlessly switch between projects from your pocket.
+NomadFlow is an open-source platform that turns your phone into a full development environment. A single Rust binary manages git worktrees, Rust-native PTY sessions, and a real-time terminal, while the React Native app lets you seamlessly switch between projects from your pocket.
 
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey.svg)
@@ -12,27 +12,28 @@ NomadFlow is an open-source platform that turns your phone into a full developme
 
 ### Instant Workflow
 - **3-step selection**: Server → Repo → Feature → Terminal ready
-- **Zero manual commands**: environment auto-configured with git worktrees + tmux
+- **Zero manual commands**: environment auto-configured with git worktrees
 - **Branch management**: create, switch, and manage branches from your phone
 
 ### Mobile App
 - **iOS & Android** via React Native / Expo
-- **Integrated terminal** powered by ttyd with WebSocket proxy
-- **Session persistence** via tmux — reconnect where you left off
+- **Integrated terminal** powered by xterm.js with multiplexed binary protocol
+- **Session persistence**: Rust-native PTY multiplexer keeps your terminal sessions alive
 - **Command shortcuts**: quick bar with customizable terminal commands
 - **Deep linking**: connect to a server via `nomadflowcode://connect?url=...&secret=...`
 
 ### Server (Single Rust Binary)
 - **All-in-one**: HTTP API + TUI wizard + daemon mode in one binary
 - **Interactive TUI**: ratatui-based wizard to manage servers, repos, and features
+- **Rust-native PTY**: high-performance terminal multiplexing without external dependencies
 - **Daemon mode**: `nomadflow start` / `nomadflow stop` for background operation
 - **Graceful shutdown**: no orphan processes on Ctrl+C or SIGTERM
 - **Public tunnels**: expose your server via `--public` with automatic subdomain routing
 
 ### Secure Connection
 - **Shared secret authentication**: single secret protects both API and terminal
-- **Bearer + Basic Auth**: API uses Bearer token, terminal uses Basic Auth (same secret)
-- **WebSocket proxy**: terminal WS goes through the server (handles iOS WKWebView auth)
+- **Bearer token**: all communication is secured via Bearer token
+- **Multiplexed WebSocket**: multiple terminal panes over a single secure connection
 
 ## Screenshots
 
@@ -103,11 +104,8 @@ nomadflow web --port 4000
 nomadflow start
 nomadflow stop
 
-# Display tmux and daemon status
+# Display server status
 nomadflow --status
-
-# Attach directly to a tmux window
-nomadflow attach <window>
 ```
 
 ### Configuration
@@ -121,12 +119,6 @@ version = 1
 [paths]
 base_dir = "~/.nomadflowcode"
 
-[tmux]
-session = "nomadflow"
-
-[ttyd]
-port = 7681
-
 [api]
 port = 8080
 
@@ -166,14 +158,14 @@ pnpm run ios    # or: pnpm run android
 │  │  /api/list-repos  /api/list-features  /health     │  │
 │  │  /api/create-feature  /api/switch-feature         │  │
 │  │  /api/clone-repo  /api/list-branches              │  │
-│  │  /terminal (proxy)  /terminal/ws (WS proxy)       │  │
+│  │  /ws/panes (multiplexed WebSocket)                │  │
 │  └──────────────────────┬───────────────────────────┘  │
 │                         │                               │
 │  ┌──────────────────────▼───────────────────────────┐  │
-│  │                    ttyd + tmux                    │  │
+│  │              Rust-native PTY Multiplexer          │  │
 │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐          │  │
-│  │  │ repo:   │  │ repo:   │  │ repo:   │  ...     │  │
-│  │  │feature-a│  │feature-b│  │  main   │          │  │
+│  │  │ Pane:   │  │ Pane:   │  │ Pane:   │  ...     │  │
+│  │  │repo/feat│  │repo/feat│  │  main   │          │  │
 │  │  └────┬────┘  └────┬────┘  └────┬────┘          │  │
 │  └───────┼────────────┼────────────┼────────────────┘  │
 │          ▼            ▼            ▼                    │
@@ -194,7 +186,7 @@ NomadFlowCode/
 ├── nomadflow-rs/               # Rust binary (single binary: server + TUI)
 │   ├── src/main.rs             # Entry point, CLI args, daemon mode
 │   ├── crates/
-│   │   ├── nomadflow-core/     # Config, models, shell, git/tmux/ttyd services
+│   │   ├── nomadflow-core/     # Config, models, shell, git services
 │   │   ├── nomadflow-server/   # Axum HTTP server with auth middleware
 │   │   ├── nomadflow-tui/      # Ratatui TUI wizard
 │   │   ├── nomadflow-relay/    # Standalone relay server for tunnel routing
@@ -209,8 +201,6 @@ NomadFlowCode/
 
 ### Server
 - macOS or Linux
-- **tmux** (terminal multiplexer)
-- **ttyd** (web terminal)
 - **Git** with worktree support
 
 ### Mobile
@@ -224,7 +214,7 @@ NomadFlowCode/
 
 NomadFlow uses a single shared secret that protects both:
 - **REST API**: via Bearer token (`Authorization: Bearer <secret>`)
-- **Terminal**: via Basic Auth (user: `nomadflow`, password: `<secret>`)
+- **Terminal**: via token in WebSocket upgrade query param
 
 **Setup:**
 
@@ -261,8 +251,9 @@ MIT License — see [LICENSE](LICENSE) for details.
 
 ## Acknowledgements
 
-- [ttyd](https://github.com/tsl0922/ttyd) — Web terminal
-- [tmux](https://github.com/tmux/tmux) — Terminal multiplexer
+- [xterm.js](https://xtermjs.org/) — Web terminal frontend
+- [pty-process](https://github.com/alacritty/pty-process) — Rust PTY handling
+- [alacritty_terminal](https://github.com/alacritty/alacritty) — Terminal state machine
 - [axum](https://github.com/tokio-rs/axum) — Rust web framework
 - [ratatui](https://github.com/ratatui/ratatui) — Terminal UI framework
 - [bore](https://github.com/ekzhang/bore) — TCP tunnel

docs/app/(home)/page.tsx

@@ -43,7 +43,7 @@ export default function HomePage() {
             NomadFlow
           </h1>
           <p className="text-base lg:text-lg text-fd-muted-foreground mb-6 lg:mb-8 text-center">
-            Manage git worktrees and tmux sessions from your phone. A single Rust
+            Manage git worktrees and PTY sessions from your phone. A single Rust
             binary that runs on your server, paired with a mobile app for on-the-go
             development.
           </p>
@@ -110,7 +110,7 @@ export default function HomePage() {
           </div>
           <h3 className="font-semibold mb-2">Single Binary</h3>
           <p className="text-sm text-fd-muted-foreground">
-            One Rust binary ships the HTTP server, WebSocket proxy, and TUI
+            One Rust binary ships the HTTP server, PTY multiplexer, and TUI
             wizard. No Node.js, no Docker required.
           </p>
         </div>
@@ -120,8 +120,8 @@ export default function HomePage() {
           </div>
           <h3 className="font-semibold mb-2">Mobile Terminal</h3>
           <p className="text-sm text-fd-muted-foreground">
-            Full terminal access from your phone via ttyd. Browse repos, switch
-            features, and code anywhere.
+            Full terminal access from your phone via native PTY. Browse repos,
+            switch features, and code anywhere.
           </p>
         </div>
         <div className="border border-fd-border rounded-xl p-5 bg-fd-card transition-colors hover:border-[#5336E2]/40">
@@ -130,8 +130,8 @@ export default function HomePage() {
           </div>
           <h3 className="font-semibold mb-2">Git Worktrees</h3>
           <p className="text-sm text-fd-muted-foreground">
-            Each feature branch gets its own worktree and tmux window. Switch
-            context instantly, no stashing needed.
+            Each feature branch gets its own worktree and dedicated PTY pane.
+            Switch context instantly, no stashing needed.
           </p>
         </div>
       </div>

docs/app/(home)/privacy/page.tsx

@@ -17,7 +17,7 @@ export default function PrivacyPage() {
       <p>
         NomadFlowCode (&quot;we&quot;, &quot;our&quot;, or &quot;the app&quot;)
         is a mobile application that connects to your own self-hosted server to
-        manage git worktrees, tmux sessions, and terminal access. This privacy
+        manage git worktrees, PTY sessions, and terminal access. This privacy
         policy explains how we handle your data.
       </p>
 

docs/app/(home)/terms/page.tsx

@@ -23,7 +23,7 @@ export default function TermsPage() {
       <h2>2. Description of Service</h2>
       <p>
         NomadFlowCode is a mobile application that allows you to connect to your
-        own self-hosted servers to manage git worktrees, tmux sessions, and
+        own self-hosted servers to manage git worktrees, PTY sessions, and
         access terminal sessions remotely. The app acts as a client and requires
         you to set up and maintain your own server infrastructure.
       </p>

docs/app/layout.tsx

@@ -13,15 +13,15 @@ export const metadata: Metadata = {
     template: '%s | NomadFlow',
   },
   description:
-    'Manage git worktrees and tmux sessions from your phone. A single Rust binary paired with a mobile app for on-the-go development.',
+    'Manage git worktrees and PTY sessions from your phone. A single Rust binary paired with a mobile app for on-the-go development.',
   icons: {
     icon: '/favicon.ico',
     apple: '/apple-touch-icon.png',
   },
   openGraph: {
     title: 'NomadFlow',
     description:
-      'Manage git worktrees and tmux sessions from your phone.',
+      'Manage git worktrees and PTY sessions from your phone.',
     siteName: 'NomadFlow',
     type: 'website',
   },

docs/content/docs/cli.mdx

@@ -19,7 +19,7 @@ nomadflow [OPTIONS] [COMMAND]
 nomadflow
 ```
 
-Starts the HTTP server in the background, then launches the **TUI wizard**. When the TUI exits, the server is gracefully shut down (ttyd is cleanly stopped, no orphan processes). If the TUI returns a tmux session to attach to, `tmux attach-session` is executed automatically.
+Starts the HTTP server in the background, then launches the **TUI wizard**. When the TUI exits, the server is gracefully shut down. The TUI allows managing PTY sessions and worktrees interactively.
 
 ### `serve`
 
@@ -35,7 +35,7 @@ Runs the HTTP server in the **foreground** with full tracing/logging enabled. Us
 | `--host <address>` | Override the displayed address (IP or domain name) for QR code and URL. |
 | `--port <port>` | Override the API server port (default: from `config.toml`, fallback `8080`). |
 
-The server handles **graceful shutdown**: on `Ctrl+C` or `SIGTERM`, it stops accepting new connections, completes in-flight requests, then cleanly stops the ttyd subprocess.
+The server handles **graceful shutdown**: on `Ctrl+C` or `SIGTERM`, it stops accepting new connections, completes in-flight requests, and cleanly shuts down all managed PTY processes.
 
 ### `start`
 
@@ -61,7 +61,7 @@ Stops the background daemon. Reads the PID file, sends `SIGTERM` to trigger grac
 nomadflow web [--port <port>]
 ```
 
-Starts a lightweight HTTP server that serves the **web dashboard** (static files), then opens it in your default browser. This is a standalone server — no tmux, no ttyd, no auth required.
+Starts a lightweight HTTP server that serves the **web dashboard** (static files), then opens it in your default browser. This is a standalone server — no auth required.
 
 | Option | Description |
 |--------|-------------|
@@ -96,33 +96,39 @@ Removes a previously linked repository from NomadFlow. If no name is given, show
 nomadflow --status
 ```
 
-Displays the current **daemon status** (running/not running, PID) and the **tmux session status** (windows, features), then exits.
+Displays the current **daemon status** (running/not running, PID) and the **active PTY panes** (repo, worktree, agent type), then exits.
 
 ### `attach`
 
 ```bash
-nomadflow attach [<window>]
+nomadflow attach [--pane <id>]
 ```
 
-Attaches to an existing tmux window (no server needed). If a window name is provided (e.g. `omstudio:my-feature`), attaches directly. Otherwise, shows an interactive picker listing all windows with their current process status.
+Attaches to a server-managed PTY pane via a Unix socket. This provides a native terminal experience directly in your CLI.
+
+| Option | Description |
+|--------|-------------|
+| `--pane <id>` | (Optional) The numeric ID of the pane to attach to. If omitted, shows an interactive picker. |
 
 ## TUI wizard
 
 When running in default mode, the TUI provides an interactive terminal interface with the following screens:
 
+- **Session picker** — quick resume of active PTY sessions
 - **Server list** — manage remote server connections
 - **Add server** — multi-step form: name, URL, token, confirmation
 - **Repository browser** — list and select repos
 - **Feature browser** — list, create, and switch feature branches
 
-The TUI is built with [ratatui](https://ratatui.rs) and exits cleanly, handing off to `tmux attach` if a session was selected.
+The TUI is built with [ratatui](https://ratatui.rs) and exits cleanly.
 
 ## Daemon files
 
 | File | Description |
 |------|-------------|
 | `~/.nomadflowcode/nomadflow.pid` | PID of the running daemon process |
 | `~/.nomadflowcode/nomadflow.log` | Stdout/stderr of the daemon process |
+| `~/.nomadflowcode/nomadflow.sock` | Unix socket for local CLI `attach` |
 
 ## Environment variables
 

docs/content/docs/concepts.mdx

@@ -1,19 +1,20 @@
 ---
 title: Concepts
-description: Architecture, git worktrees, tmux sessions, and how they fit together.
+description: Architecture, git worktrees, PTY sessions, and how they fit together.
 ---
 
 ## Architecture
 
-NomadFlowCode is built as a Rust workspace with three crates:
+NomadFlowCode is built as a Rust workspace with four core crates:
 
 | Crate | Role |
 |-------|------|
-| `nomadflow-core` | Configuration, data models, shell utilities, git/tmux/ttyd services |
-| `nomadflow-server` | Axum HTTP server with auth middleware and WebSocket proxy |
+| `nomadflow-core` | Configuration, data models, shell utilities, git services |
+| `nomadflow-pty` | Binary protocol definitions and PTY handling logic |
+| `nomadflow-server` | Axum HTTP server, authentication, and multiplexed WebSocket |
 | `nomadflow-tui` | Ratatui TUI wizard for interactive setup |
 
-All three compile into a single `nomadflow` binary.
+All crates compile into a single `nomadflow` binary.
 
 ## Git worktrees
 
@@ -31,22 +32,22 @@ Instead of switching branches in a single working directory, NomadFlowCode uses
 
 This means you can have multiple features checked out simultaneously without stashing or losing state.
 
-## Tmux sessions
+## Terminal sessions (PTY)
 
-NomadFlowCode manages a single tmux session (default: `nomadflow`). Each feature gets a dedicated tmux window named `{repo}:{feature}` to avoid collisions across repositories.
+NomadFlowCode uses a native Rust PTY multiplexer instead of external tools like tmux. Each terminal session runs as a **PaneActor** managed by a **PaneManager**.
 
 When you switch features, the server:
 1. Creates a worktree (if needed)
-2. Creates or selects the tmux window
-3. Changes to the worktree directory
+2. Spawns a PTY process in that worktree directory
+3. Manages the terminal state (ANSI parsing, buffer snapshots) in memory
 
-## ttyd and WebSocket proxy
+## Multiplexed WebSocket
 
-[ttyd](https://github.com/tsl0922/ttyd) exposes the tmux session as a web terminal on port 7681. The mobile app loads the ttyd HTML page directly for HTTP content.
-
-For WebSocket connections, iOS WKWebView does not send Basic Auth headers on WebSocket upgrades. To solve this, the NomadFlowCode server provides a WebSocket proxy at `/terminal/ws` that:
-1. Authenticates via a `token` query parameter
-2. Forwards the WebSocket connection to ttyd with proper Basic Auth headers
+All terminal communication happens over a single WebSocket connection at `/ws/panes`. This protocol supports:
+- **Multiplexing** — multiple terminal panes over one connection
+- **Binary framing** — efficient data transfer with minimal overhead
+- **Buffer snapshots** — instant terminal state resume on reconnection
+- **Real-time resizing** — automatic adjustment to mobile/web screen sizes
 
 ## Authentication flow
 
@@ -56,10 +57,8 @@ Mobile App
   ├─ API requests ──► Bearer token in Authorization header
   │                    Server validates against auth.secret
   │
-  ├─ ttyd HTML ──────► Loaded directly (basicAuthCredential in URL)
-  │
-  └─ Terminal WS ───► /terminal/ws?token=<secret>
-                       Server proxies to ttyd with Basic Auth
+  └─ Terminal WS ───► /ws/panes?token=<secret>
+                       Multiplexed binary protocol
 ```
 
 ## File structure
@@ -69,4 +68,5 @@ Mobile App
   config.toml       # server configuration
   repos/            # bare git clones
   worktrees/        # checked-out worktrees per feature
+  sessions/         # agent state tracking data
 ```