Concepts

Architecture

NomadFlowCode is built as a Rust workspace with three crates:

All three compile into a single nomadflow binary.

Git worktrees

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

~/.nomadflowcode/
  repos/           # bare clones
    my-project/
  worktrees/        # one directory per feature
    my-project/
      feature-a/
      feature-b/

This means you can have multiple features checked out simultaneously without stashing or losing state.

Tmux sessions

NomadFlowCode manages a single tmux session (default: nomadflow). Each feature gets a dedicated tmux window named {repo}:{feature} to avoid collisions across repositories.

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

ttyd and WebSocket proxy

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

Authentication flow

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

File structure

~/.nomadflowcode/
  config.toml       # server configuration
  repos/            # bare git clones
  worktrees/        # checked-out worktrees per feature