CLI and TUI interoperability compatibility suite #14

Status (updated at the v0.16 feature freeze)

Implemented on the v0.16 branch (PR #303): deterministic fixtures for finite/noisy/streaming commands, canonical and raw interactive programs, alternate screen, agent-style and nested-PTY behavior, and optional real tmux / GNU screen tests including mouse-enabled detach/reattach.

Remaining scope (ongoing by nature): physical runs of the listed CLI/TUI categories in real hosts, and new compatibility fixtures as defects are found. See docs/testing/v010-compatibility.md.

Goal

Establish and execute a comprehensive compatibility suite validating NMSh interoperability with the major categories of CLI and TUI programs.

Why

NMSh should interoperate with useful CLI tools, not replace or break them. This issue tracks ongoing compatibility work and defines the categories that must be validated.

Scope

Ordinary CLI — git, gh, ls, eza, brew, npm, pnpm

• Expected: structured execution presentation

Shell augmentation — zoxide, Atuin

• Expected: preserve their useful functionality; NMSh integrates rather than unnecessarily recreates

Noisy finite commands — npm test, xcodebuild, brew update

• Expected: FOLDED mode with summary

Streaming commands — ping, tail -f, vite, npm run dev

• Expected: LIVE presentation (large output volume does not mean FOLDED — streaming = LIVE)

Interactive TUI — nano, vim, fzf, lazygit, btop, less

• Expected: PASSTHROUGH intact

Terminal multiplexers — tmux

• Expected: strong compatibility; do not assume ordinary command rendering is appropriate inside nested terminal environments
• Mouse mode: verify mouse capture and selection work correctly when NMSh runs inside tmux with mouse mode enabled
• Nested mouse capture: document expected behavior
• Alternate screen: verify correct behavior inside tmux

Agent CLIs — Claude Code, Codex, OpenCode, Aider

• Expected: PASSTHROUGH and clean exit; agent CLIs own their own interfaces

Terminal host matrix

• Ghostty: primary; mouse enabled; enhanced keyboard
• Terminal.app: baseline; keyboard-only mouse path must work
• Mouse-enabled hosts: verify click-to-expand and hover states
• Keyboard-only scenarios: verify all interactive actions reachable without mouse

Core principle

NMSh does not replace useful CLI functionality:

• gh still handles GitHub
• zoxide still handles intelligent directory navigation
• Atuin can still handle advanced history
• tmux still multiplexes
• nano/vim still edit
• Agent CLIs still own their own interfaces

NMSh provides the surrounding interaction and presentation layer.

Non-goals

• Reimplementing functionality of any listed tool
• 100% compatibility with every possible CLI tool

Acceptance criteria

• All listed categories have been tested in a real NMSh session
• No tool in any category is broken or produces rendering corruption
• tmux nesting behavior is documented and tested (including mouse mode)
• zoxide and Atuin integrations remain functional
• All mouse-dependent interactive behaviors have verified keyboard alternatives

Human verification

This issue requires manual testing across all tool categories in a real NMSh session in Ghostty and macOS Terminal.

Dependencies

Benefits from v0.2.0 (#1–#6) being complete for accurate presentation testing.

Rough effort

Ongoing — initial pass 2–3 days