run-clippy
Run clippy linting, enforce comment punctuation rules, format code with cargo fmt, and verify module organization patterns. Use after code c
Open source Open in the app JSON README (API)
About
Run clippy linting, enforce comment punctuation rules, format code with cargo fmt, and verify module organization patterns. Use after code changes and before creating commits.
Details
- Kind
- Agent skills
- Topic
- Version control
- Publisher
- r3bl-org
- Origin
- majiayu
- Category
- ferramentas
- Stars
- 433
- Forks
- 31
- Open pull requests
- 14
- Last push
- 2026-09-04T20:40:56Z
- Repository state
- ativo
- Language
- Rust
- License
- Apache-2.0
- Added
- 2026-09-02 18:11:36
- Updated
- 2026-09-02 18:11:36
- Origin id
r3bl-org/r3bl-open-core/development/run-clippy@main
README
<!-- cspell:words ratatui Substeps Inclusivity inclusivity binstall intradoc warloc -->
# r3bl-open-core
<!--
<img
src="https://raw.githubusercontent.com/r3bl-org/r3bl-open-core/main/r3bl-term.svg?raw=true"
height="256px">
-->
<!-- R3BL TUI library & suite of apps focused on developer productivity -->
<!-- prettier-ignore-start -->
```text
██████╗ ██████╗ ██████╗
██╔══██╗██╔═══██╗██╔════╝
██████╔╝██║ ██║██║
██╔══██╗██║ ██║██║
██║ ██║╚██████╔╝╚██████╗
╚═╝ ╚═╝ ╚═════╝ ╚═════╝
```
<!-- prettier-ignore-end -->
<!-- BEGIN mktoc -->
- [r3bl-open-core](#r3bl-open-core)
- [Why R3BL TUI?](#why-r3bl-tui)
- [The Problem with Existing Solutions](#the-problem-with-existing-solutions)
- [The R3BL Solution: Web and Desktop App Inspired Terminal Apps](#the-r3bl-solution-web-and-desktop-app-inspired-terminal-apps)
- [Built-from-Scratch Primitives](#built-from-scratch-primitives)
- [Advanced Rendering & Styling](#advanced-rendering--styling)
- [Rich Component Ecosystem](#rich-component-ecosystem)
- [Welcome to the monorepo and workspace](#welcome-to-the-monorepo-and-workspace)
- [This workspace contains crates for building TUI, CLI, TTY apps](#this-workspace-contains-crates-for-building-tui-cli-tty-apps)
- [Full TUI (async, raw mode, full screen) for immersive TUI 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-choice-based-user-interaction)
- [Partial TUI (async, partial raw mode, async readline) for async REPL](#partial-tui-async-partial-raw-mode-async-readline-for-async-repl)
- [Terminal multiplexer](#terminal-multiplexer)
- [Power via composition](#power-via-composition)
- [Main library crate](#main-library-crate)
- [Main binary crate](#main-binary-crate)
- [Interactive git workflows made easy.](#interactive-git-workflows-made-easy)
- [Beautiful Markdown editor with advanced rendering and editing features.](#beautiful-markdown-editor-with-advanced-rendering-and-editing-features)
- [Project Task Organization](#project-task-organization)
- [Task Management Files](#task-management-files)
- [Task File Format](#task-file-format)
- [Implementation Plan](#implementation-plan)
- [Step 0: Do Something [STATUS]](#step-0-do-something-status)
- [Step 0.0: Do Subtask [STATUS]](#step-00-do-subtask-status)
- [Step 0.1: Do Another Subtask [STATUS]](#step-01-do-another-subtask-status)
- [Step 1: Do Something Else [STATUS]](#step-1-do-something-else-status)
- [Task Workflow Commands](#task-workflow-commands)
- [Workflow Connection](#workflow-connection)
- [Development Tools Integration](#development-tools-integration)
- [Documentation and Planning](#documentation-and-planning)
- [Documentation Philosophy](#documentation-philosophy)
- [Release and Contribution Guides](#release-and-contribution-guides)
- [Technical Design Documents](#technical-design-documents)
- [Learn how these crates are built, provide feedback](#learn-how-these-crates-are-built-provide-feedback)
- [Quick Start](#quick-start)
- [Automated Setup (Recommended)](#automated-setup-recommended)
- [Run the bootstrap script](#run-the-bootstrap-script)
- [Manual Setup](#manual-setup)
- [Install `fish` and `fzf` (via package manager)](#install-fish-and-fzf-via-package-manager)
- [Ubuntu/Debian: sudo apt install fish fzf](#ubuntudebian-sudo-apt-install-fish-fzf)
- [macOS: brew install fish fzf](#macos-brew-install-fish-fzf)
- [Or run `./bootstrap.sh` for automatic detection](#or-run-bootstrapsh-for-automatic-detection)
- [Install Rust development tools (after OS dependencies)](#install-rust-development-tools-after-os-dependencies)
- [IDE Setup and Extensions](#ide-setup-and-extensions)
- [R3BL VSCode Extensions](#r3bl-vscode-extensions)
- [Install extensions (works with both VSCode and VSCode Insiders)](#install-extensions-works-with-both-vscode-and-vscode-insiders)
- [AI (LLM) Coding Agent Integration (Optional)](#ai-llm-coding-agent-integration-optional)
- [Build the workspace and run tests](#build-the-workspace-and-run-tests)
- [Key Commands](#key-commands)
- [Cargo Target Directory Isolation for IDE/Tool Performance](#cargo-target-directory-isolation-for-idetool-performance)
- [The Problem: Cargo Lock Contention](#the-problem-cargo-lock-contention)
- [The Solution: Separate Build Artifacts](#the-solution-separate-build-artifacts)
- [Configuration by Tool](#configuration-by-tool)
- [Benefits](#benefits)
- [Example Workflow Setup](#example-workflow-setup)
- [Terminal 2: File watcher with automatic tests](#terminal-2-file-watcher-with-automatic-tests)
- [Terminal 3: Run AI (LLM) coding agent](#terminal-3-run-ai-llm-coding-agent)
- [Terminal 4: Run bacon](#terminal-4-run-bacon)
- [Result: All four run in parallel, zero blocking](#result-all-four-run-in-parallel-zero-blocking)
- [Disk Space Management](#disk-space-management)
- [Clean individual tool builds](#clean-individual-tool-builds)
- [Full cleanup (nuclear option)](#full-cleanup-nuclear-option)
- [Troubleshooting](#troubleshooting)
- [VSCode: Check .vscode/settings.json](#vscode-check-vscodesettingsjson)
- [Test with explicit path](#test-with-explicit-path)
- [Incremental Compilation Management](#incremental-compilation-management)
- [Rebuild cleanly](#rebuild-cleanly)
- [Bacon Development Tools](#bacon-development-tools)
- [Automated Development Monitoring](#automated-development-monitoring)
- [Option 1: Lightweight Watch Mode (Recommended for Most Users)](#option-1-lightweight-watch-mode-recommended-for-most-users)
- [Start watch mode](#start-watch-mode)
- [Or run checks once (manual mode)](#or-run-checks-once-manual-mode)
- [Option 2: Comprehensive Tmux Dashboard](#option-2-comprehensive-tmux-dashboard)
- [Tmux Development Dashboard](#tmux-development-dashboard)
- [Reconnect to existing session from another terminal](#reconnect-to-existing-session-from-another-terminal)
- [Kill the session when done](#kill-the-session-when-done)
- [Cross-Platform Verification (Windows)](#cross-platform-verification-windows)
- [Or run directly:](#or-run-directly)
- [Rust Toolchain Management](#rust-toolchain-management)
- [Why mkdir for Locking?](#why-mkdir-for-locking)
- [Only ONE process succeeds; all others fail](#only-one-process-succeeds-all-others-fail)
- [1. `rust-toolchain-update.fish` - Smart Validated Toolchain Updates](#1-rust-toolchain-updatefish---smart-validated-toolchain-updates)
- [Or directly](#or-directly)
- [2. `rust-toolchain-sync-to-toml.fish` - Sync to Existing Config](#2-rust-toolchain-sync-to-tomlfish---sync-to-existing-config)
- [Or directly](#or-directly-1)
- [But you need to stay on nightly-2025-09-05 for testing a specific feature](#but-you-need-to-stay-on-nightly-2025-09-05-for-testing-a-specific-feature)
- [Now rust-analyzer works for 09-05](#now-rust-analyzer-works-for-09-05)
- [3. `rust-toolchain-validate.fish` - Unified Toolchain Validation](#3-rust-toolchain-validatefish---unified-toolchain-validation)
- [Complete mode: Full build+test validation (~5-10 minutes)](#complete-mode-full-buildtest-validation-~5-10-minutes)
- [View detailed help](#view-detailed-help)
- [4. `remove_toolchains.sh` - Testing Utility](#4-remove_toolchainssh---testing-utility)
- [Or](#or)
- [Log File Output](#log-file-output)
- [Or review after completion](#or-review-after-completion)
- [Comprehensive Toolchain Management System](#comprehensive-toolchain-management-system)
- [Unified Script Architecture](#unified-script-architecture)
- [Star History](#star-history)
- [Archive](#archive)
<!-- END mktoc -->
## Why R3BL TUI?
After leaving Google in 2021, I ([Nazmul Idris](https://developerlife.com/about-me/))
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()`](https://man7.org/linux/man-pages/man3/readline.3.html) on Linux/macOS or
Windows [`ReadConsole()`](https://learn.microsoft.com/en-us/windows/console/readconsole).
R3BL TUI is fundamentally different from [`vim`](https://www.vim.org/),
[`neovim`](https://neovim.io/), and [`ratatui`](https://ratatui.rs/) 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](https://nodejs.org/) with
[ink](https://developerlife.com/2021/11/25/ink-v3-advanced-ui-components/), 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](https://react.dev/),
[SolidJS](https://www.solidjs.com/), [Elm](https://guide.elm-lang.org/architecture/),
[iced-rs](https://docs.rs/iced/latest/iced/),
[Jetpack Compose](https://developer.android.com/compose),
[JSX](https://ui.dev/imperative-vs-declarative-programming),
[CSS](https://www.w3.org/TR/CSS/#css), but making everything async (so they can be run
in parallel & concurrent via [Tokio](https://crates.io/crates/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](https://www.w3.org/TR/CSS/#css) &
[JSX](https://ui.dev/imperative-vs-declarative-programming).
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](https://en.wikipedia.org/wiki/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](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html). These crates are
likely published to [crates.io](https://crates.io/crates/r3bl_tui). Together, they form a
[Rust workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html).
Here's the [changelog](https://github.com/r3bl-org/r3bl-open-core/blob/main/CHANGELOG.md)
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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/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](https://www.youtube.com/playlist?list=PLofhE49PEwmw3MKOU1Kn3xbP4FRQR4Mb3)
- [Build with Naz: async readline](https://www.youtube.com/playlist?list=PLofhE49PEwmwelPkhfiqdFQ9IXnmGdnSE)
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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/src/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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr) crate. You can
install & run this with the following command:
```bash
cargo install r3bl-cmdr
edi
```
### Partial TUI (async, partial raw mode, async readline) for choice based user interaction
[`choose`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/readline_async/choose_api.rs)
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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr) crate. You can
install & run this with the following command:
```bash
cargo install r3bl-cmdr
giti
```
### Partial TUI (async, partial raw mode, async readline) for async REPL
[`readline_async`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/readline_async/readline_async_api.rs)
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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr) crate. You can
install & run this with the following command:
```bash
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()`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/core/pty/pty_mux/mux.rs)
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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples/pty_mux_example.rs)
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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/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`](https://github.com/r3bl-org/r3bl-open-core/tree/main/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:
```bash
cargo install r3bl-cmdr
# Interactive git workflows made easy.
giti --version
# Beautiful Markdown editor with advanced rendering and editing features.
edi --version
```
### Build infrastructure and developer tooling crate
The [`r3bl-build-infra`](https://github.com/r3bl-org/r3bl-open-core/tree/main/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:
```bash
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/`](https://github.com/r3bl-org/r3bl-open-core/tree/main/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`](https://github.com/r3bl-org/r3bl-open-core/blob/main/task/AGENTS.md):
**Structure:**
```markdown
# 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`](https://github.com/r3bl-org/r3bl-open-core/blob/main/AGENTS.md#task-tracking-system))
manages the task lifecycle:
**Create a new task:**
```bash
/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:**
```bash
/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:**
```bash
/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 decisions,
design documents
- **Planning to Active Work**: Complex features are documented in `docs/` first.
- **Tactical Execution**:
1. Complex tasks get detailed planning → `/r3bl-task create` → `./task/task_*.md`
2. Work progresses through hierarchical steps with `/r3bl-task update` marking
progress
3. Completion → Task moved to `./task/done/` via `/r3bl-task update`
This approach (docs → ./task/) ensures strategic planning, tactical planning, and detailed
execution are well-organized and connected.
### Development Tools Integration
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](#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.
## Documentation and Planning
We invest heavily in documentation quality because it is the right thing to do. Also,
[research shows](https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/why-good-docs-matter.md)
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](https://rust-lang.github.io/rfcs/1824-crates.io-default-ranking.html)), and
91% of practitioners depend on documentation for adoption decisions
([2024 study](https://arxiv.org/html/2403.03819v1)). 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](https://github.com/r3bl-org/r3bl-open-core/blob/main/.agents/skills/write-documentation/SKILL.md).
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](https://github.com/r3bl-org/r3bl-open-core/blob/main/.agents/skills/write-documentation/SKILL.md#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/`](https://github.com/r3bl-org/r3bl-open-core/tree/main/docs) folder contains
comprehensive documentation for this project, including:
### Documentation Philosophy
- [`why-good-docs-matter.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/why-good-docs-matter.md) -
Research evidence for why we invest heavily in documentation quality
### Release and Contribution Guides
- [`release-guide.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/release-guide.md) -
Step-by-step guide for releasing new versions
- [`contributing_guides/`](https://github.com/r3bl-org/r3bl-open-core/tree/main/docs/contributing_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`)
### Technical Design Documents
- 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
## Learn how these crates are built, provide feedback
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](https://www.youtube.com/@developerlifecom). Please consider
[subscribing](https://www.youtube.com/channel/UCMcsxfCwzwDevc3NRqFgfEg?sub_confirmation=1).
## Quick Start
### Automated Setup (Recommended)
Use the bootstrap script to automatically install all required tools:
```bash
# 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`](https://github.com/r3bl-org/r3bl-open-core/blob/main/bootstrap.sh)
script handles **OS-level setup** with a clean main function structure and will:
- **Cross-Platform Support**: Works on **macOS** (Homebrew) and **Linux** including Ubuntu
(apt), Fedora (dnf), Arch (pacman), openSUSE (zypper), and Alpine (apk)
- **Core Rust Installation**: Install Rust toolchain (`rustup`) and ensure `cargo` is in
`PATH`
- **Development Shell**: Install `Fish` shell and `fzf` for interactive development
- **File Watching**: Install file watchers (`inotifywait` on Linux, `fswatch` on macOS)
- **Development Utilities**: Install `htop`, `screen`, `tmux` for system monitoring
- **Node.js Ecosystem**: Install `Node.js` and `npm` (for Markdown formatting via Prettier
and local documentation serving)
- **AI (LLM) Integration (Optional)**: If you choose to use an AI coding agent, the repo
supports `Antigravity CLI` (`agy`), or any tool of your choice
- **Rust Development Tools Setup**: Call `fish run.fish install-cargo-tools` for all
Rust-specific `cargo` tooling
**Architecture**: Uses clear function separation with `main()` orchestrator and dedicated
functions for each concern (`install_rustup`, `install_clang`, `install_shell_tools`,
etc.)
### Manual Setup
If you prefer manual installation or are on Windows:
```bash
# 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)
- **Core Development Tools**: `bacon`, `flamegraph`, `inferno`
- **Workspace Management**: `cargo-workspaces`, `cargo-cache`, `cargo-update`
- **Code Quality & Link Checking**: `cargo-deny`, `cargo-unmaintained`, `cargo-expand`,
`cargo-readme`, `lychee`
- **Language Server Components**: `rust-analyzer` component, `rust-src`
**From local source (via `cargo install --path`):**
- **cmdr**: `edi`, `giti`, `rc` binaries (calls `run.fish install-cmdr`)
- **build-infra**: `cargo-rustdoc-fmt` (calls `run.fish install-build-infra`)
- **rust-analyzer-mcp-server**: `rust-analyzer-mcp-server` MCP binary (calls `run.fish install-rust-analyzer-mcp-server`)
**Features:**
- **Smart Installation**: Uses `cargo-binstall` for speed with fallback to
`cargo install --locked`
- **Local Source Rebuild**: Always rebuilds `cmdr`, `build-infra`, and `rust-analyzer-mcp-server` from source with
current toolchain
- **Shared Utilities**: Leverages utility functions from `script_lib.fish` for consistency
## IDE Setup and Extensions
### R3BL VSCode Extensions
For 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 Spaces** - Organize and switch between collections of editor tabs for different
work contexts (e.g., one space for editing features, one for writing documentation, one
for debugging). Complements the `./task/` file management system by helping you organize
your editor sessions.
- **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:**
```bash
# 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:**
- VSCode or VSCode Insiders installed
- Bash shell (for running install.sh)
**Post-installation:**
1. Restart VSCode
2. Select the R3BL Theme: `Ctrl+Shift+P` → "Preferences: Color Theme" → "R3BL Theme"
3. Configure copyright settings if needed
The R3BL VSCode extensions work seamlessly with the existing development tools mentioned
in this guide, including `rust-analyzer`, `bacon`, and the comprehensive development
workflow.
### AI (LLM) Coding Agent Integration (Optional)
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`](#automated-development-monitoring): 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/`](build-infra/README.md) folder.
- [R3BL VSCode extensions](#r3bl-vscode-extensions): Enhancements for the developer's
environment (Themes, Copyright management, etc).
- **Core Rust Stack**: `rustup`, `cargo`, `rust-analyzer`, `clippy`, `rustfmt`.
- **CLI Power Tools**: `fzf` (fuzzy finding), `btop` (monitoring), `tmux` (multiplexing),
`flamegraph` (profiling), `inferno` (stack collapse), `lychee` (link checking).
- **Workspace Utilities**: `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:
1. Explore the existing codebase with confidence.
2. Run tests, do profiling, and measure optimizations.
3. Refactor code or generate new code that adheres to our engineering standards. There are
manual review steps and many other guardrails in place in the
[`skills`](.agents/skills/) themselves.
**How it works:**
Using an AI coding agent is completely optional. If you do choose to use an AI (LLM)
coding agent or harness (such as `Antigravity CLI` (`agy`), or any tool of your choice),
point it to the instructions in
[`AGENTS.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/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`](rust-analyzer-mcp-server/)
([crates.io](https://crates.io/crates/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:
| Skill | Purpose |
| --------------------- | ---------------------------------------------------------------- |
| `check-code-quality` | Comprehensive quality checklist (check → build → clippy → tests) |
| `run-clippy` | Linting, comment punctuation, cargo fmt |
| `write-documentation` | Rustdoc conventions, intra-doc links, constant formatting |
| `organize-modules` | Private modules with public re-exports pattern |
| `check-bounds-safety` | Type-safe Index/Length patterns for bounds-sensitive code |
| `analyze-performance` | Flamegraph-based performance regression detection |
| `design-philosophy` | Core principles: cognitive load, type safety, abstraction worth |
**Slash Commands:**
Invoke `skills` directly in your AI (LLM) coding agent:
| Command | Action |
| --------------------- | ----------------------------------------------------------------------- |
| `/check` | Run comprehensive code quality checks |
| `/docs` | Documentation build and formatting |
| `/clippy` | Code style and linting |
| `/fix-intradoc-links` | Fix rustdoc intra-doc links |
| `/check-regression` | Detect performance regressions |
| `/analyze-logs` | Analyze log files (strips ANSI codes) |
| `/r3bl-task` | [Task management](#r3bl-vscode-extensions) (create, update, load, done) |
**AI (LLM) Coding Agent Synergy: R3BL VSCode Extensions**
For the best experience, install the [R3BL VSCode Extensions](#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:
| Extension | AI (LLM) Coding Agent Synergy |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **R3BL Theme** | Optimized dark theme for long coding sessions with AI (LLM) coding agents |
| **R3BL Task Spaces** | Organize editor tabs by task context — switch between feature work, debugging, and documentation while the agent tracks your `./task/` files |
| **R3BL Copy Selection Path** | Press `Alt+O` to copy file paths with line ranges — paste directly into your agent for precise code references |
## Build the workspace and run tests
There's a unified [`fish`](https://fishshell.com/) 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`](https://github.com/r3bl-org/r3bl-open-core/blob/main/run.fish). To see
all available commands:
```bash
fish run.fish
```
### Key Commands
| 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 install-cargo-tools` | Install all dev tools (`crates.io` + local source packages) |
| `fish run.fish update-cargo-tools` | Update all tools (`crates.io` + rebuild local source packages) |
| `fish run.fish install-cmdr` | Install `cmdr` binaries (`edi`, `giti`, `rc`) from source |
| `fish run.fish install-build-infra` | Install `build-infra` tools (`cargo-rustdoc-fmt`) from source |
| `fish run.fish test-watch [pattern]` | Watch for file changes and run specific test |
| `fish run.fish run-examples` | Run TUI examples interactively |
| `fish run.fish run-examples-flamegraph-svg` | Generate SVG flamegraph for performance analysis |
| `fish run.fish run-examples-flamegraph-fold [--benchmark]` | Generate perf-folded format for analysis (use `--benchmark` for reproducible profiling) |
| `fish run.fish bench` | Run benchmarks |
| `fish run.fish run-binaries` | Run `cmdr` binaries (`edi`, `giti`, `rc`) interactively |
| `fish run.fish dev-dashboard` | Start 2-pane `tmux` development dashboard (tests, docs, checks) |
| `fish run.fish check-full` | Run comprehensive checks (tests, doctests, docs, toolchain validation) |
| `fish run.fish check-windows-build` | Verify Windows cross-compilation (platform `cfg` gates) |
| `fish run.fish toolchain-validate` | Quick toolchain validation (components only, ~1-2 seconds) |
| `fish run.fish toolchain-validate-complete` | Complete toolchain validation (full build+test, ~5-10 minutes) |
| `fish run.fish toolchain-update` | Update Rust to month-old nightly toolchain with cleanup |
| `fish run.fish toolchain-sync` | Sync Rust environment to match `rust-toolchain.toml` |
| `fish run.fish toolchain-remove` | Remove ALL toolchains (⚠️ destructive testing utility) |
> **TUI Testing**: The `r3bl_tui` crate uses PTY-based testing for accurate terminal I/O
> verification. See the
> [PTY Testing Infrastructure](./tui/README.md#pty-testing-infrastructure) section in the
> TUI README for details on writing and running TUI tests.
### Cargo Target Directory Isolation for IDE/Tool Performance
**Critical Optimization**: When multiple development tools run `cargo` simultaneously
(IDE, terminal, file watcher, CI), they compete for locks on the shared `target/`
directory. This causes severe responsiveness issues as each tool waits for others to
complete. Isolating build artifacts by tool eliminates this bottleneck completely.
#### The Problem: Cargo Lock Contention
When you have multiple `cargo` instances running:
- **VSCode rust-analyzer**: Runs `cargo check` continuously in background
- **File watcher** (`check.fish`, `bacon`): Triggers `cargo` tests, doc builds, etc. on
every file save
- **Terminal**: You run manual `cargo` commands, or optionally use an AI (LLM) coding
agent (such as `Antigravity CLI` (`agy`), etc.)
All these access the same `target/` directory:
```
target/
├── debug/
├── release/
└── .rustc_info.json # ← Lock contention here
```
When one tool locks `target/`, all others wait. This cascades into a "traffic jam" where
everything becomes unresponsive.
#### The Solution: Separate Build Artifacts
Configure each tool to use its own target directory. Rust supports this via the
`CARGO_TARGET_DIR` environment variable:
```
target/
├── vscode/ # VSCode rust-analyzer builds
├── agents/ # Optional AI (LLM) coding agent builds
├── check/ # check.fish file watcher builds
└── cli/ # Terminal manual builds (optional)
```
Now tools build in parallel without interfering with each other.
#### Configuration by Tool
Generally speaking you can just add `CARGO_TARGET_DIR=target/XYZ` in the command. For
example, you can run your AI (LLM) coding agent with the `CARGO_TARGET_DIR` environment
variable set, and all the `cargo` commands spawned by it will have their own target
directory to work with:
```bash
CARGO_TARGET_DIR=target/agents <agent-command>
```
You can add this to an alias, add it to scripts (like `check.fish` does via
`set -gx CARGO_TARGET_DIR target/check`) or you can configure settings in your tool of
choice.
In VSCode, you can add the following to `.vscode/settings.json`:
```json
{
"rust-analyzer.cargo.targetDir": true
}
```
#### Benefits
| Benefit | Impact |
| -------------------- | ----------------------------------------------------------------------------- |
| **Zero Contention** | Tools run in parallel without waiting on locks |
| **Responsive IDE** | `rust-analyzer` completes checks while you code (not blocked by file watcher) |
| **Faster Feedback** | Terminal `cargo` commands complete instantly (not queued behind IDE checks) |
| **Parallel Testing** | `bacon` + `check.fish` both run, providing redundant test feedback |
| **Disk Space** | ~2-3GB per tool (manageable with cleanup) |
#### Example Workflow Setup
Here's a typical productive development workflow setup:
```bash
# Terminal 1: Running your IDE (VSCode with rust-analyzer)
CARGO_TARGET_DIR=target/vscode code .
# Terminal 2: File watcher with automatic tests
check.fish --watch-test # Runs with: CARGO_TARGET_DIR=target/check
# Terminal 3: Optional AI (LLM) coding agent (e.g. agy, or your tool of choice)
CARGO_TARGET_DIR=target/agents <agent-command>
# Terminal 4: Run bacon
CARGO_TARGET_DIR=target/bacon bacon doc --headless
# Result: All four run in parallel, zero blocking
```
Before this optimization, Terminal 3 would hang waiting for Terminal 1 & 2 to release the
`target/` lock.
#### Disk Space Management
Each tool caches ~2-3GB of build artifacts. With 4 tools, expect ~10-12GB total. To
manage:
```bash
# View size of each target directory
du -sh target/*/
# Clean individual tool builds
rm -rf target/vscode
rm -rf target/agents
rm -rf target/check
# Full cleanup (nuclear option)
rm -rf target/
```
#### Troubleshooting
**Syntax errors still appear in IDE but code works in terminal?**
Your IDE and terminal are using different target directories. Verify `CARGO_TARGET_DIR`
configuration:
```bash
# Check what each tool sees
echo $CARGO_TARGET_DIR # Terminal value
# VSCode: Check .vscode/settings.json
```
**Build artifacts aren't being reused across tools?**
Each tool has its own `target/` directory by design. This is correct - the slight disk
space overhead is worth the responsiveness gain. If you need to share builds, unset
`CARGO_TARGET_DIR` (not recommended for development).
**"Target directory not found" error?**
`cargo` automatically creates the directory. If you see this error, verify the path is
writable and the environment variable is set correctly:
```bash
# Verify the variable is actually set
env | grep CARGO_TARGET_DIR
# Test with explicit path
CARGO_TARGET_DIR=/tmp/test cargo build
```
#### Incremental Compilation Management
Incremental compilation is disabled globally (`incremental = false` in
`.cargo/config.toml`) to avoid issues with the `rustc` dependency graph on nightly builds:
```toml
# .cargo/config.toml
[build]
incremental = false # Disable to avoid rustc dep graph ICE on nightly
```
**Why disable incremental compilation?**
- The nightly compiler has occasional bugs with the dependency graph in incremental mode
- These bugs can cause Internal Compiler Errors (ICE) like
"mir_drops_elaborated_and_const_checked"
- Disabling it globally ensures stable builds across all `cargo` invocations
- The performance impact is acceptable for development workflows
**If you encounter ICE errors anyway:**
```bash
# 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.
### Bacon Development Tools
This project includes [bacon](https://dystroy.org/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
**Available Bacon Commands:**
**Code Quality & Checking:**
| Command | Description |
| ------------------ | ----------------------------------------------------------- |
| `bacon check` | Fast typecheck of default target |
| `bacon check-all` | Typecheck all targets (lib, bins, tests, benches, examples) |
| `bacon clippy` | Run `clippy` lints on default target |
| `bacon clippy-all` | Run `clippy` lints on all targets (keybinding: `c`) |
**Testing:**
| Command | Workflow | Description |
| --------------------------------- | ----------- | -------------------------------------------------------------------------- |
| `bacon test` | Interactive | Run all tests with `cargo test` (includes unit, integration, and doctests) |
| `bacon test -- <pattern>` | Interactive | Run specific test matching pattern |
| `bacon doctests` | Interactive | Run only documentation tests (`cargo test --doc`) |
| `bacon test --headless --summary` | Background | Silent test runner providing only pass/fail status |
**Documentation:**
| Command | Workflow | Description |
| -------------------------------- | ----------- | ------------------------------------------------- |
| `bacon doc` | Interactive | Generate documentation with detailed output |
| `bacon doc --headless --summary` | Background | Silent doc builder answering "did docs generate?" |
| `bacon doc-open` | Interactive | Generate docs and open in browser |
**Running & Benchmarking:**
| Command | Description |
| ---------------------------- | ----------------------------------------------------------------------- |
| `bacon run` | Build and run the project in background |
| `bacon run-long` | Run long-running processes (e.g., servers) with auto-restart on changes |
| `bacon ex -- <example_name>` | Run specific example (e.g., `bacon ex -- my-example`) |
| `bacon bench` | Run performance benchmarks |
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
**Testing Notes:**
- Use `bacon test` to run all tests (includes unit, integration, and doctests)
- Use `bacon doctests` or `bacon test --doc` to run only documentation tests
### Automated Development Monitoring
The project provides two complementary approaches for continuous monitoring during
development - choose based on your workflow preferences:
#### Option 1: Lightweight Watch Mode (Recommended for Most Users)
For developers who want automated monitoring without the overhead of `tmux`, use the
standalone check script:
```bash
./check.fish --watch
```
**What it does:**
- **Monitors source directories**: Watches `cmdr/src/`, `analytics_schema/src/`, and
`tui/src/` for changes
- **Event-driven execution**: Triggers immediately on file changes (no polling delay)
- **Intelligent debouncing**: 1-second delay prevents rapid re-runs during saves
- **Comprehensive checks**: Runs tests, doctests, and doc builds automatically
- **Clean progress output**: Shows stage-by-stage progress without verbose `cargo` logs
- **Automatic toolchain validation**: Validates and repairs Rust toolchain before checks
- **ICE recovery**: Detects and recovers from Internal Compiler Errors automatically
- **ICE escalation**: On persistent ICE, escalates to `rust-toolchain-update.fish` to find
a stable nightly
- **Continuous operation**: Keeps watching even if checks fail (perfect for iterative
development)
**Example 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:**
- **Single window**: No `tmux` complexity - just one terminal
- **Immediate feedback**: 1-second response time after file saves
- **Low overhead**: Minimal resource usage compared to running multiple monitors
- **Perfect for focus**: Clean output doesn't distract from your editor
**Event 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:**
```bash
# 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
```
#### Option 2: Comprehensive Tmux Dashboard
### Tmux Development Dashboard
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:**
- **Persistent Session**: Session name "r3bl" - reconnect from other terminals with
`tmux attach-session -t r3bl`
- **Watch Mode Documentation**: The top pane runs `./check.fish --watch-doc` which
triggers immediately on file changes to rebuild documentation.
- **Focused Development**: The bottom pane is focused and ready for your manual commands,
tests, or binary execution.
- **Persistent Session**: survives terminal disconnects, allowing you to pick up exactly
where you left off.
**Usage:**
```bash
# 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:**
| Aspect | `./check.fish --watch` | Tmux Dashboard |
| ---------------------- | ----------------------------------- | ---------------------------------- |
| **Setup Complexity** | Single command, one window | `tmux` session with 2 panes |
| **Screen Real Estate** | Minimal (one terminal) | Standard (vertical split) |
| **Monitoring Scope** | Comprehensive (tests+docs+doctests) | Documentation focused + open shell |
| **Visual Separation** | Sequential output in one stream | Parallel output in dedicated panes |
| **Ideal For** | Focused development, laptop screens | Continuous documentation feedback |
| **Tmux Knowledge** | Not required | Helpful for navigation |
| **Resource Usage** | Lower (one monitor) | Moderate (monitoring + open shell) |
| **Event-Driven** | Yes (file system events) | Yes (top pane) |
**When to use each:**
- **Use standalone watch**: When you want simple, focused monitoring of tests and docs in
a single terminal.
- **Use tmux dashboard**: When you want continuous documentation feedback while
maintaining an open shell for commands.
Both approaches use the `check.fish` script in different contexts - standalone for
comprehensive monitoring, integrated for a focused documentation dashboard.
### Cross-Platform Verification (Windows)
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 checkin