Contributing

NomadFlowCode is open source and welcomes contributions. This guide covers the monorepo structure, development setup, and conventions.

Monorepo structure

NomadFlowCode/
  nomadflow-rs/        # Rust binary (server + TUI)
    crates/
      nomadflow-core/    # config, models, services
      nomadflow-pty/     # native PTY spawning and pane management
      nomadflow-ws/      # WebSocket protocol and binary framing
      nomadflow-server/  # axum HTTP server
      nomadflow-tui/     # ratatui TUI wizard
      nomadflow-relay/   # standalone relay server for tunnel routing
    src/main.rs          # binary entry point
  nomadflowcode/       # React Native/Expo mobile app
  docs/                # Documentation site (fumadocs/Next.js)

Development setup

Rust (server + TUI)

cd nomadflow-rs
cargo build
cargo test

Requirements: Rust toolchain, git.

Mobile app

cd nomadflowcode
pnpm install
npx expo run:ios    # or run:android

Requirements: Node.js, pnpm, Expo CLI, Xcode (iOS) or Android Studio.

Documentation

cd docs
pnpm install
pnpm dev

The docs site runs at http://localhost:3000.

Conventions

JSON field naming

All API request/response bodies use camelCase field names. Rust structs use #[serde(rename_all = "camelCase")] to handle the conversion.

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Feature {
    pub worktree_path: String,  // serialized as "worktreePath"
    pub is_active: bool,        // serialized as "isActive"
}

Path comparison

On macOS, /tmp is a symlink to /private/tmp. Always use canonicalize() when comparing paths in tests or runtime logic.

Native PTY testing

The nomadflow-pty crate handles terminal state. When writing tests for PTY features, use the PaneManager and PaneActor abstractions. Avoid spawning real PTY processes in unit tests unless testing the raw PTY spawning logic.

Pane identifying

Panes are identified by a combination of repo and worktree fields rather than a single string, ensuring robust identification across multiple repositories.

Pull request guidelines

1. Fork the repository and create a feature branch.
2. Write tests for new functionality.
3. Run the test suite — cargo test in nomadflow-rs/.
4. Keep commits focused — one logical change per commit.
5. Update documentation if your change affects the API, CLI, or configuration.