Rust TUI for parallel command execution

A terminal user interface for par, a parallel command executor. Monitor running tasks, send signals, view output—all from an interactive TUI.

Problem

par runs commands in parallel, but monitoring them means juggling terminal windows or parsing log files. A TUI provides real-time visibility into what’s running, what’s queued, and what failed.

Architecture

Client Library First: The project builds a robust async client library before the UI. The library is a facade over the par CLI:

┌─────────────────────────────────────────────────────────┐
│                    ParClient (Facade)                    │
├─────────────────────────────────────────────────────────┤
│  list_tasks()  │  send_event()  │  get_workspace()      │
└────────┬───────┴────────┬───────┴────────┬──────────────┘
         │                │                │
         ▼                ▼                ▼
   ┌──────────┐    ┌──────────────┐   ┌──────────────┐
   │  State   │    │   Commands   │   │    Cache     │
   │  Reader  │    │   Executor   │   │   (TTL)      │
   └──────────┘    └──────────────┘   └──────────────┘
         │                │
         ▼                ▼
   ~/.local/share/    par send
   par/global_state   par list

Read Path: Parse global_state.json for task/workspace info Write Path: Execute par subcommands for actions

Key Patterns

Anti-Corruption Layer: Internal models (models.rs) are isolated from raw JSON structures (state.rs). The library stays resilient when par changes its data format.

Lenient Parsing: All optional fields use #[serde(default)]. Unknown JSON keys are ignored. The client degrades gracefully.

Thread-Safe Caching: Arc<RwLock<>> with TTL-based expiration. Sub-10ms response times for cache hits.

Retry with Backoff: Exponential backoff (100ms → 200ms → 400ms) for transient failures. Errors classified as retry-able or permanent.

Current Status

Constitutional Principles

The project follows five non-negotiable principles:

1. API-First: All TUI interactions bound to par CLI contracts
2. Domain-First: Explicit, testable domain models before rendering
3. Interface-First: UI components defined with inputs/outputs/state transitions
4. Test-First: TDD strictly enforced (red-green-refactor)
5. Infrastructure-First: Cross-platform support from day one

Why This Exists

Building TUIs properly means building the data layer first. This project is as much about the methodology—spec-driven development, constitutional principles, TDD—as it is about the final product. The client library is a reference implementation for wrapping CLI tools in Rust.