Concepts

Architecture

NomadFlowCode is built as a Rust workspace with six crates:

Crate	Role
`nomadflow-core`	Configuration, data models, shell utilities, git services
`nomadflow-pty`	Native PTY spawning, pane management, and terminal state
`nomadflow-ws`	WebSocket protocol definitions and binary framing
`nomadflow-server`	Axum HTTP server, authentication, and API routes
`nomadflow-tui`	Ratatui TUI wizard for interactive setup
`nomadflow-relay`	Standalone relay server for public tunnel subdomain routing

All crates (except nomadflow-relay) compile into a single nomadflow binary. The relay is a separate binary deployed on a VPS.

Git worktrees

Instead of switching branches in a single working directory, NomadFlowCode uses git worktrees. Each feature branch gets its own directory:

~/.nomadflowcode/
  repos/           # symlinks (via `link`) or cloned repositories
    my-project/
  worktrees/        # one directory per feature
    my-project/
      feature-a/
      feature-b/

Repositories appear in repos/ either as symlinks to existing projects (created by nomadflow link) or as cloned repositories (created via the clone-repo API). This means you can have multiple features checked out simultaneously without stashing or losing state.

Terminal sessions (PTY)

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:

Creates a worktree (if needed)
Spawns a PTY process in that worktree directory
Manages the terminal state (ANSI parsing, buffer snapshots) in memory

Multiplexed WebSocket

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

Mobile App
  │
  ├─ API requests ──► Bearer token OR Basic Auth in Authorization header
  │                    Server validates against auth.secret
  │
  └─ Terminal WS ───► /ws/panes with Sec-WebSocket-Protocol: bearer.<secret>
                       Multiplexed binary protocol

File structure

~/.nomadflowcode/
  config.toml       # server configuration (auto-created by setup wizard)
  repos/            # symlinks or cloned repositories
  worktrees/        # checked-out worktrees per feature
  sessions/         # agent state tracking data