r3bl-open-core
██████╗ ██████╗ ██████╗
██╔══██╗██╔═══██╗██╔════╝
██████╔╝██║ ██║██║
██╔══██╗██║ ██║██║
██║ ██║╚██████╔╝╚██████╗
╚═╝ ╚═╝ ╚═════╝ ╚═════╝
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
██████╗ ██████╗ ██████╗
██╔══██╗██╔═══██╗██╔════╝
██████╔╝██║ ██║██║
██╔══██╗██║ ██║██║
██║ ██║╚██████╔╝╚██████╗
╚═╝ ╚═╝ ╚═════╝ ╚═════╝
Fully async Rust TUI engine 🦀. For powering AI/LLM coding agents, Cloud/SSH workflows & interactive CLIs: non-blocking readline, inline dialogs, React/Elm-style full-screen TUI, Markdown editor, PTY multiplexing & rust-analyzer MCP server.
Despite the massive rise of AI/LLM coding agents & execution harnesses and cloud VM
administration over SSH, terminal UI innovation has largely stagnated since the 1970s.
Most CLI tools still rely on blocking single-threaded I/O, [curses]-era APIs, and
fragile platform hacks - or rely on the heavy, fragile workaround of layering web stacks
like [Node.js], [React], and [ink] onto the console. This introduces unreasonable
memory bloat, high latency, broken keyboard shortcuts, and unpredictable instability that
breaks down during long-horizon agentic workflows and sub-process orchestration.
ROC (r3bl-open-core) moves the terminal forward (with love & respect) into 2026 and
beyond. ❤️
R3BL brings modern web and desktop app design patterns to the terminal, turning it into a place of focused productivity to build delightful, ergonomic, and rich text user interface (TUI) experiences.
Representing years of systems programming, performance optimization, and production-grade infrastructure design in Rust, R3BL re-imagines the terminal for the modern era - making rich, reactive TUI applications accessible over SSH to any terminal emulator across Linux, macOS, Windows, and Unix/BSDs (such as FreeBSD).
R3BL TUI is fundamentally different from [vim], [neovim], and [ratatui] through its
immediate mode reactive UI, clean separation between rendering and state mutation, and
purely async architecture - it never blocks the main thread, and natively embraces
multithreaded execution and multi-process orchestration.
ROC is designed to power four primary use cases:
🤖 AI/LLM Coding Agents & Execution Harnesses: Building fast, interactive terminal
interfaces and execution harnesses for AI/LLM coding agents in pure Rust. While popular
agent tools are written in [Node.js] and [ink] (see [origin story]), Node-based
runtimes struggle with runaway memory consumption, fragile sub-process control, and
unstable PTY session management when orchestrating heavy, long-running tools in
sandboxed environments (containers, microVMs, systemd-nspawn machines, etc.).
Furthermore, Node-based runtimes struggle with terminal input decoding, frequently
dropping modifier keys, mangling keyboard chords, and introducing sluggish ESC key
disambiguation lag. ROC provides a rock-solid, pure Rust foundation engineered for
native PTY orchestration, zero-latency ANSI input decoding, deterministic process
lifecycles, flicker-free diff rendering, and minimal resource overhead.
☁️ DevOps & Cloud Workflows: Administering modern cloud infrastructure shouldn't feel like using stone-age tools to build a satellite. Juggling remote VMs, containers, and multi-process server environments through bare terminal sessions is slow and error-prone. ROC transforms terminal workflows into a rich, responsive workspace with in-memory virtual terminal emulation, virtual tabs, 2D horizontal panning across wide logs, and double-buffered diff rendering that stays lag-free even over high-latency SSH connections.
📝 Interactive Document & Markdown Workflows: Rich interactive editing, syntax highlighting, and real-time code block execution directly inside Markdown documents in the terminal, bridging documentation directly with live operations.
🛠️ Developer Productivity Infrastructure: High-efficiency developer tooling and composable terminal infrastructure to enhance knowledge capture, eliminate friction, and streamline everyday command-line workflows.
The framework supports the full spectrum from CLI to inline dialogs to full-screen TUI and terminal multiplexing experiences with deep systems integration.
With over 2.7M downloads across crates.io, ROC (r3bl-open-core) provides
production-grade systems infrastructure across five specialized crates:
r3bl_tuiAt the heart of ROC is r3bl_tui, which provides four foundational interaction
primitives designed from the ground up in pure Rust:
📟 CLI & REPLs (readline_async): Unlike GNU [readline] which is single-threaded
and blocking, our implementation is fully async, interruptable, and non-blocking,
allowing background spinners and tasks to print concurrently without pausing line
editing or blocking your main thread.
📑 Inline / Partial TUI (choose): Single-shot interactive multi-select dialogs
that enter raw mode and render inline in terminal scrollback without taking over the
screen or disrupting the back buffer (similar to fzf in spirit).
🖥️ Full-Screen TUI: Complete raw mode with alternate screen support, fully async and panic-safe terminal restoration. Build [React] and [Elm] inspired apps with [unidirectional data flow], [responsive] [flexbox] layouts, [declarative] [CSS-like] styling, reactive state architecture, reusable modal dialogs with asynchronous autocomplete, and a full-featured Markdown editor component with custom parser, custom syntax highlighter, and fast zero-copy gap buffer.
🔀 Terminal Multiplexing & PTY: In-memory virtual terminals, virtual terminal tabs,
deterministic process orchestration, and multiplexing primitives (build your own
[tmux] or sandboxed AI/LLM coding agent execution harness) featuring 2D horizontal
viewport panning and decoupled throughput.
Power via Composition: Designed to be [loosely coupled and strongly coherent], you can
pick and choose only what you need or compose them seamlessly within a single application.
Transition smoothly from a non-blocking readline_async prompt into an inline choose
menu, launch a full-screen TUI for complex tasks, or orchestrate background PTY
subprocesses, all sharing application state without process restarts.
The entire framework across all 4 pillars is testable across Linux, macOS, and Windows. Powered by our own PTY pillar, real production code runs headlessly in an isolated virtual terminal environment, enabling end-to-end testing of interactive apps without requiring human interaction:
generate_pty_test! macro. Automate
key sequences, window resizing, and screen output verification in completely isolated
child processes without someone having to sit and manually type at a keyboard.OfsBuf),
providing built-in visual snapshot testing. Easily diff and assert the actual rendered
terminal screen state headlessly generated in a real PTY environment.InputDevice and OutputDevice abstract terminal I/O away
from physical stdin and stdout, allowing input events and output streams to be
driven and inspected directly in tests without taking over your terminal.📐 Zero-Cost Type-Proof Architecture & Mathematical Correctness: Rather than relying
on ambiguous primitive integers (usize, u16) and runtime assertions, formal type
theory and trait hierarchies [make illegal states unrepresentable]:
CRow, VPRow, CHeight), eliminating
primitive obsession and transposition bugs with zero runtime memory or performance
overhead:
IndexOps: VPRow, VPCol, CRow, CCol), 1-based
terminal coordinates (TermRow, TermCol), and 1-based lengths (LengthOps:
VPHeight, VPWidth, CHeight, CWidth).to_zero_based(), from_zero_based(),
convert_to_length()).Index + Length = Index, Index - Index = Length) to eliminate dangerous
manual arithmetic on raw integers, preventing off-by-one errors (< vs <=),
negative underflow, and CSI zero-index terminal crashes (TermRowDelta,
TermColDelta).StorageCoordinate, usize: CPos) from 16-bit visual
coordinates (ScreenCoordinate, u16: VPPos), requiring explicit camera viewport
transformations.as Casts: Replaces dangerous,
silent primitive as casting across the codebase with explicit, type-safe traits
(WideningCastTo for lossless promotions and NarrowingCastTo for checked/clamped
reductions), preventing accidental truncations and sign-loss bugs.bool flags. Instead, they return
structured witness enums (ArrayOverflowResult, RangeBoundsResult), forcing
callers to exhaustively handle all boundary states at compile time.🦄 First-Class Unicode & Complex Emoji Engine (GCString): Most terminal emulators
and TUI libraries break when handling "jumbo emojis", zero-width joiners (ZWJ), skin
tone modifiers, and wide characters (display width > 1), causing visual tearing,
misaligned borders, and string-slicing panics. ROC solves this from the ground up via
GCStringOwned:
ByteIndex, UTF-8 offset), logical editing position (SegIndex, user-perceived
grapheme clusters), and visual column position (VPCol, actual terminal display
width).👨🏾🤝👨🏿 spans 5 codepoints and 7 code units, but resolves to 1 logical
grapheme segment and 2 visual columns).🔒 Supply-Chain Integrity & Owning Our BOM: In an era of software supply-chain
attacks, maintainer burnout, and abandonware, our explicit architectural goal is to
own our Bill of Materials (BOM). Critical primitives (including our custom
direct_to_ansi terminal I/O backend, VT-100/ANSI parser, zero-copy gap buffer, and
Markdown parser) are engineered in-house in pure Rust. We strictly limit external
dependencies to actively funded, strongly supported, and battle-tested industry
foundations (such as tokio, mio, and mimalloc), safeguarding production
applications against transitive bloat, sudden deprecations, and upstream
vulnerabilities.
🌍 Multi-Backend Architecture (Linux, macOS, Windows, Unix/BSDs): Native, first-class support across platforms using the best backend for each OS:
direct_to_ansi engine
(talking directly to the terminal device via mio/epoll for minimal latency and
maximum throughput, without the use of crossterm).crossterm. We plan to expand
direct_to_ansi in the future to replace crossterm across all platforms.🚀 SIMD Contiguous Memory Layout (Flat2DArray): Single contiguous 1D allocation
indexed as 2D, delivering 2.3x rendering speedups, SIMD chunk batching, and eliminating
pointer indirection ([implementation deep
dive][High-Performance Flat 2D Arrays in Rust (SIMD, L1 Cache)] and [memory latency
theory][Rust, Memory performance & latency]).
🧑🤝🧑 Double-Buffered SSH-Optimized Diff Rendering: Double-buffered compositor computes minimal cell-level diffs between frames, painting only what changed for smooth, flicker-free performance over high-latency SSH connections, with multi-layer Z-order compositing for modal overlays and popups.
🔀 Terminal Multiplexing & PTY Architecture (PTYMux): Decouples physical display
constraints from subprocess execution via virtual terminals and process orchestration:
xterm, Alacritty, Kitty) lack horizontal
panning for standard CLI tools (like cat, grep, git log, dmesg), forcibly
hard-wrapping wide lines across rows and mangling tabular data, JSON, or stack
traces into unreadable spaghetti. When running any CLI program inside a ROC PTY
session (a concrete manifestation of which is [pty_mux_example], powered by
[GrowableBuffer] and [PTYMux]), ROC decouples the physical viewport from the
virtual terminal canvas width (e.g., 1,000+ columns). The child process writes into
this wide virtual canvas without line wrapping, allowing users to smoothly pan
horizontally (Shift + Mouse Wheel or trackpad gestures) across the output without
layout destruction.xterm): In
traditional terminal emulators (like xterm), running a command that dumps
megabytes of text (e.g., cat large.log) blocks the process on stdout I/O while
the terminal synchronously parses escape codes, recalculates line wrapping, and
rasterizes every glyph. Counter-intuitively, running that same command inside a ROC
PTY session (such as [pty_mux_example]) running inside xterm is often
significantly faster than running the command directly in bare xterm. ROC's
headless VT-100 parser (OfsBufVT100) acts as an in-memory shock absorber,
ingesting raw subprocess output at memory bus speeds, while double-buffered diff
rendering paints only the visible viewport to the host terminal at controlled
display intervals. Subprocesses drain stdout without stalling on terminal drawing
or network I/O backpressure.🕊️ Terminfo Liberation: Completely frees your applications from legacy terminfo /
termcap databases and [ncurses] baggage by querying modern ANSI protocols directly
at runtime.
📜 CSS-Like Styling & Declarative Layouts: Responsive [flexbox] layouts and
[declarative] [CSS-like] styling inspired by [React] and [Elm].
🎨 Intelligent Color Degradation: Automatically detects terminal capabilities and
gracefully degrades colors: 24-bit Truecolor -> 256 colors -> 16 ANSI colors ->
Monochrome (black & white). Gracefully handles environments lacking truecolor support
(such as pre-macOS 26 Tahoe Terminal.app, Linux virtual consoles, or headless CI
runners), complete with dynamic lolcat rainbow color-wheel palettes that automatically
adapt to terminal color capability.
⌨️ Modern Terminal Input & Keyboard Protocol Architecture: Combines Linux-native
kernel TTY polling via direct_to_ansi with an IO-free Sans-IO protocol state machine
for robust, zero-latency input handling across local terminals and SSH:
direct_to_ansi Driver: Bypasses crossterm and libc FFI
wrappers on Linux by talking directly to /dev/tty via mio/epoll(7),
eliminating thread-blocking reads and CPU-spinning loops.Shift+Enter], Ctrl+Enter, Ctrl+Tab, Ctrl+Number/Punctuation, Ctrl+I vs
Tab, and Alt+[ collisions.CSI u) Progressive Enhancement: Negotiates advanced
keyboard protocols with modern terminals ([Kitty keyboard protocol]), enabling full
modifier reporting, key-release events, and unambiguous key sequences with graceful
legacy fallback.MaybeMore): Replaces brittle 50-100ms timeout
heuristics with an internal state machine (KernelDrained, KernelMayHaveMore),
achieving 0ms zero-latency ESC handling while correctly reassembling multi-packet
escape sequences across SSH.stdin to prevent terminal text leakage, while supporting full SGR mouse
tracking (clicks, drags, scroll wheel).🧩 Composable "Applet" Architecture & Shared State: Enables multiple integrated TUI experiences ("applets") to run within the same process and terminal window. Supports shared application state across sub-apps alongside local view state, allowing seamless transitions and routing between Full-Screen TUI views and inline Partial-TUI dialogs without process restarts or lost context.
All the crates in the r3bl-open-core [monorepo] provide lots of useful functionality to
help you build TUI (text user interface) apps, along with 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.
This crate provides five entry points for building interactive terminal applications. Each
internalizes terminal availability and size checks, and returns a TuiAvailability<T>
enum:
[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.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
[choose] allows you to build less interactive apps that ask a 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
[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:
tcp-api-server]: An interactive async REPL client demonstrating readline_async
with concurrent background tasks and progress spinners.tui/examples]: Standalone examples in this workspace demonstrating async readline
(readline_async.rs), spinners (spinner.rs), shell (shell_async.rs), and PTY
orchestration.[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.
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].
To add r3bl_tui to your own Rust project:
Option 1: crates.io (stable release)
Use this if you prefer stable, versioned releases:
cargo add r3bl_tui
Or in your Cargo.toml:
[dependencies]
r3bl_tui = "0.7.8"
Option 2: GitHub main branch (bleeding edge)
Bug fixes and patches land on main immediately before being published to crates.io. If
you need the latest fixes or rapid iteration:
cargo add r3bl_tui --git https://github.com/r3bl-org/r3bl-open-core.git --branch main
Or in your Cargo.toml:
[dependencies]
r3bl_tui = { git = "https://github.com/r3bl-org/r3bl-open-core.git", branch = "main" }
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
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
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/] - Directory containing detailed task management files:
task_*.md files in root of ./task/ - Complex tasks currently
in progresspending/: Tasks queued for later workdone/: Completed task files moved from root after all steps are marked
[COMPLETE]archive/: Abandoned tasks retained for historical referenceAGENTS.md: Rules and format specifications for creating and maintaining task
filesDetailed 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:
doctocprettierStatus markers:
[COMPLETE] - Step finished and verified[WORK_IN_PROGRESS] - Currently working on this step[BLOCKED] - Cannot proceed (waiting for dependency)[DEFERRED] - Postponed to laterThe /r3bl-task slash command (defined in [AGENTS.md: task-tracking-system]) manages
the task lifecycle:
Create a new task:
/r3bl-task create my_feature_name
./task/task_my_feature_name.md from your detailed planUpdate an existing task:
/r3bl-task update my_feature_name
./task/task_my_feature_name.md./task/done/ when all steps are [COMPLETE]Resume working on a task:
/r3bl-task load my_feature_name
./task/task_my_feature_name.md for continued work[WORK_IN_PROGRESS]The task organization workflow connects strategic planning with tactical execution:
docs/ folder): Feature roadmaps, architectural decisions,
design documentsdocs/ first./r3bl-task create → ./task/task_*.md/r3bl-task update marking
progress./task/done/ via /r3bl-task updateThis approach (docs → ./task/) ensures strategic planning, tactical planning, and detailed execution are well-organized and connected.
R3BL provides IDE extensions to enhance your development workflow:
For VSCode Users
R3BL provides custom VSCode extensions including Task Spaces (organize editor tabs by context), theme, and enhanced syntax highlighting. See the [R3BL VSCode Extensions] section below for installation and detailed feature descriptions.
Workflow Integration:
The R3BL Task Spaces extension helps you organize editor tabs by context (e.g., one space
for features, one for docs, one for debugging) while the ./task/ files track your
implementation progress.
We invest heavily in documentation quality because it is the right thing to do. Also, [research shows] it is the single most important factor developers consider when evaluating open source projects. In the Rust ecosystem specifically, documentation is the #1 crate evaluation criterion ([RFC 1824]), and 91% of practitioners depend on documentation for adoption decisions ([2024 study]). Every public API has rustdoc comments with usage examples, and doc tests verify that every example compiles and runs.
Our documentation standards are not aspirational - they are [machine-enforced]. Conventions for voice, structure, links, and formatting are codified as an AI (LLM) skill that runs during development, not a style guide that sits in a wiki collecting dust. We also operationalize inclusivity at the documentation level: our [Pedagogical Links for Inclusivity] rule requires linking domain-specific terms to external references so no reader is excluded by assumed knowledge - a concrete, measurable practice rather than a vague aspiration.
The [docs/] folder contains comprehensive documentation for this project, including:
why-good-docs-matter.md] - Research evidence for why we invest heavily in
documentation qualityrelease-guide.md] - Step-by-step guide for releasing new versionsCONTRIBUTING.md] - Contribution guidelines including branch naming, commit message
standards, local checks, and PR proceduresdocs/task_tui_perf_optimize.md)The docs/ folder serves as the central repository for:
To learn how we built this crate, please take a look at the following resources.
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.sh
The [bootstrap.sh] script handles OS-level setup with a clean main function
structure and will:
rustup) and ensure cargo is in
PATHFish shell and fzf for interactive developmentinotifywait on Linux, fswatch on macOS)htop, screen, tmux for system monitoringNode.js] and npm (for Markdown formatting via
Prettier and local documentation serving)Antigravity CLI (agy), or any tool of your choicefish run.fish install-cargo-tools for all
Rust-specific cargo toolingArchitecture: Uses clear function separation with main() orchestrator and dedicated
functions for each concern (install_rustup, install_clang, install_shell_tools,
etc.)
If you prefer manual installation or are on Windows:
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install `fish`, `fzf`, `nodejs`, and `npm` (via package manager)
# Ubuntu/Debian: sudo apt install fish fzf nodejs npm
# macOS: brew install fish fzf node
# Or run `./bootstrap.sh` for automatic detection
# Install Rust development tools (after OS dependencies)
fish run.fish install-cargo-tools
Note: The manual approach requires you to install OS-level dependencies yourself. The
install-cargo-tools command focuses specifically on Rust development tools:
From crates.io (via cargo-binstall with fallback to cargo install):
cargo-binstall: Fast binary installer (installed first as foundation)bacon, flamegraph, infernocargo-workspaces, cargo-cache, cargo-updatecargo-deny, cargo-unmaintained, cargo-expand,
cargo-readme, lycheerust-analyzer component, rust-srcFrom local source (via cargo install --path):
edi, giti, rc, env-source binaries (calls run.fish install-cmdr)cargo-rustdoc-fmt (calls run.fish install-build-infra)rust-analyzer-mcp-server MCP binary (calls
run.fish install-rust-analyzer-mcp-server)Features:
cargo-binstall for speed with fallback to
cargo install --lockedcmdr, build-infra, and
rust-analyzer-mcp-server from source with current toolchainscript_lib.fish for consistencyFor an optimal development experience with r3bl-open-core in VSCode, we provide a custom 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:
./task/ file management system by helping you organize
your editor sessions.Benefits for r3bl-open-core development:
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.sh
Prerequisites:
Post-installation:
Ctrl+Shift+P → "Preferences: Color Theme" → "R3BL Theme"The R3BL VSCode extensions work seamlessly with the existing development tools mentioned
in this guide, including rust-analyzer, bacon, and the comprehensive development
workflow.
We believe developers should be empowered to think for themselves, read & understand code, and write code. We do not push the use of AI (LLM) coding agents or advocate "vibe coding".
Comprehensive Non-AI (LLM) Tooling:
Our primary development experience is built around robust tools and scripts which don't require LLMs. These tools are deterministic (not probabilistic), don't hallucinate, are fast & efficient, and only consume your local compute and energy resources:
./check.fish]: Your go-to tool for builds, tests, and linting.run.fish][unified-script-architecture]: Orchestrates workspace-wide commands.bacon][bacon-development-tools]: Provides real-time background feedback.bootstrap.sh][automated-setup-recommended]: Automated OS-level and toolchain setup.cargo-rustdoc-fmt: Custom rustdoc formatter located in the [build-infra/]
folder.rustup, cargo, rust-analyzer, clippy, rustfmt.fzf (fuzzy finding), btop (monitoring), tmux (multiplexing),
flamegraph (profiling), inferno (stack collapse), lychee (link checking).cargo-binstall, cargo-deny, cargo-expand, cargo-update,
cargo-workspaces, cargo-cache, cargo-outdated, cargo-unmaintained,
cargo-readme, cargo-warloc (count lines of code).For those who choose to use AI (LLM) coding agents, this project is agent-agnostic and provides structured guidance to support you in using your tool of choice. This ensures that you can:
skills] themselves.How it works:
Using an AI coding agent is completely optional. If you do choose to use an AI/LLM coding
agent (such as Antigravity CLI (agy), or any tool of your choice), point it to the
instructions in [AGENTS.md]. This file contains our design philosophy, coding standards,
and crate-specific guidance.
To equip your AI coding agent with AST-aware code navigation, compiler diagnostics, and
automated quick-fixes via rust-analyzer, connect it to our
[r3bl-rust-analyzer-mcp-server] ([crates.io: r3bl-rust-analyzer-mcp-server]) Model
Context Protocol (MCP) server.
Available Skills (.agents/skills/):
When used, AI (LLM) coding agents can leverage the patterns and commands defined in the
.agents/ directory:
Slash Commands:
Invoke skills directly in your AI (LLM) coding agent:
AI (LLM) Coding Agent Synergy: R3BL VSCode Extensions
For the best experience, install the [R3BL VSCode Extensions]. They boost your productivity whether you use them standalone or hand-in-hand with AI (LLM) coding agents. Here are some highlights:
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.fish
TUI Testing: The
r3bl_tuicrate uses PTY-based testing for accurate terminal I/O verification. See the [PTY Testing Infrastructure] section in the TUI README for details on writing and running TUI tests.
High-Performance Zero-Configuration Build Architecture: check.fish dynamically
provisions an isolated tmpfs target directory based on the repository and worktree
location, and symlinks ./target to that directory. This ensures blazing-fast RAM builds
(~2-3x speedup) while completely eliminating lock contention across multiple terminals,
IDE instances (rust-analyzer), and Git worktrees.
When working concurrently across multiple Git worktrees (e.g. roc, roc-build-spawny,
roc-fix-shift-home-lockup), each worktree operates in its own isolated tmpfs workspace:
/home/user/github/roc/target -> /tmp/check-fish-$USER-roc-<hash>/target
/home/user/github/roc-build-spawny/target -> /tmp/check-fish-$USER-roc-build-spawny-<hash>/target
/home/user/github/roc-fix-shift-home-lockup/target -> /tmp/check-fish-$USER-roc-fix-shift-home-lockup-<hash>/target
.lock file and build
cache../target is a native filesystem symlink,
cargo, rust-analyzer, bacon, and check.fish within the same worktree share the
exact same RAM cache seamlessly without requiring custom CARGO_TARGET_DIR environment
variables.check.fish automatically inspects total physical system memory:
/tmp (RAM-backed tmpfs) for maximum
compilation speed./var/tmp (NVMe
disk-backed storage) to prevent tmpfs exhaustion and out-of-memory crashes during large
builds or background system updates.check.fish can be safely executed from any subfolder or crate directory (e.g. from
tui/, cmdr/, etc.). It automatically resolves the repository root (CHECK_REPO_ROOT)
and operates relative to the root project workspace.
When cloning, syncing, or copying repository folders via rsync (or across reboots where
tmpfs is wiped):
./target symlinks are detected and auto-healed whenever
check.fish runs../check.fish --check on any new machine or worktree to instantly
provision the build cache symlink.--clean)To clear the build cache:
./check.fish --clean (Recommended): Safely empties the backing tmpfs target
directory contents and staging directories, preserving the symlink structure and
avoiding OS errors.cargo clean: Standard cargo clean works normally through the symlink.rm -rf target: If the ./target symlink is manually deleted from the shell,
check.fish detects the missing symlink on the next run, wipes any orphaned backing
store, and re-provisions a fresh symlink.Incremental compilation is disabled globally (incremental = false in
.cargo/config.toml) to avoid issues with the rustc dependency graph on nightly builds:
# .cargo/config.toml
[build]
incremental = false # Disable to avoid rustc dep graph ICE on nightly
Why disable incremental compilation?
cargo invocationsIf you encounter ICE errors anyway:
# Clear any corrupted incremental artifacts
rm -rf target/check target/debug target/release
# Rebuild cleanly
cargo check # or cargo build, cargo test, etc.
The check.fish script also explicitly sets CARGO_INCREMENTAL=0 as a redundant
safeguard.
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):
OSC hyperlinks)Background Workflow (Silent monitoring):
Available Bacon Commands:
Code Quality & Checking:
Testing:
Documentation:
Running & Benchmarking:
Choose the workflow that matches your current needs:
Testing Notes:
bacon test to run all tests (includes unit, integration, and doctests)bacon doctests or bacon test --doc to run only documentation testsThe project provides two complementary approaches for continuous monitoring during development - choose based on your workflow preferences:
For developers who want automated monitoring without the overhead of tmux, use the
standalone check script:
./check.fish --watch
What it does:
cmdr/src/, analytics_schema/src/, and
tui/src/ for changescargo logsrust-toolchain-update.fish to find
a stable nightlyExample output:
👀 Watch mode activated
Monitoring: cmdr/src, analytics_schema/src, tui/src
Log file: /tmp/r3bl_tui/check.log
Press Ctrl+C to stop
[10:00:00] 🔄 Quiet period reached, running checks...
[10:00:01] 🛫 Running tests...
[10:00:05] ✅ tests passed (4.2s)
[10:00:06] 🛫 Running doctests...
[10:00:08] ✅ doctests passed (2.1s)
[10:00:09] 🛫 Running doc build...
[10:00:15] ✅ doc build passed (6.3s)
[10:00:15] ✅ All checks passed!
[10:00:15] 👀 Watching for changes...
Benefits:
tmux complexity - just one terminalEvent handling: While checks run (30+ seconds), the Linux kernel buffers new file
change events. When checks complete, buffered events trigger immediately if debounce
allows. This ensures no changes are lost but may cause cascading re-runs if you save
multiple times during test execution. Adjust DEBOUNCE_WINDOW_SECS in the script if
needed.
Usage:
# Show available options
./check.fish --help
# Start watch mode
./check.fish --watch
# Or run checks once (manual mode)
./check.fish # Default: tests + doctests + docs
./check.fish --check # Fast typecheck only (cargo check)
./check.fish --build # Compile only (cargo build)
./check.fish --clippy # Lint only (cargo clippy --all-targets)
./check.fish --fmt # Format changed files (cargo fmt + cargo-rustdoc-fmt)
./check.fish --test # Tests + doctests only
./check.fish --doc # Docs only (quick, no deps)
./check.fish --full # ALL checks + ICE escalation to toolchain update
For developers who prefer a multi-pane visual environment, the tmux dashboard combines
documentation monitoring with a focused development shell.
Comprehensive 2-Pane Development Dashboard:
┌─────────────────────────────────────────────────────────────┐
│ Tmux Session: r3bl (2-pane vertical layout) │
├─────────────────────────────────────────────────────────────┤
│ Top Pane: │
│ ./check.fish --watch-doc │
│ (Documentation watch mode for real-time feedback) │
├─────────────────────────────────────────────────────────────┤
│ Bottom Pane: │
│ (Empty, focused for your commands) │
└─────────────────────────────────────────────────────────────┘
Key Features:
tmux attach-session -t r3bl./check.fish --watch-doc which
triggers immediately on file changes to rebuild documentation.Usage:
# Start the development dashboard
fish run.fish dev-dashboard
# Reconnect to existing session from another terminal
tmux attach-session -t r3bl
# Kill the session when done
tmux kill-session -t r3bl
Comparison: Standalone vs Tmux Dashboard:
When to use each:
Both approaches use the check.fish script in different contexts - standalone for
comprehensive monitoring, integrated for a focused documentation dashboard.
This project uses platform-specific code gates (#[cfg(unix)], #[cfg(not(unix))]) for
Unix-specific functionality like terminal I/O. To verify these gates compile correctly on
Windows without needing a full Windows cross-compiler (mingw-w64), we use Rust's
metadata-only compilation.
How It Works:
The --emit=metadata flag tells rustc to stop after type checking and MIR generation,
skipping code generation and linking entirely. This validates all platform-specific cfg
gates without needing a linker for the target platform.
# Verify Windows cross-compilation
fish run.fish check-windows-build
# Or run directly:
cargo rustc -p r3bl_tui --target x86_64-pc-windows-gnu -- --emit=metadata
Prerequisites:
The Windows target is automatically installed by fish run.fish install-cargo-tools. To
install manually:
rustup target add x86_64-pc-windows-gnu
When to Use:
#[cfg(unix)] or #[cfg(not(unix))] conditional compilation gatesExample Output:
Verifying Windows cross-compilation for r3bl_tui...
Target: x86_64-pc-windows-gnu
Mode: metadata only (no linking required)
✅ Windows cross-compilation check passed
Platform-specific cfg gates compile correctly for Windows.
Technical Details:
This approach catches the most common cross-platform issues (missing cfg gates, type mismatches in platform-specific code) with minimal setup overhead.
Platform Backends: The TUI crate supports multiple backends:
Crossterm(cross-platform, default on macOS/Windows) andDirectToAnsi(provided byr3bl_tuiitself, Linux-native, ~18% better performance). We use cfg gates to ensure the selection of the correct backend for supported platforms. See [Platform-Specific Backends] for details.
This project includes three complementary scripts for comprehensive Rust toolchain management, each serving a specific purpose in the development workflow.
Concurrency Safety: Toolchain modification scripts (rust-toolchain-update.fish
and rust-toolchain-sync-to-toml.fish) use mkdir (atomic directory creation) to ensure
only one toolchain modification runs at a time. Validation scripts
(rust-toolchain-validate.fish and check.fish) are lock-free since they only read
toolchain state - multiple validations can run concurrently without conflict.
The key insight is understanding atomicity - when a system operation must check-and-act in a way that's guaranteed to be indivisible:
The Problem with File Existence Checks:
Traditional approaches try to check if a lock exists, then create it:
# UNSAFE - Race condition!
if [ ! -f lock ]; then
echo "timestamp" > temp
mv temp lock # TOCTOU race between check and move
fi
Between the check ([ ! -f lock ]) and the move (mv temp lock), another process can
slip in and also acquire the lock. This is called a Time-Of-Check-Time-Of-Use (TOCTOU)
race condition.
How mkdir Works - Atomic Check-and-Create:
mkdir is different. It combines the check and create into ONE indivisible kernel
operation:
# SAFE - Atomic operation
mkdir lock_dir # Check AND create in ONE kernel operation
# Only ONE process succeeds; all others fail
When mkdir runs, the kernel does:
Even with perfect timing and multiple processes starting simultaneously, only ONE can create the directory.
Technical Implementation:
# In script_lib.fish
if mkdir ./rust-toolchain-script.lock 2>/dev/null
# Lock acquired - this process has exclusive access
else
# Lock held by another process
fi
Key Advantages:
rm -rf rust-toolchain-script.lockThe locking mechanism uses:
rust-toolchain-script.lock/timestamp
for age trackingrust-toolchain-update.fish - Smart Validated Toolchain UpdatesIntelligently finds and validates a stable nightly toolchain, preferring older versions for stability while ensuring they don't have ICE (Internal Compiler Error) bugs.
# Via run.fish command
fish run.fish toolchain-update
# Or directly
./rust-toolchain-update.fish
What it does:
cargo clippy --all-targetscargo buildcargo test --all-targetscargo test --doccargo doc --workspace --no-depsrust-toolchain.toml to use the validated stable nightlyrust-analyzer component (required by IDEs and
cargo)notify-send):
stable-*)rustc-ice-*.txt) generated during validationcargo cache, build artifacts/home/nazmul/Downloads/rust-toolchain-update.logWhen to use:
systemd timer)Example output:
═══════════════════════════════════════════════════════
Starting search for stable toolchain
Strategy: Start 45 days ago, try progressively newer up to today
Search window: 2025-08-29 to 2025-10-13
═══════════════════════════════════════════════════════
Attempt 1/46
Trying toolchain: nightly-2025-08-29 (45 days ago)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Validating toolchain: nightly-2025-08-29
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Running validation step: `clippy`
⚠️ Command exited with code 101 (this is OK if not ICE)
✅ No ICE detected - continuing validation
...
✅ Toolchain nightly-2025-08-29 is STABLE (no ICE detected)
🎉 FOUND STABLE TOOLCHAIN: nightly-2025-08-29
Success notification sent
✅ Successfully updated `rust-toolchain.toml`
✅ Successfully installed `rust-analyzer` component
Removed 2 old toolchain(s)
Toolchains directory size before cleanup: 5.3G
Toolchains directory size after cleanup: 2.6G
rust-toolchain-sync-to-toml.fish - Sync to Existing ConfigSyncs your Rust environment to match whatever is specified in rust-toolchain.toml.
# Via run.fish command
fish run.fish toolchain-sync
# Or directly
./rust-toolchain-sync-to-toml.fish
What it does:
rust-toolchain.toml (doesn't modify it)rust-analyzer and rust-src components automatically (required by IDEs and
cargo)stable-*)/home/nazmul/Downloads/rust-toolchain-sync-to-toml.logWhen to use:
git checkout/reset/pull changes rust-toolchain.tomlrust-analyzer is missing for the current toolchainrust-analyzer failed to start"rust-toolchain.tomlKey difference from update script:
Example workflow:
# Weekly script updates TOML to nightly-2025-09-11
# But you need to stay on nightly-2025-09-05 for testing a specific feature
git checkout rust-toolchain.toml # Revert to 09-05
fish run.fish toolchain-sync # Install components for 09-05
# Now rust-analyzer works for 09-05
rust-toolchain-validate.fish - Unified Toolchain ValidationConsolidated validation script providing two modes: quick component check or comprehensive build+test validation.
# Quick mode: Fast component check (~1-2 seconds)
fish run.fish toolchain-validate
./rust-toolchain-validate.fish quick
# Complete mode: Full build+test validation (~5-10 minutes)
fish run.fish toolchain-validate-complete
./rust-toolchain-validate.fish complete
# View detailed help
./rust-toolchain-validate.fish
Mode Comparison:
Quick Mode Validation:
rustuprustup profile is default or completerust-analyzer component is presentrust-src component is presentrustc --version works (not corrupted)Complete Mode Validation:
cargo clippy --all-targets (no ICE)cargo build (no ICE)cargo test --all-targets (no ICE)cargo test --doc (no ICE)cargo doc --workspace --no-deps (no ICE)Return Codes:
0: ✅ Valid (quick) or Stable (complete)1: ❌ Not installed (quick) or ICE detected (complete)2: ⚠️ Missing components (quick only)3: ❌ Toolchain corrupted (quick only)4: ❌ Failed to read rust-toolchain.toml5: ❌ Wrong rustup profile (quick only)When to use Quick Mode:
sync-toolchainrust-analyzer not working?)When to use Complete Mode:
toolchain-update search (finding stable nightly)Integration with other toolchain scripts:
check.fish: Uses quick mode to check toolchain before running tests; calls
toolchain-sync if invalidrust-toolchain-sync-to-toml.fish: Performs quick validation after installing
componentsrust-toolchain-update.fish: Uses complete mode to find stable nightlyremove_toolchains.sh - Testing UtilityRemoves ALL Rust toolchains for testing upgrade progress display (⚠️ DESTRUCTIVE).
./remove_toolchains.sh
What it does:
rustup installation progressWhen to use:
edi and gitirustup download and installation progresscmdr/src/analytics_client/upgrade_check.rs functionalityRecovery after testing:
`rustup toolchain install stable && rustup default stable`
# Or
fish run.fish toolchain-update
⚠️ Warning: This is a destructive testing utility. Use only when you understand the implications and are prepared to reinstall toolchains.
All toolchain management scripts display detailed log file locations to stdout at
startup:
📋 Detailed log: /home/nazmul/Downloads/rust-toolchain-sync-to-toml.log
This makes it easy to monitor progress and check detailed logs after operations complete:
# Watch logs in real-time
tail -f /home/nazmul/Downloads/rust-toolchain-update.log
# Or review after completion
cat /home/nazmul/Downloads/rust-toolchain-sync-to-toml.log
The four scripts work together to provide a complete toolchain management solution:
Four complementary scripts:
rust-toolchain-validate.fish): Non-destructive validation of current
toolchainrust-toolchain-update.fish): Smart search for stable nightly with
comprehensive validationrust-toolchain-sync-to-toml.fish): Install toolchain matching
rust-toolchain.tomlremove_toolchains.sh): Testing utility to clean all toolchains
(destructive)Key benefits:
rust-toolchain.tomlupdate script designed to run weekly via systemd timersync script fixes environment after git operationsvalidate script enables automated health checks in CI/CD
pipelinesremove script enables testing upgrade workflowscheck.fish automatically validates and repairs toolchain
before running testsThe project uses a clean separation of concerns across three main scripts with shared utilities:
┌──────────────────────────────────────────────────────────────────────────┐
│ Bootstrap Flow │
└──────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐ calls ┌────────────────────────────────────┐
│ bootstrap.sh │──────────────►│ fish run.fish install-cargo-tools │
│ (OS-level) │ │ (Rust development tools) │
└─────────────────┘ └────────────────────────────────────┘
│ │
│ installs │ uses
▼ ▼
┌─────────────────┐ ┌──────────────────────────────────┐
│ rustup, │ │ script_lib.fish │
│ fish, fzf, │ │ (shared utility functions) │
│ inotify-tools │ │ │
└─────────────────┘ │ • install_windows_target │
│ • install_if_missing │
│ • install_cargo_tool │
│ • read_toolchain_from_toml │
│ • acquire_toolchain_lock │
Fully async Rust TUI engine 🦀. For powering AI/LLM coding agents, Cloud/SSH workflows & interactive CLIs: non-blocking readline, inline dialogs, React/Elm-style full-screen TUI, Markdown editor, PTY
Visão geral
Fully async Rust TUI engine 🦀. For powering AI/LLM coding agents, Cloud/SSH workflows & interactive CLIs: non-blocking readline, inline dialogs, React/Elm-style full-screen TUI, Markdown editor, PTY multiplexing & rust-analyzer MCP server.
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
R3bl Open Core roda localmente via stdio.
Última verificação: 2026-11-11. Fully async Rust TUI engine 🦀. For powering AI/LLM coding agents, Cloud/SSH workflows & interactive CLIs: non-blocking readline, inline dialogs, React/Elm-style full-screen TUI, Markdown editor, PTY multiplexing & rust-analyzer MCP server.