r3bl-open-core

██████╗  ██████╗  ██████╗
██╔══██╗██╔═══██╗██╔════╝
██████╔╝██║   ██║██║
██╔══██╗██║   ██║██║
██║  ██║╚██████╔╝╚██████╗
╚═╝  ╚═╝ ╚═════╝  ╚═════╝

• r3bl-open-core
• Why R3BL TUI?
  • The Problem with Existing Solutions
  • The R3BL Solution: Web and Desktop App Inspired Terminal Apps
  • Built-from-Scratch Primitives
  • Advanced Rendering & Styling
  • Rich Component Ecosystem
• Welcome to the monorepo and workspace
• This workspace contains crates for building TUI, CLI, TTY apps
  • Full TUI (async, raw mode, full screen) for immersive TUI apps
  • Partial TUI (async, partial raw mode, async readline) for choice based user interaction
  • Partial TUI (async, partial raw mode, async readline) for async REPL
  • Terminal multiplexer
• Power via composition
  • Main library crate
  • Main binary crate
• Interactive git workflows made easy.
• Beautiful Markdown editor with advanced rendering and editing features.
• Project Task Organization
  • Task Management Files
  • Task File Format
• Implementation Plan
• Step 0: Do Something [STATUS]
  • Step 0.0: Do Subtask [STATUS]
  • Step 0.1: Do Another Subtask [STATUS]
• Step 1: Do Something Else [STATUS]
  • Task Workflow Commands
  • Workflow Connection
  • Development Tools Integration
• Documentation and Planning
  • Documentation Philosophy
  • Release and Contribution Guides
  • Technical Design Documents
• Learn how these crates are built, provide feedback
• Quick Start
  • Automated Setup (Recommended)
• Run the bootstrap script
  • Manual Setup
• Install fish and fzf (via package manager)
• Ubuntu/Debian: sudo apt install fish fzf
• macOS: brew install fish fzf
• Or run ./bootstrap.sh for automatic detection
• Install Rust development tools (after OS dependencies)
• IDE Setup and Extensions
  • R3BL VSCode Extensions
• Install extensions (works with both VSCode and VSCode Insiders)
  • AI (LLM) Coding Agent Integration (Optional)
• Build the workspace and run tests
  • Key Commands
  • Cargo Target Directory Isolation for IDE/Tool Performance
    • The Problem: Cargo Lock Contention
    • The Solution: Separate Build Artifacts
    • Configuration by Tool
    • Benefits
    • Example Workflow Setup
• Terminal 2: File watcher with automatic tests
• Terminal 3: Run AI (LLM) coding agent
• Terminal 4: Run bacon
• Result: All four run in parallel, zero blocking
  • Disk Space Management
• Clean individual tool builds
• Full cleanup (nuclear option)
  • Troubleshooting
• VSCode: Check .vscode/settings.json
• Test with explicit path
  • Incremental Compilation Management
• Rebuild cleanly
  • Bacon Development Tools
  • Automated Development Monitoring
    • Option 1: Lightweight Watch Mode (Recommended for Most Users)
• Start watch mode
• Or run checks once (manual mode)
  • Option 2: Comprehensive Tmux Dashboard
  • Tmux Development Dashboard
• Reconnect to existing session from another terminal
• Kill the session when done
  • Cross-Platform Verification (Windows)
• Or run directly:
  • Rust Toolchain Management
    • Why mkdir for Locking?
• Only ONE process succeeds; all others fail
  • 1. rust-toolchain-update.fish - Smart Validated Toolchain Updates
• Or directly
  • 2. rust-toolchain-sync-to-toml.fish - Sync to Existing Config
• Or directly
• But you need to stay on nightly-2025-09-05 for testing a specific feature
• Now rust-analyzer works for 09-05
  • 3. rust-toolchain-validate.fish - Unified Toolchain Validation
• Complete mode: Full build+test validation (~5-10 minutes)
• View detailed help
  • 4. remove_toolchains.sh - Testing Utility
• Or
  • Log File Output
• Or review after completion
  • Comprehensive Toolchain Management System
  • Unified Script Architecture
• Star History
• Archive

Why R3BL TUI?

After leaving Google in 2021, I (Nazmul Idris) embarked on a journey to create infrastructure for modern, powerful, async CLI and TUI experiences built from the ground up in Rust.

The core architectural innovation: a purely async, immediate mode reactive UI (every state change triggers a render from scratch) where nothing blocks the main thread - unlike traditional approaches using platform-specific blocking operations like POSIX readline() on Linux/macOS or Windows ReadConsole().

R3BL TUI is fundamentally different from vim, neovim, and ratatui through its immediate mode reactive UI with clean separation between rendering and state mutation, and purely async nature.

This fully async, responsive framework works seamlessly across Linux, macOS, and Windows. It's optimized for use over SSH connections by painting only diffs, and handles complex concurrent operations with low latency while ensuring no thread blocking.

The Problem with Existing Solutions

I initially tried Node.js with ink, but encountered fundamental limitations:

• Module incompatibilities and dependency conflicts
• Limited control over keybindings and terminal behavior
• High resource consumption for simple tasks
• Screen flickering and poor rendering performance

The R3BL Solution: Web and Desktop App Inspired Terminal Apps

Our framework supports the full spectrum from CLI to hybrid TUI to full TUI experiences with deep system integration.

Key Innovation: "Applets" - A revolutionary state management system that allows processes to persist state across their lifecycle and share it with other instances or processes. And the underlying systems level infrastructure mechanisms that make this possible.

Built-from-Scratch Primitives

Async Readline: Unlike POSIX readline which is single-threaded and blocking, our implementation is fully async, interruptable, and non-blocking.

Choose API: Single-shot user interactions that enter raw mode without taking over the screen or disrupting the terminal's back buffer.

Full TUI: Complete raw mode with alternate screen support, fully async and non-destructive.

All components are end-to-end testable using our:

• InputDevice and OutputDevice types for stdin, stdout, and stderr.
• PTY infrastructure.
• VT-100 parser / generator infrastructure.

Advanced Rendering & Styling

• CSS-like styling with JSX-inspired declarative layouts
• Gradient color support with automatic terminal capability detection
• Double-buffered compositor for efficient rendering
• Comprehensive color support that adapts to terminal capabilities (even handles macOS Terminal.app's lack of truecolor support)

Rich Component Ecosystem

• Beautiful Markdown parser with syntax highlighting
• Rich text editor components
• Dialog box support
• Animation framework (in development)
• Process orchestration via the "script" module
• Async REPL infrastructure

R3BL TUI brings the ergonomics of modern web development (React, flexbox, CSS) to terminal applications in Rust, creating a new paradigm for command-line productivity tools.

We are building command line apps with rich text user interfaces (TUI). We want to lean into the terminal as a place of productivity, and build all kinds of delightful, ergonomic, and useful experiences for it.

1. 🔮 Instead of just building one app, we are building a library to enable any kind of rich TUI development w/ a twist: taking concepts that work really well for the frontend mobile and web development world and re-imagining them for TUI & Rust.

• Taking inspiration from things like React, SolidJS, Elm, iced-rs, Jetpack Compose, JSX, CSS, but making everything async (so they can be run in parallel & concurrent via Tokio).
• Even the thread running the main event loop doesn't block since it is async.
• Using macros to create DSLs to implement something inspired by CSS & JSX.

2. 🌎 We are building apps to enhance developer productivity & workflows.

• The idea here is not to rebuild tmux in Rust (separate processes mux'd onto a single terminal window). Rather it is to build a set of integrated "apps" (or "tasks") that run in the same process that renders to one terminal window.
• Inside of this terminal window, we can implement things like "applet" switching, routing, tiling layout, stacking layout, etc. so that we can manage a lot of TUI apps (which are tightly integrated) that are running in the same process, in the same window. So you can imagine that all these "applets" have shared application state. Each "applet" may also have its own local application state.
• You can mix and match "Full TUI" with "Partial TUI" to build for whatever use case you need. r3bl_tui allows you to create application state that can be moved between various "applets", where each "applet" can be "Full TUI" or "Partial TUI".
• Here are some examples of the types of "app"s we plan to build (for which this infrastructure acts as the open source engine):
  1. Multi user text editors w/ syntax highlighting.
  2. Integrations w/ github issues.
  3. Integrations w/ calendar, email, contacts APIs.

Welcome to the monorepo and workspace

All the crates in the r3bl-open-core monorepo provide lots of useful functionality to help you build TUI (text user interface) apps, along w/ general niceties & ergonomics that all Rustaceans 🦀 can enjoy 🎉.

Any top-level folder in this repository that contains a Cargo.toml file is a Rust project, also known as a crate. These crates are likely published to crates.io. Together, they form a Rust workspace.

Here's the changelog for this monorepo containing a Rust workspace. The changelog is a great place to start to get familiar with what has changed recently in each of the crates in this Rust workspace.

This workspace contains crates for building TUI, CLI, TTY apps

The r3bl_tui crate is the main crate that contains the core functionality for building TUI apps. It allows you to build apps that range from "full" TUI to "partial" TUI, and everything in the middle.

Here are some videos that you can watch to get a better understanding of TTY programming.

• Build with Naz: TTY playlist
• Build with Naz: async readline

This crate provides five entry points for building interactive terminal applications. Each internalizes terminal availability and size checks, and returns a TuiAvailability<T> enum:

Entry Point	Purpose	Best For
TerminalWindow::main_event_loop()	Full TUI framework	Complex, multi-component apps with layouts, dialogs, and custom logic.
ReadlineAsyncContext::try_new()	Async Readline	CLI-style line input, REPLs, and background logging.
choose()	Interactive Selection	Prompting user to select one or more items from a list.
PTYMuxBuilder::build()	Terminal Multiplexer	Wrapping existing CLI tools (like htop, bash) in a multi-pane TUI.
Spinner::try_start()	Indeterminate Progress	Long-running tasks needing visual feedback (standalone or embedded).

Full TUI (async, raw mode, full screen) for immersive TUI apps

tui gives you "raw mode", "alternate screen" and "full screen" support, while being totally async. It provides a full-featured framework with:

• App trait: Unidirectional data flow architecture.
• FlexBox: Responsive layout engine.
• Component System: Reusable UI elements (editors, dialogs, etc.).

An example of this is the "Full TUI" app edi in the r3bl-cmdr crate. You can install & run this with the following command:

cargo install r3bl-cmdr
edi

Partial TUI (async, partial raw mode, async readline) for choice based user interaction

choose allows you to build less interactive apps that ask a user user to make choices from a list of options and then use a decision tree to perform actions.

An example of this is this "Partial TUI" app giti in the r3bl-cmdr crate. You can install & run this with the following command:

cargo install r3bl-cmdr
giti

Partial TUI (async, partial raw mode, async readline) for async REPL

readline_async gives you the ability to easily ask for user input in a line editor. You can customize the prompt, and other behaviors, like input history.

Using this, you can build your own async shell programs using "async readline & stdout". Use advanced features like showing indeterminate progress spinners, and even write to stdout in an async manner, without clobbering the prompt / async readline, or the spinner. When the spinner is active, it pauses output to stdout, and resumes it when the spinner is stopped.

An example of this is this "Partial TUI" app giti in the r3bl-cmdr crate. You can install & run this with the following command:

cargo install r3bl-cmdr
giti

Here are other examples of this:

1. https://github.com/nazmulidris/rust-scratch/tree/main/tcp-api-server
2. https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples

Terminal multiplexer

PTYMux::run() lets you build a terminal multiplexer similar to tmux. It manages multiple child processes (each in its own PTY) with per-process virtual terminal buffers and instant switching. See the pty_mux_example for a working example that wraps bash, htop, and other CLI tools.

Power via composition

You can mix and match "Full TUI" with "Partial TUI" to build for whatever use case you need. r3bl_tui allows you to create application state that can be moved between various "applets", where each "applet" can be "Full TUI" or "Partial TUI".

Main library crate

There is just one main library crate in this workspace: r3bl_tui.

Main binary crate

There is just one main binary crate that contains user facing apps that are built using the library crates: r3bl-cmdr. This crate contains these apps:

• giti: Interactive git workflows made easy.
• edi: Beautiful Markdown editor with advanced rendering and editing features.
• env-source: Fast cross-platform environment loader evaluating scripts across POSIX sh, Fish, PowerShell, and cmd.exe.

You can install & run this with the following command:

cargo install r3bl-cmdr
# Interactive git workflows made easy.
giti --version
# Beautiful Markdown editor with advanced rendering and editing features.
edi --version
# Fast cross-platform environment loader.
env-source --version

Build infrastructure and developer tooling crate

The r3bl-build-infra crate provides developer productivity tools:

• cargo-rustdoc-fmt: Formats markdown tables and converts inline links to reference-style links in rustdoc comments.

You can install this binary with:

cargo install r3bl-build-infra
# Or from local source within this workspace:
fish run.fish install-build-infra

Project Task Organization

This project uses a task management system for organizing day-to-day development work using detailed task files with implementation plans in the ./task/ directory.

Task Management Files

• ./task/ - Directory containing detailed task management files:
  • Active tasks: task_*.md files in root of ./task/ - Complex tasks currently in progress
  • pending/: Tasks queued for later work
  • done/: Completed task files moved from root after all steps are marked [COMPLETE]
  • archive/: Abandoned tasks retained for historical reference
  • AGENTS.md: Rules and format specifications for creating and maintaining task files

Task File Format

Detailed task files follow a structured format defined in ./task/AGENTS.md:

Structure:

# Task Overview

High-level description, architecture, context, and the "why"

# Implementation Plan

## Step 0: Do Something [STATUS]

Detailed instructions for this step

### Step 0.0: Do Subtask [STATUS]

Details about subtask

### Step 0.1: Do Another Subtask [STATUS]

Details about another subtask

## Step 1: Do Something Else [STATUS]

More detailed steps...

Hierarchical organization:

• Steps are numbered (Step 0, Step 1, Step 2, etc.)
• Substeps use decimal notation (Step 0.0, Step 0.1, etc.)
• Table of contents automatically generated and maintained using doctoc
• Formatting standardized with prettier

Status markers:

• [COMPLETE] - Step finished and verified
• [WORK_IN_PROGRESS] - Currently working on this step
• [BLOCKED] - Cannot proceed (waiting for dependency)
• [DEFERRED] - Postponed to later

Task Workflow Commands

The /r3bl-task slash command (defined in AGENTS.md) manages the task lifecycle:

Create a new task:

/r3bl-task create my_feature_name

• Creates ./task/task_my_feature_name.md from your detailed plan
• Use after you have a comprehensive plan in your todo list
• Initializes structure with steps and status markers

Update an existing task:

/r3bl-task update my_feature_name

• Updates progress markers in ./task/task_my_feature_name.md
• Moves completed task files to ./task/done/ when all steps are [COMPLETE]

Resume working on a task:

/r3bl-task load my_feature_name

• Loads ./task/task_my_feature_name.md for continued work
• Resumes from the last step marked [WORK_IN_PROGRESS]
• If none found, asks which incomplete step to start with

Workflow Connection

The task organization workflow connects strategic planning with tactical execution:

• Strategic Planning (docs/ folder): Feature roadmaps, architectural dec