██████╗ ██████╗ ██████╗ ██╗ ████████╗██╗ ██╗██╗
██╔══██╗╚════██╗██╔══██╗██║ ╚══██╔══╝██║ ██║██║
██████╔╝ █████╔╝██████╔╝██║ ██║ ██║ ██║██║
██╔══██╗ ╚═══██╗██╔══██╗██║ ██║ ██║ ██║██║
██║ ██║██████╔╝██████╔╝███████╗ ██║ ╚██████╔╝██║
╚═╝ ╚═╝╚═════╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═════╝ ╚═╝
Table of contents:
- Why R3BL TUI?
- Welcome to the monorepo and workspace
- This workspace contains crates for building TUI, CLI, TTY apps
- Power via composition
- Project Task Organization
- Documentation and Planning
- Learn how these crates are built, provide feedback
- Quick Start
- IDE Setup and Extensions
- Build the workspace and run tests
- Star History
- Archive
After leaving Google in 2021, I (Nazmul Idris) embarked on creating infrastructure for modern, powerful 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.
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
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.
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 abstractions for stdin, stdout, and stderr.
- 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)
- 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 power and ergonomics of modern web development to the terminal, creating a new paradigm for command-line productivity tools.
We are working on building command line apps in Rust which have rich text user interfaces (TUI). We want to lean into the terminal as a place of productivity, and build all kinds of awesome apps for it.
- 🔮 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.
- 🌎 We are building apps to enhance developer productivity & workflows.
- The idea here is not to rebuild
tmuxin 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_tuiallows 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):
- Multi user text editors w/ syntax highlighting.
- Integrations w/ github issues.
- Integrations w/ calendar, email, contacts APIs.
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.
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.
tui gives you "raw mode",
"alternate screen" and "full screen" support, while being totally async. 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
edichoose
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
gitireadline_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
gitiHere are other examples of this:
- https://github.com/nazmulidris/rust-scratch/tree/main/tcp-api-server
- https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples
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".
There is just one main library crate in this workspace:
r3bl_tui.
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.
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 --versionThis project uses three root-level Markdown files to organize day-to-day development work:
todo.md- Active tasks and immediate priorities that need attentiondone.md- Completed tasks and achievements, providing a historical record of progressclaude.md- AI assistant interaction logs and collaborative planning sessions
The task organization workflow connects with the documentation in docs/ as follows:
- Strategic to Tactical: Items from
docs/planning files (strategic goals, feature designs) are broken down into actionable tasks and copied intotodo.md - Planning to Execution: Complex features get documented in
docs/first, then their implementation steps flow into the daily task management system - Documentation of Decisions: AI-assisted development sessions and decision-making processes are
logged in
claude.mdfor future reference
This dual-level approach ensures both strategic planning (in docs/) and tactical execution (in
root-level .md files) are well-organized and connected.
The docs/ folder contains
comprehensive documentation for this project, including:
release-guide.md- Step-by-step guide for releasing new versionscontributing_guides/- Detailed contribution guidelines including:- Branch naming conventions (
BRANCH.md) - Commit message standards (
COMMIT_MESSAGE.md) - Issue creation guidelines (
ISSUE.md) - Pull request procedures (
PULL_REQUEST.md) - Code style guide (
STYLE_GUIDE.md)
- Branch naming conventions (
- Parser strategy analysis and design decisions
- Performance optimization guides (
docs/task_tui_perf_optimize.md) - Architecture documentation for various components
- Feature-specific planning and design documents
The docs/ folder serves as the central repository for:
- Long-term planning: Strategic goals and feature roadmaps
- Technical decisions: Architecture choices and implementation strategies
- Process documentation: How we work and contribute to the project
- Design artifacts: Detailed analysis of complex features before implementation
To learn how we built this crate, please take a look at the following resources.
- If you like consuming video content, here's our YT channel. Please consider subscribing.
For Linux and macOS users, use the bootstrap script to automatically install all required tools:
# Clone the repository
git clone https://github.com/r3bl-org/r3bl-open-core.git
cd r3bl-open-core
# Run the bootstrap script
./bootstrap.shThe bootstrap.sh script will:
- Install Rust toolchain (rustup)
- Install Fish shell and fzf
- Install file watchers (inotifywait on Linux, fswatch on macOS)
- Install all required cargo development tools
- Detect your package manager automatically
If you prefer manual installation or are on Windows:
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 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 development tools
fish run.fish install-cargo-toolsFor an optimal development experience with r3bl-open-core, we provide a custom VSCode extension pack specifically designed for Rust development. This extension pack is not available on the VSCode marketplace and must be installed manually.
What's included:
- R3BL Theme - A carefully crafted dark theme optimized for Rust and Markdown development
- Auto Insert Copyright - Automatically inserts copyright headers in new files
- Semantic Configuration - Enhanced Rust syntax highlighting with additional semantic tokens
- Extension Pack - Bundles all R3BL extensions for easy installation
Benefits for r3bl-open-core development:
- Zero manual configuration required
- Enhanced semantic highlighting for better code readability
- Automatic copyright header insertion following project standards
- Seamless integration with rust-analyzer
- Optimized color scheme for the r3bl codebase
Installation:
# Clone the extension repository
git clone https://github.com/r3bl-org/r3bl-vscode-extensions.git
cd r3bl-vscode-extensions
# Install extensions (works with both VSCode and VSCode Insiders)
./install.shPrerequisites:
- VSCode or VSCode Insiders installed
- Bash shell (for running install.sh)
Post-installation:
- Restart VSCode
- Select the R3BL Theme:
Ctrl+Shift+P→ "Preferences: Color Theme" → "R3BL Theme" - Configure copyright settings if needed
The extensions work seamlessly with the existing development tools mentioned in this guide, including rust-analyzer and bacon.
There's a unified fish script that you can use to run the build and
release pipeline for this workspace, and more (local only operations).
To get a list of available commands, you can review the fish script in the root of this repo
run.fish. To see all available
commands:
fish run.fishYou should see output that looks like this:
Usage: fish run.fish <command> [args]
Workspace-wide commands:
all Run all major checks
build Build entire workspace
build-full Full build with clean and update
clean Clean entire workspace
test Test entire workspace
check Check all workspaces
clippy Run clippy on all workspaces
clippy-pedantic Run clippy with pedantic lints
docs Generate docs for all
serve-docs Serve documentation
rustfmt Format all code
install-cargo-tools Install development tools
upgrade-deps Upgrade dependencies
audit-deps Security audit
unmaintained Check for unmaintained deps
build-server Remote build server - uses rsync
Watch commands:
watch-all-tests Watch files, run all tests
watch-one-test [pattern] Watch files, run specific test
watch-clippy Watch files, run clippy
watch-check Watch files, run cargo check
TUI-specific commands:
run-examples [--release] [--no-log] Run TUI examples
run-examples-flamegraph-svg Generate SVG flamegraph
run-examples-flamegraph-fold Generate perf-folded format
bench Run benchmarks
cmdr-specific commands:
run-binaries Run edi, giti, or rc
install-cmdr Install cmdr binaries
docker-build Build release in Docker
Other commands:
log Monitor log.txt in cmdr or tui directory
help Show this help
| Command | Description |
|---|---|
fish run.fish all |
Run all major checks (build, test, clippy, docs, audit, format) |
fish run.fish build |
Build the entire workspace |
fish run.fish test |
Run all tests across the workspace |
fish run.fish watch-all-tests |
Watch for file changes and run tests automatically |
fish run.fish run-examples |
Run TUI examples interactively |
fish run.fish run-binaries |
Run cmdr binaries (edi, giti, rc) interactively |
fish run.fish update-toolchain |
Update Rust to month-old nightly toolchain with cleanup |
This project includes bacon configuration for background code checking and testing. Bacon provides real-time feedback on code changes with two distinct workflows:
Interactive Workflow (Rich TUI with details):
- Full terminal UI with detailed output
- Ctrl+click on errors and warnings to jump directly to source code (via OSC hyperlinks)
- Perfect for active debugging and development
Background Workflow (Silent monitoring):
- Minimal output - just success/failure status
- Answers simple yes/no questions like "do tests pass?" or "do docs build?"
- Ideal for background monitoring while focusing on other tasks
Bacon commands:
| Command | Workflow | Description |
|---|---|---|
bacon nextest |
Interactive | Rich TUI test runner with clickable errors, detailed output, and real-time updates |
bacon nextest --headless --summary |
Background | Silent test runner providing only pass/fail status |
bacon doc |
Interactive | Documentation builder with detailed output and error navigation |
bacon doc --headless --summary |
Background | Silent doc builder answering "did docs generate?" with minimal output |
Choose the workflow that matches your current needs:
- Use interactive when actively debugging or wanting detailed feedback
- Use background for continuous monitoring, CI/CD pipelines, or when you just need to know if things work
Note: We use cargo-nextest for running tests as it's significantly faster than cargo test. However, nextest does not run doctests (tests in documentation comments). To run doctests, use cargo test --doc separately.
For developers who want ultra-minimal status monitoring, this project includes two bash scripts designed for integration with the GNOME Executor extension. These scripts provide at-a-glance status indicators in your GNOME top bar.
Quick Status Scripts:
| Script | Purpose | Success Output | Failure Output |
|---|---|---|---|
test-status-one-line.bash |
Run tests and show emoji status | 🧪✔️ |
🧪❌ |
doc-status-one-line.bash |
Build docs and show emoji status | 📚✔️ |
📚❌ |
Key Features:
- Single-line output: Perfect for status bars and monitoring systems
- Emoji-only status: Universal visual language requiring no text parsing
- Silent operation: All cargo output is suppressed, only status emoji appears
- Directory-independent: Scripts work from anywhere by changing to project directory
- Fast execution: Optimized for quick status checks without verbose output
Usage Examples:
# Quick test status check
./test-status-one-line.bash
# Output: " 🧪✔️"
# Quick documentation build check
./doc-status-one-line.bash
# Output: " 📚✔️"Integration with Development Workflow:
- Complements Bacon: While bacon provides rich interactive feedback, these scripts offer minimal monitoring
- CI/CD friendly: Perfect for automated pipelines requiring simple pass/fail status
- GNOME integration: Designed specifically for desktop environment status bar integration
- Background monitoring: Ideal for continuous status monitoring without interrupting workflow
These scripts provide the same underlying functionality as the bacon workflows but with radically different output designed for external consumption rather than developer interaction.
This project uses sccache to speed up Rust compilation by
caching build artifacts (configured in the .cargo/config.toml file). After running
fish run.fish install-cargo-tools, you can verify sccache is working:
sccache --show-stats
# Copy to clipboard for easy sharing
sccache --show-status 2>&1 | setclipThis will display cache hit rates and storage information. Higher cache hit percentages indicate faster builds through cached compilation results.
To reset the cache, you can run:
# Complete reset
sccache --zero-stats
sccache --stop-server
rm -rf ~/.cache/sccache
# Server starts automatically on next use
cargo build # or sccache --show-statsThere is no need to restart the server, as it is designed to be "lazy". And running cargo build or
sccache --show-stats will automatically start the server if it is stopped.
This project uses an intelligent Rust toolchain management strategy to balance access to recent language features with stability. The update-toolchain command maintains a month-old nightly toolchain, avoiding bleeding-edge instability while staying current with Rust development.
fish run.fish update-toolchainWhat it does:
- Calculates a nightly toolchain date from exactly 1 month ago
- Updates
rust-toolchain.tomlto use this stable-but-recent nightly - Installs the target toolchain if not already present
- Performs aggressive cleanup by removing all old nightly toolchains except:
- All stable toolchains (
stable-*) - The newly targeted month-old nightly
- All stable toolchains (
- Logs all operations to
/home/nazmul/Downloads/rust-toolchain-update.log
Benefits:
- Stability: Month-old nightlies have proven stability while providing recent features
- Disk space savings: Aggressive cleanup removes accumulated old toolchains
- Consistency: Ensures all developers use the same Rust version
- Automation ready: Designed to run weekly via systemd timer for hands-off maintenance
Example output:
Target toolchain: nightly-2024-08-13
✅ Successfully updated rust-toolchain.toml
✅ Successfully installed/verified nightly-2024-08-13
Removed 3 old toolchain(s)
Toolchains directory size before cleanup: 2.1G
Toolchains directory size after cleanup: 1.4G
For developers working on the cmdr upgrade check feature:
remove_toolchains.sh- Removes ALL Rust toolchains (⚠️ DESTRUCTIVE)- Purpose: Test the upgrade progress display in
ediandgiti - Creates a clean slate to see full rustup installation progress
- Usage:
./remove_toolchains.shthencargo run --bin edi - Recovery:
rustup toolchain install stable && rustup default stable - See:
cmdr/src/analytics_client/upgrade_check.rsfor implementation details
- Purpose: Test the upgrade progress display in
The root-level run.fish script consolidates functionality that was previously scattered across
multiple workspace-specific scripts. This unified approach provides:
- Workspace-wide commands that operate on the entire project
- TUI-specific commands for running examples and benchmarks
- cmdr-specific commands for binary management
- Cross-platform file watching using inotifywait (Linux) or fswatch (macOS)
- Smart log monitoring that detects and manages log files from different workspaces
All commands work from the root directory, eliminating the need to navigate between subdirectories.
As this repo grows, changes, and matures, pruning is necessary. The
r3bl-open-core-archive is where all the code
and artifacts that are no longer needed are moved to.
This way nothing is "lost" and if you need to use some of the code that was removed, you can find it there.
Also if you want to make changes to this code and maintain it yourself, please let us know.
- You can submit PRs and we can also accept them, and publish them to crates.io if that makes sense.
- Or we can even work out and arrangements to move ownership of the code & crate to you if you would like to commit to maintaining it.