{"id":26175209,"url":"https://github.com/r3bl-org/r3bl-open-core","last_synced_at":"2026-02-17T02:30:54.593Z","repository":{"id":37269374,"uuid":"462913472","full_name":"r3bl-org/r3bl-open-core","owner":"r3bl-org","description":"TUI framework and developer productivity apps in Rust 🦀","archived":false,"fork":false,"pushed_at":"2025-05-08T14:43:07.000Z","size":69721,"stargazers_count":363,"open_issues_count":67,"forks_count":23,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-08T15:37:20.217Z","etag":null,"topics":["cli","cli-app","command-line","concurrent","console","editor","hacktoberfest","linux","macos","parallel","productivity","rust","syntax-highlighting","terminal","tui","tuify","vte","windows"],"latest_commit_sha":null,"homepage":"https://r3bl.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r3bl-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"nazmulidris"}},"created_at":"2022-02-23T21:35:10.000Z","updated_at":"2025-05-08T14:43:12.000Z","dependencies_parsed_at":"2023-11-16T12:10:49.992Z","dependency_job_id":"8b7875ea-ddc2-44db-bd12-33aaab822534","html_url":"https://github.com/r3bl-org/r3bl-open-core","commit_stats":{"total_commits":1090,"total_committers":13,"mean_commits":83.84615384615384,"dds":0.05229357798165135,"last_synced_commit":"7a629389d779634f3e2387177201d9df0fed3aea"},"previous_names":["r3bl-org/r3bl-rs-utils","r3bl-org/r3bl-open-core","r3bl-org/r3bl_rs_utils"],"tags_count":157,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r3bl-org%2Fr3bl-open-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r3bl-org%2Fr3bl-open-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r3bl-org%2Fr3bl-open-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r3bl-org%2Fr3bl-open-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r3bl-org","download_url":"https://codeload.github.com/r3bl-org/r3bl-open-core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254168985,"owners_count":22026207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-app","command-line","concurrent","console","editor","hacktoberfest","linux","macos","parallel","productivity","rust","syntax-highlighting","terminal","tui","tuify","vte","windows"],"created_at":"2025-03-11T20:38:24.696Z","updated_at":"2026-02-17T02:30:54.582Z","avatar_url":"https://github.com/r3bl-org.png","language":"Rust","readme":"\u003c!-- cspell:words ratatui --\u003e\n\n# r3bl-open-core\n\n\u003cimg\nsrc=\"https://raw.githubusercontent.com/r3bl-org/r3bl-open-core/main/r3bl-term.svg?raw=true\"\nheight=\"256px\"\u003e\n\n\u003c!-- R3BL TUI library \u0026 suite of apps focused on developer productivity --\u003e\n\n\u003c!-- prettier-ignore-start --\u003e\n```\n██████╗ ██████╗ ██████╗ ██╗         ████████╗██╗   ██╗██╗\n██╔══██╗╚════██╗██╔══██╗██║         ╚══██╔══╝██║   ██║██║\n██████╔╝ █████╔╝██████╔╝██║            ██║   ██║   ██║██║\n██╔══██╗ ╚═══██╗██╔══██╗██║            ██║   ██║   ██║██║\n██║  ██║██████╔╝██████╔╝███████╗       ██║   ╚██████╔╝██║\n╚═╝  ╚═╝╚═════╝ ╚═════╝ ╚══════╝       ╚═╝    ╚═════╝ ╚═╝\n```\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of contents:**\n\n- [Why R3BL TUI?](#why-r3bl-tui)\n  - [The Problem with Existing Solutions](#the-problem-with-existing-solutions)\n  - [The R3BL Solution: Web and Desktop App Inspired Terminal Apps](#the-r3bl-solution-web-and-desktop-app-inspired-terminal-apps)\n  - [Built-from-Scratch Primitives](#built-from-scratch-primitives)\n  - [Advanced Rendering \u0026 Styling](#advanced-rendering--styling)\n  - [Rich Component Ecosystem](#rich-component-ecosystem)\n- [Welcome to the monorepo and workspace](#welcome-to-the-monorepo-and-workspace)\n- [This workspace contains crates for building TUI, CLI, TTY apps](#this-workspace-contains-crates-for-building-tui-cli-tty-apps)\n  - [Full TUI (async, raw mode, full screen) for immersive TUI apps](#full-tui-async-raw-mode-full-screen-for-immersive-tui-apps)\n  - [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)\n  - [Partial TUI (async, partial raw mode, async readline) for async REPL](#partial-tui-async-partial-raw-mode-async-readline-for-async-repl)\n- [Power via composition](#power-via-composition)\n  - [Main library crate](#main-library-crate)\n  - [Main binary crate](#main-binary-crate)\n- [Project Task Organization](#project-task-organization)\n  - [Task Management Files](#task-management-files)\n  - [Task File Format](#task-file-format)\n  - [Task Workflow Commands](#task-workflow-commands)\n  - [Workflow Connection](#workflow-connection)\n  - [Development Tools Integration](#development-tools-integration)\n- [Documentation and Planning](#documentation-and-planning)\n  - [Release and Contribution Guides](#release-and-contribution-guides)\n  - [Technical Design Documents](#technical-design-documents)\n- [Learn how these crates are built, provide feedback](#learn-how-these-crates-are-built-provide-feedback)\n- [Quick Start](#quick-start)\n  - [Automated Setup (Recommended)](#automated-setup-recommended)\n  - [Manual Setup](#manual-setup)\n- [IDE Setup and Extensions](#ide-setup-and-extensions)\n  - [R3BL IntelliJ Plugins](#r3bl-intellij-plugins)\n  - [R3BL VSCode Extensions](#r3bl-vscode-extensions)\n  - [Claude Code Integration](#claude-code-integration)\n- [Build the workspace and run tests](#build-the-workspace-and-run-tests)\n  - [Key Commands](#key-commands)\n  - [Cargo Target Directory Isolation for IDE/Tool Performance](#cargo-target-directory-isolation-for-idetool-performance)\n    - [The Problem: Cargo Lock Contention](#the-problem-cargo-lock-contention)\n    - [The Solution: Separate Build Artifacts](#the-solution-separate-build-artifacts)\n    - [Configuration by Tool](#configuration-by-tool)\n    - [Benefits](#benefits)\n    - [Example Workflow Setup](#example-workflow-setup)\n    - [Disk Space Management](#disk-space-management)\n    - [Troubleshooting](#troubleshooting)\n    - [Incremental Compilation Management](#incremental-compilation-management)\n  - [Bacon Development Tools](#bacon-development-tools)\n  - [Automated Development Monitoring](#automated-development-monitoring)\n    - [Option 1: Lightweight Watch Mode (Recommended for Most Users)](#option-1-lightweight-watch-mode-recommended-for-most-users)\n    - [Option 2: Comprehensive Tmux Dashboard](#option-2-comprehensive-tmux-dashboard)\n  - [Tmux Development Dashboard](#tmux-development-dashboard)\n  - [Status Monitoring Scripts](#status-monitoring-scripts)\n  - [Wild Linker (Linux)](#wild-linker-linux)\n  - [Cross-Platform Verification (Windows)](#cross-platform-verification-windows)\n  - [Rust Toolchain Management](#rust-toolchain-management)\n    - [Why mkdir for Locking?](#why-mkdir-for-locking)\n    - [1. rust-toolchain-update.fish - Smart Validated Toolchain Updates](#1-rust-toolchain-updatefish---smart-validated-toolchain-updates)\n    - [2. rust-toolchain-sync-to-toml.fish - Sync to Existing Config](#2-rust-toolchain-sync-to-tomlfish---sync-to-existing-config)\n    - [3. rust-toolchain-validate.fish - Unified Toolchain Validation](#3-rust-toolchain-validatefish---unified-toolchain-validation)\n    - [4. remove_toolchains.sh - Testing Utility](#4-remove_toolchainssh---testing-utility)\n    - [Log File Output](#log-file-output)\n    - [Comprehensive Toolchain Management System](#comprehensive-toolchain-management-system)\n  - [Unified Script Architecture](#unified-script-architecture)\n- [Star History](#star-history)\n- [Archive](#archive)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Why R3BL TUI?\n\nAfter leaving Google in 2021, I ([Nazmul Idris](https://developerlife.com/about-me/))\nembarked on a journey to create infrastructure for modern, powerful, async CLI and TUI\nexperiences built from the ground up in Rust.\n\nThe core architectural innovation: a purely async, immediate mode reactive UI (every state change\ntriggers a render from scratch) where nothing blocks the main thread - unlike traditional approaches\nusing platform-specific blocking operations like POSIX\n[`readline()`](https://man7.org/linux/man-pages/man3/readline.3.html) on Linux/macOS or Windows\n[`ReadConsole()`](https://learn.microsoft.com/en-us/windows/console/readconsole).\n\nR3BL TUI is fundamentally different from [`vim`](https://www.vim.org/),\n[`neovim`](https://neovim.io/), and [`ratatui`](https://ratatui.rs/) through its immediate mode\nreactive UI with clean separation between rendering and state mutation, and purely async nature.\n\nThis fully async, responsive framework works seamlessly across Linux, macOS, and Windows. It's\noptimized for use over SSH connections by painting only diffs, and handles complex concurrent\noperations with low latency while ensuring no thread blocking.\n\n### The Problem with Existing Solutions\n\nI initially tried [Node.js](https://nodejs.org/) with\n[ink](https://developerlife.com/2021/11/25/ink-v3-advanced-ui-components/), but encountered\nfundamental limitations:\n\n- Module incompatibilities and dependency conflicts\n- Limited control over keybindings and terminal behavior\n- High resource consumption for simple tasks\n- Screen flickering and poor rendering performance\n\n### The R3BL Solution: Web and Desktop App Inspired Terminal Apps\n\nOur framework supports the full spectrum from CLI to hybrid TUI to full TUI experiences with deep\nsystem integration.\n\n**Key Innovation: \"Applets\"** - A revolutionary state management system that allows\nprocesses to persist state across their lifecycle and share it with other instances or\nprocesses. And the underlying systems level infrastructure mechanisms that make this\npossible.\n\n### Built-from-Scratch Primitives\n\n**Async Readline**: Unlike POSIX readline which is single-threaded and blocking, our implementation\nis fully async, interruptable, and non-blocking.\n\n**Choose API**: Single-shot user interactions that enter raw mode without taking over the screen or\ndisrupting the terminal's back buffer.\n\n**Full TUI**: Complete raw mode with alternate screen support, fully async and non-destructive.\n\nAll components are end-to-end testable using our InputDevice and OutputDevice abstractions for\nstdin, stdout, and stderr.\n\n### Advanced Rendering \u0026 Styling\n\n- **CSS-like styling** with JSX-inspired declarative layouts\n- **Gradient color support** with automatic terminal capability detection\n- **Double-buffered compositor** for efficient rendering\n- **Comprehensive color support** that adapts to terminal capabilities (even handles macOS\n  Terminal.app's lack of truecolor support)\n\n### Rich Component Ecosystem\n\n- Beautiful Markdown parser with syntax highlighting\n- Rich text editor components\n- Dialog box support\n- Animation framework (in development)\n- Process orchestration via the \"script\" module\n- Async REPL infrastructure\n\nR3BL TUI brings the ergonomics of modern web development (React, flexbox, CSS) to terminal\napplications in Rust, creating a new paradigm for command-line productivity tools.\n\nWe are building command line apps with rich text user interfaces (TUI). We want to lean\ninto the terminal as a place of productivity, and build all kinds of delightful,\nergonomic, and useful experiences for it.\n\n1. 🔮 Instead of just building one app, we are building a library to enable any kind of rich TUI\n   development w/ a twist: taking concepts that work really well for the frontend mobile and web\n   development world and re-imagining them for TUI \u0026 Rust.\n\n- Taking inspiration from things like [React](https://react.dev/),\n  [SolidJS](https://www.solidjs.com/), [Elm](https://guide.elm-lang.org/architecture/),\n  [iced-rs](https://docs.rs/iced/latest/iced/),\n  [Jetpack Compose](https://developer.android.com/compose),\n  [JSX](https://ui.dev/imperative-vs-declarative-programming),\n  [CSS](https://www.w3.org/TR/CSS/#css), but making everything async (so they can be run in parallel\n  \u0026 concurrent via [Tokio](https://crates.io/crates/tokio)).\n- Even the thread running the main event loop doesn't block since it is async.\n- Using macros to create DSLs to implement something inspired by\n  [CSS](https://www.w3.org/TR/CSS/#css) \u0026\n  [JSX](https://ui.dev/imperative-vs-declarative-programming).\n\n2. 🌎 We are building apps to enhance developer productivity \u0026 workflows.\n\n- The idea here is not to rebuild `tmux` in Rust (separate processes mux'd onto a single terminal\n  window). Rather it is to build a set of integrated \"apps\" (or \"tasks\") that run in the same\n  process that renders to one terminal window.\n- Inside of this terminal window, we can implement things like \"applet\" switching, routing, tiling\n  layout, stacking layout, etc. so that we can manage a lot of TUI apps (which are tightly\n  integrated) that are running in the same process, in the same window. So you can imagine that all\n  these \"applets\" have shared application state. Each \"applet\" may also have its own local\n  application state.\n- You can mix and match \"Full TUI\" with \"Partial TUI\" to build for whatever use case you need.\n  `r3bl_tui` allows you to create application state that can be moved between various \"applets\",\n  where each \"applet\" can be \"Full TUI\" or \"Partial TUI\".\n- Here are some examples of the types of \"app\"s we plan to build (for which this infrastructure acts\n  as the open source engine):\n  1. Multi user text editors w/ syntax highlighting.\n  2. Integrations w/ github issues.\n  3. Integrations w/ calendar, email, contacts APIs.\n\n## Welcome to the monorepo and workspace\n\nAll the crates in the `r3bl-open-core` [monorepo](https://en.wikipedia.org/wiki/Monorepo) provide\nlots of useful functionality to help you build TUI (text user interface) apps, along w/ general\nniceties \u0026 ergonomics that all Rustaceans 🦀 can enjoy 🎉.\n\nAny top-level folder in this repository that contains a `Cargo.toml` file is a Rust project, also\nknown as a [crate](https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html). These crates\nare likely published to [crates.io](https://crates.io/crates/r3bl_tui). Together, they form a\n[Rust workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html).\n\nHere's the [changelog](https://github.com/r3bl-org/r3bl-open-core/blob/main/CHANGELOG.md) for this\nmonorepo containing a Rust workspace. The changelog is a great place to start to get familiar with\nwhat has changed recently in each of the crates in this Rust workspace.\n\n## This workspace contains crates for building TUI, CLI, TTY apps\n\nThe [`r3bl_tui`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui) crate is the main crate\nthat contains the core functionality for building TUI apps. It allows you to build apps that range\nfrom \"full\" TUI to \"partial\" TUI, and everything in the middle.\n\nHere are some videos that you can watch to get a better understanding of TTY programming.\n\n- [Build with Naz: TTY playlist](https://www.youtube.com/playlist?list=PLofhE49PEwmw3MKOU1Kn3xbP4FRQR4Mb3)\n- [Build with Naz: async readline](https://www.youtube.com/playlist?list=PLofhE49PEwmwelPkhfiqdFQ9IXnmGdnSE)\n\n### Full TUI (async, raw mode, full screen) for immersive TUI apps\n\n[`tui`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/src/tui) gives you \"raw mode\",\n\"alternate screen\" and \"full screen\" support, while being totally async. An example of this is the\n\"Full TUI\" app `edi` in the [`r3bl-cmdr`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr)\ncrate. You can install \u0026 run this with the following command:\n\n```sh\ncargo install r3bl-cmdr\nedi\n```\n\n### Partial TUI (async, partial raw mode, async readline) for choice based user interaction\n\n[`choose`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/readline_async/choose_api.rs)\nallows you to build less interactive apps that ask a user user to make choices from a list of\noptions and then use a decision tree to perform actions.\n\nAn example of this is this \"Partial TUI\" app `giti` in the\n[`r3bl-cmdr`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr) crate. You can install \u0026\nrun this with the following command:\n\n```sh\ncargo install r3bl-cmdr\ngiti\n```\n\n### Partial TUI (async, partial raw mode, async readline) for async REPL\n\n[`readline_async`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/readline_async/readline_async_api.rs)\ngives you the ability to easily ask for user input in a line editor. You can customize the prompt,\nand other behaviors, like input history.\n\nUsing this, you can build your own async shell programs using \"async readline \u0026 stdout\". Use\nadvanced features like showing indeterminate progress spinners, and even write to stdout in an async\nmanner, without clobbering the prompt / async readline, or the spinner. When the spinner is active,\nit pauses output to stdout, and resumes it when the spinner is stopped.\n\nAn example of this is this \"Partial TUI\" app `giti` in the\n[`r3bl-cmdr`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr) crate. You can install \u0026\nrun this with the following command:\n\n```sh\ncargo install r3bl-cmdr\ngiti\n```\n\nHere are other examples of this:\n\n1. https://github.com/nazmulidris/rust-scratch/tree/main/tcp-api-server\n2. https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples\n\n## Power via composition\n\nYou can mix and match \"Full TUI\" with \"Partial TUI\" to build for whatever use case you need.\n`r3bl_tui` allows you to create application state that can be moved between various \"applets\", where\neach \"applet\" can be \"Full TUI\" or \"Partial TUI\".\n\n### Main library crate\n\nThere is just one main library crate in this workspace:\n[`r3bl_tui`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui).\n\n### Main binary crate\n\nThere is just one main binary crate that contains user facing apps that are built using the library\ncrates: [`r3bl-cmdr`](https://github.com/r3bl-org/r3bl-open-core/tree/main/cmdr). This crate\ncontains these apps:\n\n- `giti`: Interactive git workflows made easy.\n- `edi`: Beautiful Markdown editor with advanced rendering and editing features.\n\nYou can install \u0026 run this with the following command:\n\n```sh\ncargo install r3bl-cmdr\n# Interactive git workflows made easy.\ngiti --version\n# Beautiful Markdown editor with advanced rendering and editing features.\nedi --version\n```\n\n## Project Task Organization\n\nThis project uses a two-tier task management system for organizing day-to-day development work:\nlightweight pointers with simple tasks in root-level files, and detailed task files with\nimplementation plans in the `./task/` directory.\n\n### Task Management Files\n\n- **[`todo.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/todo.md)** - Active tasks,\n  immediate priorities, and pointers to detailed task files. Latest changes at top. Uses status\n  markers: `[ ]` (pending), `[⌛]` (in progress), `[x]` (completed)\n- **[`done.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/done.md)** - Completed tasks\n  and achievements, providing a historical record of progress. Links to archived task files in\n  `./task/done/`\n- **[`./task/`](https://github.com/r3bl-org/r3bl-open-core/tree/main/task)** - Directory containing\n  detailed task management files:\n  - **Active tasks**: `task_*.md` files in root of `./task/` - Complex tasks currently in progress\n  - **`pending/`**: Tasks queued for later work\n  - **`done/`**: Completed task files moved from root after all steps are marked `[COMPLETE]`\n  - **`archive/`**: Abandoned tasks retained for historical reference\n  - **`CLAUDE.md`**: Rules and format specifications for creating and maintaining task files\n\n### Task File Format\n\nDetailed task files follow a structured format defined in\n[`./task/CLAUDE.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/task/CLAUDE.md):\n\n**Structure:**\n\n```markdown\n# Task Overview\n\nHigh-level description, architecture, context, and the \"why\"\n\n# Implementation Plan\n\n## Step 0: Do Something [STATUS]\n\nDetailed instructions for this step\n\n### Step 0.0: Do Subtask [STATUS]\n\nDetails about subtask\n\n### Step 0.1: Do Another Subtask [STATUS]\n\nDetails about another subtask\n\n## Step 1: Do Something Else [STATUS]\n\nMore detailed steps...\n```\n\n**Hierarchical organization:**\n\n- Steps are numbered (Step 0, Step 1, Step 2, etc.)\n- Substeps use decimal notation (Step 0.0, Step 0.1, etc.)\n- Table of contents automatically generated and maintained using `doctoc`\n- Formatting standardized with `prettier`\n\n**Status markers:**\n\n- `[COMPLETE]` - Step finished and verified\n- `[WORK_IN_PROGRESS]` - Currently working on this step\n- `[BLOCKED]` - Cannot proceed (waiting for dependency)\n- `[DEFERRED]` - Postponed to later\n\n### Task Workflow Commands\n\nThe `/task` slash command (defined in\n[`.claude/commands/task.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/.claude/commands/task.md))\nmanages the task lifecycle:\n\n**Create a new task:**\n\n```sh\n/task create my_feature_name\n```\n\n- Creates `./task/task_my_feature_name.md` from your detailed plan\n- Use after you have a comprehensive plan in your todo list\n- Initializes structure with steps and status markers\n\n**Update an existing task:**\n\n```sh\n/task update my_feature_name\n```\n\n- Updates progress markers in `./task/task_my_feature_name.md`\n- Moves completed task files to `./task/done/` when all steps are `[COMPLETE]`\n- Updates `todo.md` and `done.md` cross-references as needed\n\n**Resume working on a task:**\n\n```sh\n/task load my_feature_name\n```\n\n- Loads `./task/task_my_feature_name.md` for continued work\n- Resumes from the last step marked `[WORK_IN_PROGRESS]`\n- If none found, asks which incomplete step to start with\n\n### Workflow Connection\n\nThe task organization workflow connects strategic planning with tactical execution:\n\n- **Strategic Planning** (`docs/` folder): Feature roadmaps, architectural decisions, design\n  documents\n- **Planning to Active Work**: Complex features are documented in `docs/` first, then planned into\n  `todo.md`\n- **Tactical Execution**:\n  1. Simple tasks stay in `todo.md` as checklist items\n  2. Complex tasks get detailed planning → `/task create` → `./task/task_*.md`\n  3. Work progresses through hierarchical steps with `/task update` marking progress\n  4. Completion → Task moved to `./task/done/` via `/task update`\n  5. `done.md` maintains archive links for historical reference\n- **Continuous Sync**: `todo.md` is synchronized with the GitHub project dashboard for visibility\n  across team members\n\nThis three-level approach (docs → todo.md → ./task/) ensures strategic planning, tactical planning,\nand detailed execution are well-organized and connected.\n\n### Development Tools Integration\n\nR3BL provides IDE extensions and plugins to enhance your development workflow, regardless of your\neditor choice:\n\n**For VSCode Users**\n\nR3BL provides custom VSCode extensions including Task Spaces (organize editor tabs by context),\ntheme, and enhanced syntax highlighting. See the [R3BL VSCode Extensions](#r3bl-vscode-extensions)\nsection below for installation and detailed feature descriptions.\n\n**For IntelliJ IDEA Users**\n\nR3BL provides theme and productivity plugins for IntelliJ IDEA and other JetBrains IDEs. See the\n[R3BL IntelliJ Plugins](#r3bl-intellij-plugins) section below for installation from the JetBrains\nMarketplace and detailed feature descriptions.\n\n**Workflow Integration:**\n\nBoth IDE environments complement the `./task/` file management system in this project:\n\n- **VSCode**: The R3BL Task Spaces extension helps you organize editor tabs by context (e.g., one\n  space for features, one for docs, one for debugging) while the `./task/` files track your\n  implementation progress\n- **RustRover**: Use the built-in Task Management plugin alongside `./task/` files for seamless\n  workflow integration\n\n## Documentation and Planning\n\nThe [`docs/`](https://github.com/r3bl-org/r3bl-open-core/tree/main/docs) folder contains\ncomprehensive documentation for this project, including:\n\n### Release and Contribution Guides\n\n- [`release-guide.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/release-guide.md) -\n  Step-by-step guide for releasing new versions\n- [`contributing_guides/`](https://github.com/r3bl-org/r3bl-open-core/tree/main/docs/contributing_guides) -\n  Detailed contribution guidelines including:\n  - Branch naming conventions (`BRANCH.md`)\n  - Commit message standards (`COMMIT_MESSAGE.md`)\n  - Issue creation guidelines (`ISSUE.md`)\n  - Pull request procedures (`PULL_REQUEST.md`)\n  - Code style guide (`STYLE_GUIDE.md`)\n\n### Technical Design Documents\n\n- Parser strategy analysis and design decisions\n- Performance optimization guides (`docs/task_tui_perf_optimize.md`)\n- Architecture documentation for various components\n- Feature-specific planning and design documents\n\nThe `docs/` folder serves as the central repository for:\n\n- **Long-term planning**: Strategic goals and feature roadmaps\n- **Technical decisions**: Architecture choices and implementation strategies\n- **Process documentation**: How we work and contribute to the project\n- **Design artifacts**: Detailed analysis of complex features before implementation\n\n## Learn how these crates are built, provide feedback\n\nTo learn how we built this crate, please take a look at the following resources.\n\n- If you like consuming video content, here's our\n  [YT channel](https://www.youtube.com/@developerlifecom). Please consider\n  [subscribing](https://www.youtube.com/channel/CHANNEL_ID?sub_confirmation=1).\n\n## Quick Start\n\n### Automated Setup (Recommended)\n\nUse the bootstrap script to automatically install all required tools:\n\n```sh\n# Clone the repository\ngit clone https://github.com/r3bl-org/r3bl-open-core.git\ncd r3bl-open-core\n\n# Run the bootstrap script\n./bootstrap.sh\n```\n\nThe [`bootstrap.sh`](https://github.com/r3bl-org/r3bl-open-core/blob/main/bootstrap.sh) script\nhandles **OS-level setup** with a clean main function structure and will:\n\n- **Cross-Platform Support**: Works on **macOS** (Homebrew) and **Linux** including Ubuntu (apt),\n  Fedora (dnf), Arch (pacman), openSUSE (zypper), and Alpine (apk)\n- **Core Rust Installation**: Install Rust toolchain (rustup) and ensure cargo is in PATH\n- **Compiler Setup**: Install clang compiler (required by Wild linker)\n- **Development Shell**: Install Fish shell and fzf for interactive development\n- **File Watching**: Install file watchers (inotifywait on Linux, fswatch on macOS)\n- **Development Utilities**: Install htop, screen, tmux for system monitoring\n- **Node.js Ecosystem**: Install Node.js and npm for web tooling\n- **AI Integration**: Install Claude Code CLI (has built-in LSP server functionality)\n- **Rust Development Tools Setup**: Call `fish run.fish install-cargo-tools` for all Rust-specific\n  tooling\n\n**Architecture**: Uses clear function separation with main() orchestrator and dedicated functions\nfor each concern (install_rustup, install_clang, install_shell_tools, etc.)\n\n### Manual Setup\n\nIf you prefer manual installation or are on Windows:\n\n```sh\n# Install Rust\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Install Fish and fzf (via package manager)\n# Ubuntu/Debian: sudo apt install fish fzf\n# macOS: brew install fish fzf\n# Or run ./bootstrap.sh for automatic detection\n\n# Install Rust development tools (after OS dependencies)\nfish run.fish install-cargo-tools\n```\n\n**Note**: The manual approach requires you to install OS-level dependencies yourself. The\n`install-cargo-tools` command focuses specifically on **Rust development tools**:\n\n**From crates.io (via cargo-binstall with fallback to cargo install):**\n\n- **cargo-binstall**: Fast binary installer (installed first as foundation)\n- **Core Development Tools**: bacon, flamegraph, inferno\n- **Workspace Management**: cargo-workspaces, cargo-cache, cargo-update\n- **Code Quality**: cargo-deny, cargo-unmaintained, cargo-expand, cargo-readme\n- **Wild Linker**: Fast linker with optimized .cargo/config.toml generation\n- **Language Server**: rust-analyzer component\n\n**From local source (via cargo install --path):**\n\n- **cmdr**: edi, giti, rc binaries (calls `install-cmdr`)\n- **build-infra**: cargo-rustdoc-fmt (calls `install-build-infra`)\n\n**Features:**\n\n- **Smart Installation**: Uses cargo-binstall for speed with fallback to cargo install --locked\n- **Local Source Rebuild**: Always rebuilds cmdr and build-infra from source with current toolchain\n- **Shared Utilities**: Leverages utility functions from script_lib.fish for consistency\n\n## IDE Setup and Extensions\n\nChoose the development environment that works best for you. R3BL provides extensions and plugins for\nboth VSCode and IntelliJ IDEA.\n\n### R3BL IntelliJ Plugins\n\nFor developers using IntelliJ IDEA, RustRover, or other JetBrains IDEs, install the R3BL plugins\ndirectly from the JetBrains Marketplace:\n\n**Available Plugins:**\n\n- **[R3BL Theme](https://plugins.jetbrains.com/plugin/28943-r3bl-theme/)** - Vibrant dark theme with\n  carefully chosen colors for visual clarity and reduced eye strain. Optimized for Rust, Markdown,\n  and 30+ languages.\n- **[R3BL Copy Selection Path](https://plugins.jetbrains.com/plugin/28944-r3bl-copy-selection-path-and-range/)** -\n  Copy file paths with selected line ranges in Claude Code compatible format. Press `Alt+O` to copy\n  the current file path with line numbers.\n\n**Installation from JetBrains Marketplace:**\n\n1. Open IntelliJ IDEA / RustRover\n2. Go to `Settings` → `Plugins` → `Marketplace`\n3. Search for \"R3BL Theme\" and \"R3BL Copy Selection Path\"\n4. Click `Install` on each plugin\n5. Restart the IDE\n\n**Or install from disk (for latest development builds):**\n\n```sh\n# Clone the plugins repository\ngit clone https://github.com/r3bl-org/r3bl-intellij-plugins.git\ncd r3bl-intellij-plugins\n\n# Build the plugins\n./gradlew buildPlugin\n\n# In IntelliJ: Settings → Plugins → ⚙️ → Install Plugin from Disk\n# Select the .zip files from:\n# - plugins/r3bl-theme/build/distributions/r3bl-theme-*.zip\n# - plugins/r3bl-copy-selection-path/build/distributions/r3bl-copy-selection-path-*.zip\n```\n\n**Benefits for r3bl-open-core development:**\n\n- **Vibrant Color Scheme**: Enhanced syntax highlighting makes Rust code more readable\n- **Claude Code Integration**: Quickly copy file paths with line ranges using `Alt+O` to share code\n  references with Claude Code\n- **Reduced Eye Strain**: Carefully balanced colors optimized for long coding sessions\n- **Multi-Language Support**: Works great with Rust, Markdown, TOML, and all file types in this\n  project\n\n**Post-installation:**\n\n1. Restart IntelliJ IDEA / RustRover\n2. Go to `Settings` → `Appearance \u0026 Behavior` → `Appearance` → `Theme` → Select \"R3BL\"\n3. Use `Alt+O` to copy file paths with line ranges (great for Claude Code interactions!)\n\n**Task Workflow Integration:**\n\nIntelliJ IDEA and RustRover include a built-in Task Management plugin that works seamlessly\nalongside the `./task/` file management system in this project. Use it to organize your work\ncontexts while the `./task/` files track your implementation progress.\n\n### R3BL VSCode Extensions\n\nFor an optimal development experience with r3bl-open-core in VSCode, we provide a custom extension\npack specifically designed for Rust development. This extension pack is not available on the VSCode\nmarketplace and must be installed manually.\n\n**What's included:**\n\n- **Task Spaces** - Organize and switch between collections of editor tabs for different work\n  contexts (e.g., one space for editing features, one for writing documentation, one for debugging).\n  Complements the `./task/` file management system by helping you organize your editor sessions.\n- **R3BL Theme** - A carefully crafted dark theme optimized for Rust and Markdown development\n- **Auto Insert Copyright** - Automatically inserts copyright headers in new files\n- **Semantic Configuration** - Enhanced Rust syntax highlighting with additional semantic tokens\n- **Extension Pack** - Bundles all R3BL extensions for easy installation\n\n**Benefits for r3bl-open-core development:**\n\n- Zero manual configuration required\n- Enhanced semantic highlighting for better code readability\n- Automatic copyright header insertion following project standards\n- Seamless integration with rust-analyzer\n- Optimized color scheme for the r3bl codebase\n\n**Installation:**\n\n```sh\n# Clone the extension repository\ngit clone https://github.com/r3bl-org/r3bl-vscode-extensions.git\ncd r3bl-vscode-extensions\n\n# Install extensions (works with both VSCode and VSCode Insiders)\n./install.sh\n```\n\n**Prerequisites:**\n\n- VSCode or VSCode Insiders installed\n- Bash shell (for running install.sh)\n\n**Post-installation:**\n\n1. Restart VSCode\n2. Select the R3BL Theme: `Ctrl+Shift+P` → \"Preferences: Color Theme\" → \"R3BL Theme\"\n3. Configure copyright settings if needed\n\nBoth the IntelliJ plugins and VSCode extensions work seamlessly with the existing development tools\nmentioned in this guide, including rust-analyzer, bacon, and the comprehensive development workflow.\n\n### Claude Code Integration\n\nThis project is configured for optimal use with [Claude Code](https://claude.ai/claude-code), the\nofficial CLI for Claude AI.\n\n**Project Instructions:**\n\nThe [`CLAUDE.md`](https://github.com/r3bl-org/r3bl-open-core/blob/main/CLAUDE.md) file at the repo\nroot provides project-specific instructions that Claude Code follows automatically. This includes\ndesign philosophy, coding standards, and crate-specific guidance.\n\n**Available Skills (`.claude/skills/`):**\n\nClaude Code autonomously discovers and applies these coding patterns when relevant:\n\n| Skill                   | Purpose                                                  |\n|-------------------------|----------------------------------------------------------|\n| `check-code-quality`    | Comprehensive quality checklist (check → build → clippy → tests) |\n| `run-clippy`            | Linting, comment punctuation, cargo fmt                  |\n| `write-documentation`   | Rustdoc conventions, intra-doc links, constant formatting |\n| `organize-modules`      | Private modules with public re-exports pattern           |\n| `check-bounds-safety`   | Type-safe Index/Length patterns for bounds-sensitive code |\n| `analyze-performance`   | Flamegraph-based performance regression detection        |\n| `design-philosophy`     | Core principles: cognitive load, type safety, abstraction worth |\n\n**Slash Commands:**\n\nInvoke skills directly in Claude Code:\n\n| Command              | Action                                     |\n|----------------------|--------------------------------------------|\n| `/check`             | Run comprehensive code quality checks      |\n| `/docs`              | Documentation build and formatting         |\n| `/clippy`            | Code style and linting                     |\n| `/fix-intradoc-links`| Fix rustdoc intra-doc links                |\n| `/check-regression`  | Detect performance regressions             |\n| `/analyze-logs`      | Analyze log files (strips ANSI codes)      |\n| `/r3bl-task`         | Task management (create, update, load, done) |\n\n**Getting Started with Claude Code:**\n\n1. Install Claude Code: `npm install -g @anthropic-ai/claude-code`\n2. Navigate to the project root: `cd r3bl-open-core`\n3. Start Claude Code: `claude`\n4. Claude automatically reads `CLAUDE.md` and applies project conventions\n\n**Companion Tools: R3BL Development Pack**\n\nFor the best Claude Code experience, install the\n[R3BL VSCode Extensions](https://github.com/r3bl-org/r3bl-vscode-extensions) which are designed to\nwork hand-in-hand with Claude Code:\n\n| Extension                 | Claude Code Synergy                                           |\n|---------------------------|---------------------------------------------------------------|\n| **R3BL Copy Selection Path** | Press `Alt+O` to copy file paths with line ranges — paste directly into Claude Code for precise code references |\n| **R3BL Task Spaces**      | Organize editor tabs by task context — switch between feature work, debugging, and documentation while Claude Code tracks your `./task/` files |\n| **R3BL Theme**            | Optimized dark theme for long coding sessions with Claude Code |\n\n```bash\n# Install the R3BL Development Pack\ngit clone https://github.com/r3bl-org/r3bl-vscode-extensions.git\ncd r3bl-vscode-extensions \u0026\u0026 ./install.sh\n```\n\nThe `Alt+O` shortcut is particularly powerful: select code in VSCode, press `Alt+O`, then paste the\npath with line numbers directly into your Claude Code conversation for precise context.\n\n## Build the workspace and run tests\n\nThere's a unified [`fish`](https://fishshell.com/) script that you can use to run the build and\nrelease pipeline for this workspace, and more (local only operations).\n\nTo get a list of available commands, you can review the `fish` script in the root of this repo\n[`run.fish`](https://github.com/r3bl-org/r3bl-open-core/blob/main/run.fish). To see all available\ncommands:\n\n```sh\nfish run.fish\n```\n\nYou should see output that looks like this:\n\n```text\nUsage: fish run.fish \u003ccommand\u003e [args]\n\nWorkspace-wide commands:\n    all                  Run all major checks\n    build                Build entire workspace\n    build-full           Full build with clean and update\n    clean                Clean entire workspace\n    test                 Test entire workspace\n    check                Check all workspaces\n    clippy               Run clippy on all workspaces\n    clippy-pedantic      Run clippy with pedantic lints\n    docs                 Generate docs for all\n    serve-docs           Serve documentation\n    rustfmt              Format all code\n    rustdoc-fmt          Format rustdoc comments\n    install-cargo-tools  Install all dev tools (crates.io + local source)\n    upgrade-deps         Upgrade dependencies\n    update-cargo-tools   Update all tools (crates.io + rebuild local source)\n    audit-deps           Security audit\n    unmaintained-deps    Check for unmaintained deps\n    toolchain-update     Update Rust to month-old nightly\n    toolchain-sync       Sync environment to rust-toolchain.toml\n    toolchain-validate   Quick toolchain validation (components only)\n    toolchain-validate-complete  Complete toolchain validation (full build+test)\n    toolchain-remove     Remove ALL toolchains (testing)\n\nWatch commands:\n    test-watch [pattern]  Watch files, run specific test\n    clippy-watch          Watch files, run clippy\n    check-watch           Watch files, run cargo check\n    check-full-watch      Watch files, run all checks (tests, doctests, docs)\n    check-full-watch-test Watch files, run tests and doctests\n    check-full-watch-doc  Watch files, run doc build only\n\nTUI-specific commands:\n    run-examples [--release] [--no-log]  Run TUI examples\n    run-examples-flamegraph-svg  Generate SVG flamegraph\n    run-examples-flamegraph-fold [--benchmark]  Generate perf-folded (use --benchmark for reproducible profiling)\n    bench                Run benchmarks\n\nLocal source package commands:\n    install-cmdr         Install cmdr binaries (edi, giti, rc) from source\n    install-build-infra  Install build-infra tools (cargo-rustdoc-fmt) from source\n\ncmdr-specific commands:\n    run-binaries         Run edi, giti, or rc\n\nDevelopment Session Commands:\n    dev-dashboard        Start 2-pane tmux development dashboard\n\nOther commands:\n    log                  Monitor log.txt in cmdr or tui directory\n    help                 Show this help\n```\n\n### Key Commands\n\n| Command                                                    | Description                                                                             |\n| ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| `fish run.fish all`                                        | Run all major checks (build, test, clippy, docs, audit, format)                         |\n| `fish run.fish build`                                      | Build the entire workspace                                                              |\n| `fish run.fish test`                                       | Run all tests across the workspace                                                      |\n| `fish run.fish install-cargo-tools`                        | Install all dev tools (crates.io + local source packages)                               |\n| `fish run.fish update-cargo-tools`                         | Update all tools (crates.io + rebuild local source packages)                            |\n| `fish run.fish install-cmdr`                               | Install cmdr binaries (edi, giti, rc) from source                                       |\n| `fish run.fish install-build-infra`                        | Install build-infra tools (cargo-rustdoc-fmt) from source                               |\n| `fish run.fish test-watch [pattern]`                       | Watch for file changes and run specific test                                            |\n| `fish run.fish run-examples`                               | Run TUI examples interactively                                                          |\n| `fish run.fish run-examples-flamegraph-svg`                | Generate SVG flamegraph for performance analysis                                        |\n| `fish run.fish run-examples-flamegraph-fold [--benchmark]` | Generate perf-folded format for analysis (use `--benchmark` for reproducible profiling) |\n| `fish run.fish bench`                                      | Run benchmarks                                                                          |\n| `fish run.fish run-binaries`                               | Run cmdr binaries (edi, giti, rc) interactively                                         |\n| `fish run.fish dev-dashboard`                              | Start 2-pane tmux development dashboard (tests, docs, checks)                           |\n| `fish run.fish check-full`                                 | Run comprehensive checks (tests, doctests, docs, toolchain validation)                  |\n| `fish run.fish check-windows-build`                        | Verify Windows cross-compilation (platform cfg gates)                                   |\n| `fish run.fish toolchain-validate`                         | Quick toolchain validation (components only, ~1-2 seconds)                              |\n| `fish run.fish toolchain-validate-complete`                | Complete toolchain validation (full build+test, ~5-10 minutes)                          |\n| `fish run.fish toolchain-update`                           | Update Rust to month-old nightly toolchain with cleanup                                 |\n| `fish run.fish toolchain-sync`                             | Sync Rust environment to match rust-toolchain.toml                                      |\n| `fish run.fish toolchain-remove`                           | Remove ALL toolchains (⚠️ destructive testing utility)                                  |\n\n\u003e **TUI Testing**: The `r3bl_tui` crate uses PTY-based testing for accurate terminal I/O\n\u003e verification. See the [PTY Testing Infrastructure](./tui/README.md#pty-testing-infrastructure)\n\u003e section in the TUI README for details on writing and running TUI tests.\n\n### Cargo Target Directory Isolation for IDE/Tool Performance\n\n**Critical Optimization**: When multiple development tools run cargo simultaneously (IDE, terminal,\nfile watcher, CI), they compete for locks on the shared `target/` directory. This causes severe\nresponsiveness issues as each tool waits for others to complete. Isolating build artifacts by tool\neliminates this bottleneck completely.\n\n#### The Problem: Cargo Lock Contention\n\nWhen you have multiple `cargo` instances running:\n\n- **VSCode rust-analyzer**: Runs `cargo check` continuously in background\n- **RustRover**: Runs `cargo check` continuously in background\n- **File watcher** (`check.fish`, `bacon`): Triggers cargo tests, doc builds, etc. on every file\n  save\n- **Terminal**: You run manual `cargo` commands, and `Claude Code` is running commands\n\nAll these access the same `target/` directory:\n\n```\ntarget/\n├── debug/\n├── release/\n└── .rustc_info.json  # ← Lock contention here\n```\n\nWhen one tool locks `target/`, all others wait. This cascades into a \"traffic jam\" where everything\nbecomes unresponsive.\n\n#### The Solution: Separate Build Artifacts\n\nConfigure each tool to use its own target directory. Rust supports this via the `CARGO_TARGET_DIR`\nenvironment variable:\n\n```\ntarget/\n├── vscode/      # VSCode rust-analyzer builds\n├── rustrover/   # JetBrains IDE builds\n├── claude/      # Claude Code builds\n├── check/       # check.fish file watcher builds\n└── cli/         # Terminal manual builds (optional)\n```\n\nNow tools build in parallel without interfering with each other.\n\n#### Configuration by Tool\n\nGenerally speaking you can just add `CARGO_TARGET_DIR=target/XYZ` in the command, for eg you can run\nthe following in your terminal to run `claude` with the `CARGO_TARGET_DIR` env var set, and all the\n`cargo` commands spawned by `claude` will have their own taret directory to work with:\n\n```bash\nCARGO_TARGET_DIR=target/claude $argv\n```\n\nYou can add this to an alias, add it to scripts (like `check.fish` does via\n`set -gx CARGO_TARGET_DIR target/check`) or you can configure settings in your tool of choice.\n\nIn VSCode, you can add the following to `.vscode/settings.json`:\n\n```json\n{\n  \"rust-analyzer.cargo.targetDir\": true\n}\n```\n\nIn RustRover, you can go to \"Settings -\u003e Rust -\u003e Environment Variables\" and add this\n`CARGO_TARGET_DIR=target/rustrover`\n\n#### Benefits\n\n| Benefit              | Impact                                                                      |\n| -------------------- | --------------------------------------------------------------------------- |\n| **Zero Contention**  | Tools run in parallel without waiting on locks                              |\n| **Responsive IDE**   | rust-analyzer completes checks while you code (not blocked by file watcher) |\n| **Faster Feedback**  | Terminal cargo commands complete instantly (not queued behind IDE checks)   |\n| **Parallel Testing** | bacon + check.fish both run, providing redundant test feedback              |\n| **Disk Space**       | ~2-3GB per tool (manageable with cleanup)                                   |\n\n#### Example Workflow Setup\n\nHere's a typical productive development workflow setup:\n\n```bash\n# Terminal 1: Running your IDE (VSCode with rust-analyzer)\nCARGO_TARGET_DIR=target/vscode code .\n\n# Terminal 2: File watcher with automatic tests\ncheck.fish --watch-test # Runs with: CARGO_TARGET_DIR=target/check\n\n# Terminal 3: Run claude code\nCARGO_TARGET_DIR=target/claude claude\n\n# Terminal 4: Run bacon\nCARGO_TARGET_DIR=target/bacon bacon doc --headless\n\n# Result: All three run in parallel, zero blocking\n```\n\nBefore this optimization, Terminal 3 would hang waiting for Terminals 1-2 to release the `target/`\nlock.\n\n#### Disk Space Management\n\nEach tool caches ~2-3GB of build artifacts. With 4 tools, expect ~10-12GB total. To manage:\n\n```bash\n# View size of each target directory\ndu -sh target/*/\n\n# Clean individual tool builds\nrm -rf target/vscode\nrm -rf target/rustrover\nrm -rf target/claude\nrm -rf target/check\n\n# Full cleanup (nuclear option)\nrm -rf target/\n```\n\n#### Troubleshooting\n\n**Syntax errors still appear in IDE but code works in terminal?**\n\nYour IDE and terminal are using different target directories. Verify `CARGO_TARGET_DIR`\nconfiguration:\n\n```bash\n# Check what each tool sees\necho $CARGO_TARGET_DIR  # Terminal value\n# VSCode: Check .vscode/settings.json\n# RustRover: Check IDE settings\n```\n\n**Build artifacts aren't being reused across tools?**\n\nEach tool has its own `target/` directory by design. This is correct - the slight disk space\noverhead is worth the responsiveness gain. If you need to share builds, unset `CARGO_TARGET_DIR`\n(not recommended for development).\n\n**\"Target directory not found\" error?**\n\nCargo automatically creates the directory. If you see this error, verify the path is writable and\nthe environment variable is set correctly:\n\n```bash\n# Verify the variable is actually set\nenv | grep CARGO_TARGET_DIR\n\n# Test with explicit path\nCARGO_TARGET_DIR=/tmp/test cargo build\n```\n\n#### Incremental Compilation Management\n\nIncremental compilation is disabled globally (`incremental = false` in `.cargo/config.toml`) to\navoid issues with the rustc dependency graph on nightly builds:\n\n```toml\n# .cargo/config.toml\n[build]\nincremental = false  # Disable to avoid rustc dep graph ICE on nightly\n```\n\n**Why disable incremental compilation?**\n\n- The nightly compiler has occasional bugs with the dependency graph in incremental mode\n- These bugs can cause Internal Compiler Errors (ICE) like \"mir_drops_elaborated_and_const_checked\"\n- Disabling it globally ensures stable builds across all cargo invocations\n- The performance impact is acceptable for development workflows\n\n**If you encounter ICE errors anyway:**\n\n```bash\n# Clear any corrupted incremental artifacts\nrm -rf target/check target/debug target/release\n\n# Rebuild cleanly\ncargo check  # or cargo build, cargo test, etc.\n```\n\nThe `check.fish` script also explicitly sets `CARGO_INCREMENTAL=0` as a redundant safeguard.\n\n### Bacon Development Tools\n\nThis project includes [bacon](https://dystroy.org/bacon/) configuration for background code checking\nand testing. Bacon provides real-time feedback on code changes with two distinct workflows:\n\n**Interactive Workflow (Rich TUI with details):**\n\n- Full terminal UI with detailed output\n- Ctrl+click on errors and warnings to jump directly to source code (via OSC hyperlinks)\n- Perfect for active debugging and development\n\n**Background Workflow (Silent monitoring):**\n\n- Minimal output - just success/failure status\n- Answers simple yes/no questions like \"do tests pass?\" or \"do docs build?\"\n- Ideal for background monitoring while focusing on other tasks\n\n**Available Bacon Commands:**\n\n**Code Quality \u0026 Checking:**\n\n| Command            | Description                                                 |\n| ------------------ | ----------------------------------------------------------- |\n| `bacon check`      | Fast typecheck of default target                            |\n| `bacon check-all`  | Typecheck all targets (lib, bins, tests, benches, examples) |\n| `bacon clippy`     | Run clippy lints on default target                          |\n| `bacon clippy-all` | Run clippy lints on all targets (keybinding: `c`)           |\n\n**Testing:**\n\n| Command                           | Workflow    | Description                                                              |\n| --------------------------------- | ----------- | ------------------------------------------------------------------------ |\n| `bacon test`                      | Interactive | Run all tests with cargo test (includes unit, integration, and doctests) |\n| `bacon test -- \u003cpattern\u003e`         | Interactive | Run specific test matching pattern                                       |\n| `bacon doctests`                  | Interactive | Run only documentation tests (`cargo test --doc`)                        |\n| `bacon test --headless --summary` | Background  | Silent test runner providing only pass/fail status                       |\n\n**Documentation:**\n\n| Command                          | Workflow    | Description                                       |\n| -------------------------------- | ----------- | ------------------------------------------------- |\n| `bacon doc`                      | Interactive | Generate documentation with detailed output       |\n| `bacon doc --headless --summary` | Background  | Silent doc builder answering \"did docs generate?\" |\n| `bacon doc-open`                 | Interactive | Generate docs and open in browser                 |\n\n**Running \u0026 Benchmarking:**\n\n| Command                      | Description                                                             |\n| ---------------------------- | ----------------------------------------------------------------------- |\n| `bacon run`                  | Build and run the project in background                                 |\n| `bacon run-long`             | Run long-running processes (e.g., servers) with auto-restart on changes |\n| `bacon ex -- \u003cexample_name\u003e` | Run specific example (e.g., `bacon ex -- my-example`)                   |\n| `bacon bench`                | Run performance benchmarks                                              |\n\nChoose the workflow that matches your current needs:\n\n- Use **interactive** when actively debugging or wanting detailed feedback\n- Use **background** for continuous monitoring, CI/CD pipelines, or when you just need to know if\n  things work\n\n**Testing Notes:**\n\n- Use `bacon test` to run all tests (includes unit, integration, and doctests)\n- Use `bacon doctests` or `bacon test --doc` to run only documentation tests\n\n### Automated Development Monitoring\n\nThe project provides two complementary approaches for continuous monitoring during development -\nchoose based on your workflow preferences:\n\n#### Option 1: Lightweight Watch Mode (Recommended for Most Users)\n\nFor developers who want automated monitoring without the overhead of tmux, use the standalone check\nscript:\n\n```sh\n./check.fish --watch\n```\n\n**What it does:**\n\n- **Monitors source directories**: Watches `cmdr/src/`, `analytics_schema/src/`, and `tui/src/` for\n  changes\n- **Event-driven execution**: Triggers immediately on file changes (no polling delay)\n- **Intelligent debouncing**: 5-second delay prevents rapid re-runs during saves\n- **Comprehensive checks**: Runs tests, doctests, and doc builds automatically\n- **Clean progress output**: Shows stage-by-stage progress without verbose cargo logs\n- **Automatic toolchain validation**: Validates and repairs Rust toolchain before checks\n- **ICE recovery**: Detects and recovers from Internal Compiler Errors automatically\n- **ICE escalation**: On persistent ICE, escalates to `rust-toolchain-update.fish` to find a stable nightly\n- **Continuous operation**: Keeps watching even if checks fail (perfect for iterative development)\n\n**Example output:**\n\n```\n👀 Watch mode activated\nMonitoring: cmdr/src, analytics_schema/src, tui/src\nPress Ctrl+C to stop\n\n🔄 Changes detected, running checks...\n\n▶️  Running tests...\n✅ Tests passed\n\n▶️  Running doctests...\n✅ Doctests passed\n\n▶️  Building docs...\n✅ Docs built\n\n✅ All checks passed!\n\n👀 Watching for changes...\n```\n\n**Benefits:**\n\n- **Single window**: No tmux complexity - just one terminal\n- **Immediate feedback**: 2-second response time after file saves\n- **Low overhead**: Minimal resource usage compared to running multiple monitors\n- **Perfect for focus**: Clean output doesn't distract from your editor\n\n**Event handling:** While checks run (30+ seconds), the Linux kernel buffers new file change events.\nWhen checks complete, buffered events trigger immediately if debounce allows. This ensures no\nchanges are lost but may cause cascading re-runs if you save multiple times during test execution.\nAdjust `DEBOUNCE_SECONDS` in the script if needed.\n\n**Usage:**\n\n```sh\n# Show available options\n./check.fish --help\n\n# Start watch mode\n./check.fish --watch\n\n# Or run checks once (manual mode)\n./check.fish              # Default: tests + doctests + docs\n./check.fish --check      # Fast typecheck only (cargo check)\n./check.fish --build      # Compile only (cargo build)\n./check.fish --clippy     # Lint only (cargo clippy --all-targets)\n./check.fish --test       # Tests + doctests only\n./check.fish --doc        # Docs only (quick, no deps)\n./check.fish --full       # ALL checks + ICE escalation to toolchain update\n```\n\n#### Option 2: Comprehensive Tmux Dashboard\n\n### Tmux Development Dashboard\n\nFor developers who prefer a multi-pane visual environment, the tmux dashboard combines multiple\nbacon monitors with the `check.fish --watch` script for comprehensive coverage.\n\n**When to choose tmux dashboard over standalone watch mode:**\n\n- You want to see **all** checks running simultaneously in different panes\n- You prefer visual separation between tests, doctests, docs, and comprehensive checks\n- You're comfortable with tmux keybindings and pane navigation\n- You have screen space for a 2x2 grid layout\n\n**Comprehensive 4-Pane Development Dashboard:**\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Tmux Session: r3bl-dev (2x2 grid layout)                    │\n├──────────────────────┬──────────────────────────────────────┤\n│ Top-left:            │ Top-right:                           │\n│ bacon test           │ bacon doc                            │\n│ (Unit \u0026 Integration  │ (Documentation generation            │\n│  Tests)              │  with live feedback)                 │\n├──────────────────────┼──────────────────────────────────────┤\n│ Bottom-left:         │ Bottom-right:                        │\n│ bacon doctests       │ ./check.fish --watch                 │\n│ (Documentation       │ (Event-driven comprehensive checks:  │\n│  Tests)              │  tests + doctests + docs + ICE)      │\n└──────────────────────┴──────────────────────────────────────┘\n```\n\n**Key Features:**\n\n- **Persistent Session**: Session name \"r3bl-dev\" - reconnect from other terminals with\n  `tmux attach-session -t r3bl-dev`\n- **Multiple Monitors**: Combines three bacon monitors (tests, doctests, docs) with one\n  comprehensive check monitor (`check.fish --watch`)\n- **Event-Driven Checks**: The bottom-right pane runs `./check.fish --watch` which triggers\n  immediately on file changes (not periodic polling)\n- **Comprehensive Coverage**: The `check.fish --watch` monitor provides:\n  - All unit and integration tests (`cargo test --all-targets`)\n  - Documentation tests (`cargo test --doc`)\n  - Documentation building (`cargo doc --no-deps`)\n  - Automatic ICE (Internal Compiler Error) detection and recovery\n  - Automatic toolchain validation and repair if needed\n  - 5-second intelligent debouncing to prevent rapid re-runs\n- **Interactive Multiplexing**: Full tmux keybindings for pane switching and layout customization\n- **Redundant Coverage**: Tests run in two panes (bacon test + check.fish) - if one fails, the other\n  shows details\n\n**Usage:**\n\n```sh\n# Start the development dashboard\nfish run.fish dev-dashboard\n\n# Reconnect to existing session from another terminal\ntmux attach-session -t r3bl-dev\n\n# Kill the session when done\ntmux kill-session -t r3bl-dev\n```\n\n**Comparison: Standalone vs Tmux Dashboard:**\n\n| Aspect                 | `./check.fish --watch`              | Tmux Dashboard                             |\n| ---------------------- | ----------------------------------- | ------------------------------------------ |\n| **Setup Complexity**   | Single command, one window          | tmux session with 4 panes                  |\n| **Screen Real Estate** | Minimal (one terminal)              | Large (2x2 grid)                           |\n| **Monitoring Scope**   | Comprehensive (tests+docs+doctests) | Granular (separate panes for each)         |\n| **Visual Separation**  | Sequential output in one stream     | Parallel output in dedicated panes         |\n| **Ideal For**          | Focused development, laptop screens | Multi-monitor setups, visual dashboards    |\n| **Tmux Knowledge**     | Not required                        | Helpful for navigation                     |\n| **Resource Usage**     | Lower (one monitor)                 | Higher (4 monitors)                        |\n| **Event-Driven**       | Yes (file system events)            | Yes (check.fish pane) + bacon auto-rebuild |\n\n**When to use each:**\n\n- **Use standalone watch**: When you want simple, focused monitoring in a single terminal\n- **Use tmux dashboard**: When you want comprehensive visibility with separate panes for each\n  concern\n\nBoth approaches use the same `check.fish --watch` script in different contexts - standalone for\nsimplicity, integrated for comprehensive dashboards.\n\n**Typical Development Session:**\n\n1. Start session: `fish run.fish dev-dashboard`\n2. Monitor panes to catch issues while coding\n3. Switch to specific pane for detailed investigation if needed\n4. All four monitors provide continuous feedback on code quality\n\n### Wild Linker (Linux)\n\nThis project uses the [Wild linker](https://github.com/davidlattimore/wild) as a fast alternative to\nthe default linker on Linux systems. Wild can significantly reduce link times during iterative\ndevelopment, making builds faster and more responsive.\n\n**Automatic Configuration**: The build system automatically detects and configures Wild when both\n`clang` and `wild` are installed. If either tool is missing, the configuration gracefully falls back\nto standard parallel compilation without Wild.\n\n**Installation**: The setup process automatically installs both prerequisites:\n\n- `clang`: Installed by\n  [`bootstrap.sh`](https://github.com/r3bl-org/r3bl-open-core/blob/main/bootstrap.sh) as a system\n  dependency\n- `wild-linker`: Installed by `fish run.fish install-cargo-tools` via `cargo-binstall` (with\n  fallback to `cargo install`)\n\n**Configuration**: When available, Wild is configured in `.cargo/config.toml` for Linux targets:\n\n```toml\n[target.x86_64-unknown-linux-gnu]\nlinker = \"clang\"\nrustflags = [\n    \"-Z\", \"threads=8\",  # Parallel compilation\n    \"-C\", \"link-arg=--ld-path=wild\"  # Wild linker\n]\n```\n\n**Verification**: Check if Wild is active by looking for the configuration in `.cargo/config.toml`\nor by observing faster link times during development builds.\n\n**Platform Support**: Wild linker is Linux-only. On other platforms, the build system uses standard\nparallel compilation without Wild.\n\n### Cross-Platform Verification (Windows)\n\nThis project uses platform-specific code gates (`#[cfg(unix)]`, `#[cfg(not(unix))]`) for\nUnix-specific functionality like terminal I/O. To verify these gates compile correctly on Windows\nwithout needing a full Windows cross-compiler (mingw-w64), we use Rust's metadata-only compilation.\n\n**How It Works:**\n\nThe `--emit=metadata` flag tells rustc to stop after type checking and MIR generation, skipping code\ngeneration and linking entirely. This validates all platform-specific cfg gates without needing a\nlinker for the target platform.\n\n```sh\n# Verify Windows cross-compilation\nfish run.fish check-windows-build\n\n# Or run directly:\ncargo rustc -p r3bl_tui --target x86_64-pc-windows-gnu -- --emit=metadata\n```\n\n**Prerequisites:**\n\nThe Windows target is automatically installed by `fish run.fish install-cargo-tools`. To install\nmanually:\n\n```sh\nrustup target add x86_64-pc-windows-gnu\n```\n\n**When to Use:**\n\n- After modifying `#[cfg(unix)]` or `#[cfg(not(unix))]` conditional compilation gates\n- Before committing platform-specific code changes\n- As part of CI/CD for cross-platform verification\n- When adding new platform-specific modules or functions\n\n**Example Output:**\n\n```text\nVerifying Windows cross-compilation for r3bl_tui...\nTarget: x86_64-pc-windows-gnu\nMode: metadata only (no linking required)\n\n✅ Windows cross-compilation check passed\nPlatform-specific cfg gates compile correctly for Windows.\n```\n\n**Technical Details:**\n\n| Aspect              | Description                                                      |\n| ------------------- | ---------------------------------------------------------------- |\n| **Target**          | `x86_64-pc-windows-gnu` (Windows with GNU toolchain ABI)         |\n| **Compilation**     | Stops at MIR stage (`--emit=metadata`), no object code generated |\n| **Linking**         | Not required - no mingw-w64 or Windows SDK needed                |\n| **What's Verified** | Syntax, types, trait bounds, cfg gate correctness                |\n| **What's NOT**      | Runtime behavior, Windows-specific API calls, linking errors     |\n\nThis approach catches the most common cross-platform issues (missing cfg gates, type mismatches in\nplatform-specific code) with minimal setup overhead.\n\n\u003e **Platform Backends**: The TUI crate supports multiple backends: `Crossterm` (cross-platform,\n\u003e default on macOS/Windows) and `DirectToAnsi` (provided by `r3bl_tui` itself, Linux-native, ~18%\n\u003e better performance). We use cfg gates to ensure the selection of the correct backend for supported\n\u003e platforms. See [Platform-Specific Backends](./tui/README.md#platform-specific-backends) for\n\u003e details.\n\n### Rust Toolchain Management\n\nThis project includes three complementary scripts for comprehensive Rust toolchain management, each\nserving a specific purpose in the development workflow.\n\n**Concurrency Safety:** Toolchain **modification** scripts (`rust-toolchain-update.fish` and\n`rust-toolchain-sync-to-toml.fish`) use `mkdir` (atomic directory creation) to ensure only one\ntoolchain modification runs at a time. **Validation** scripts (`rust-toolchain-validate.fish` and\n`check.fish`) are lock-free since they only read toolchain state - multiple validations can run\nconcurrently without conflict.\n\n#### Why mkdir for Locking?\n\nThe key insight is understanding **atomicity** - when a system operation must check-and-act in a way\nthat's guaranteed to be indivisible:\n\n**The Problem with File Existence Checks:**\n\nTraditional approaches try to check if a lock exists, then create it:\n\n```bash\n# UNSAFE - Race condition!\nif [ ! -f lock ]; then\n    echo \"timestamp\" \u003e temp\n    mv temp lock  # TOCTOU race between check and move\nfi\n```\n\nBetween the check (`[ ! -f lock ]`) and the move (`mv temp lock`), another process can slip in and\nalso acquire the lock. This is called a **Time-Of-Check-Time-Of-Use (TOCTOU) race condition**.\n\n**How mkdir Works - Atomic Check-and-Create:**\n\n`mkdir` is different. It combines the check and create into ONE indivisible kernel operation:\n\n```bash\n# SAFE - Atomic operation\nmkdir lock_dir  # Check AND create in ONE kernel operation\n# Only ONE process succeeds; all others fail\n```\n\nWhen `mkdir` runs, the kernel does:\n\n1. **Check**: Does the directory exist?\n2. **Create**: If not, create it\n3. **Return**: With ONE atomic operation - not two separate steps\n\nEven with perfect timing and multiple processes starting simultaneously, only ONE can create the\ndirectory.\n\n**Technical Implementation:**\n\n```fish\n# In script_lib.fish\nif mkdir ./rust-toolchain-script.lock 2\u003e/dev/null\n    # Lock acquired - this process has exclusive access\nelse\n    # Lock held by another process\nfi\n```\n\n**Key Advantages:**\n\n- **Atomic**: Check-and-create in ONE kernel operation (impossible to race)\n- **Simple**: No file descriptors or special handling needed\n- **Reliable**: Works on all Unix systems (standard POSIX behavior)\n- **Stale lock detection**: Automatically removes locks older than 10 minutes (crashed processes)\n- **Crash-safe**: Abandoned locks are auto-cleaned after 10 minutes, or manually via\n  `rm -rf rust-toolchain-script.lock`\n\nThe locking mechanism uses:\n\n- **mkdir (atomic directory creation)**: Creates lock directory atomically - succeeds for one\n  process, fails for all others\n- **Atomic kernel operation**: Check-and-create happens as ONE indivisible operation - the\n  definition of mutual exclusion\n- **Timestamp tracking**: Stores creation time in `rust-toolchain-script.lock/timestamp` for age\n  tracking\n- **Stale lock detection**: Checks lock age on collision - auto-removes if older than 10 minutes\n  (600 seconds)\n- **Lock holder cleanup**: Process that acquired lock removes directory (including timestamp) when\n  done\n- **Conflict detection**: Failed mkdir indicates lock is held - shows age for transparency\n- **Standard Unix pattern**: Used by systemd, init systems, and most Unix tools\n\n#### 1. rust-toolchain-update.fish - Smart Validated Toolchain Updates\n\nIntelligently finds and validates a stable nightly toolchain, preferring older versions for\nstability while ensuring they don't have ICE (Internal Compiler Error) bugs.\n\n```sh\n# Via run.fish command\nfish run.fish toolchain-update\n\n# Or directly\n./rust-toolchain-update.fish\n```\n\n**What it does:**\n\n- **Smart search**: Tests nightly toolchains starting from 45 days ago, moving forward day-by-day\n  until finding a stable one (up to today)\n- **ICE validation**: Runs comprehensive validation suite on each candidate:\n  - `cargo clippy --all-targets`\n  - `cargo build`\n  - `cargo test --all-targets`\n  - `cargo test --doc`\n  - `cargo doc --no-deps`\n- **Toolchain vs code errors**: Distinguishes between:\n  - ❌ **ICE errors** (compiler crashes) → rejects toolchain, tries next day\n  - ✅ **Code errors** (compilation/test failures) → accepts toolchain (validates compiler works,\n    not your code)\n- **First stable wins**: Stops at the first toolchain without ICE errors (usually finds stable\n  toolchain in first attempt)\n- **Updates** `rust-toolchain.toml` to use the validated stable nightly\n- Installs the target toolchain with rust-analyzer component (required by IDEs and cargo)\n- **Desktop notifications** (via notify-send):\n  - 🎉 Success notification when stable toolchain found (normal urgency)\n  - 🚨 Critical alert if no stable toolchain found in entire 45-day window (extremely rare)\n- Performs aggressive cleanup by removing all old nightly toolchains except:\n  - All stable toolchains (`stable-*`)\n  - The newly validated nightly\n- **Final verification with fresh build**:\n  - Removes ICE failure files (`rustc-ice-*.txt`) generated during validation\n  - Cleans all caches: cargo cache, build artifacts\n  - Runs full verification: tests, doctests, and documentation build\n  - Ensures new toolchain works perfectly from scratch\n- Logs all operations to `/home/nazmul/Downloads/rust-toolchain-update.log`\n\n**When to use:**\n\n- Weekly maintenance (can be automated via systemd timer)\n- When you want to update to a validated stable nightly\n- When you want to clean up old toolchains\n- After encountering ICE errors with current toolchain\n\n**Example output:**\n\n```text\n═══════════════════════════════════════════════════════\nStarting search for stable toolchain\nStrategy: Start 45 days ago, try progressively newer up to today\nSearch window: 2025-08-29 to 2025-10-13\n═══════════════════════════════════════════════════════\n\nAttempt 1/46\nTrying toolchain: nightly-2025-08-29 (45 days ago)\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nValidating toolchain: nightly-2025-08-29\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nRunning validation step: clippy\n  ⚠️  Command exited with code 101 (this is OK if not ICE)\n  ✅ No ICE detected - continuing validation\n...\n✅ Toolchain nightly-2025-08-29 is STABLE (no ICE detected)\n\n🎉 FOUND STABLE TOOLCHAIN: nightly-2025-08-29\nSuccess notification sent\n\n✅ Successfully updated rust-toolchain.toml\n✅ Successfully installed rust-analyzer component\nRemoved 2 old toolchain(s)\nToolchains directory size before cleanup: 5.3G\nToolchains directory size after cleanup: 2.6G\n```\n\n#### 2. rust-toolchain-sync-to-toml.fish - Sync to Existing Config\n\nSyncs your Rust environment to match whatever is specified in `rust-toolchain.toml`.\n\n```sh\n# Via run.fish command\nfish run.fish toolchain-sync\n\n# Or directly\n./rust-toolchain-sync-to-toml.fish\n```\n\n**What it does:**\n\n- **Reads** the channel value from `rust-toolchain.toml` (doesn't modify it)\n- Installs the exact toolchain specified in the TOML\n- Installs rust-analyzer and rust-src components automatically (required by IDEs and cargo)\n- Performs aggressive cleanup by removing all old nightly toolchains except:\n  - All stable toolchains (`stable-*`)\n  - The target toolchain from the TOML\n- Logs all operations to `/home/nazmul/Downloads/rust-toolchain-sync-to-toml.log`\n\n**When to use:**\n\n- After `git checkout/reset/pull` changes `rust-toolchain.toml`\n- When rust-analyzer is missing for the current toolchain\n- When your IDE shows \"rust-analyzer failed to start\"\n- After manually editing `rust-toolchain.toml`\n- When you need to stay on a specific nightly version\n\n**Key difference from update script:**\n\n- **This script (sync)**: Respects TOML → Installs what's specified\n- **Update script**: Modifies TOML → Installs \"1 month ago\" nightly\n\n**Example workflow:**\n\n```sh\n# Weekly script updates TOML to nightly-2025-09-11\n# But you need to stay on nightly-2025-09-05 for testing a specific feature\ngit checkout rust-toolchain.toml  # Revert to 09-05\nfish run.fish toolchain-sync  # Install components for 09-05\n# Now rust-analyzer works for 09-05\n```\n\n#### 3. rust-toolchain-validate.fish - Unified Toolchain Validation\n\nConsolidated validation script providing two modes: quick component check or comprehensive\nbuild+test validation.\n\n```sh\n# Quick mode: Fast component check (~1-2 seconds)\nfish run.fish toolchain-validate\n./rust-toolchain-validate.fish quick\n\n# Complete mode: Full build+test validation (~5-10 minutes)\nfish run.fish toolchain-validate-complete\n./rust-toolchain-validate.fish complete\n\n# View detailed help\n./rust-toolchain-validate.fish\n```\n\n**Mode Comparison:**\n\n| Aspect            | Quick Mode                              | Complete Mode                        |\n| ----------------- | --------------------------------------- | ------------------------------------ |\n| **Time**          | ~1-2 seconds                            | ~5-10 minutes                        |\n| **Purpose**       | Component verification                  | Stability verification               |\n| **Use Case**      | Fast health checks                      | Pre-nightly validation               |\n| **Checks**        | Installation + components + rustc works | Full build + clippy + tests + docs   |\n| **ICE Detection** | No                                      | Yes (critical for nightly selection) |\n\n**Quick Mode Validation:**\n\n- ✅ Toolchain is installed via rustup\n- ✅ rust-analyzer component is present\n- ✅ rust-src component is present\n- ✅ rustc --version works (not corrupted)\n\n**Complete Mode Validation:**\n\n- ✅ All quick mode checks\n- ✅ cargo clippy --all-targets (no ICE)\n- ✅ cargo build (no ICE)\n- ✅ cargo test --all-targets (no ICE)\n- ✅ cargo test --doc (no ICE)\n- ✅ cargo doc --no-deps (no ICE)\n\n**Return Codes:**\n\n- `0`: ✅ Valid (quick) or Stable (complete)\n- `1`: ❌ Not installed (quick) or ICE detected (complete)\n- `2`: ⚠️ Missing components (quick only)\n- `3`: 🔥 Corrupted - rustc fails (quick only)\n- `4`: ❌ Failed to read rust-toolchain.toml\n\n**When to use Quick Mode:**\n\n- After installing/repairing toolchain with `sync-toolchain`\n- Troubleshooting IDE issues (rust-analyzer not working?)\n- Pre-flight check before running tests\n- Regular health monitoring\n- Part of automated CI/CD pipelines\n\n**When to use Complete Mode:**\n\n- Verifying nightly toolchain stability before using it\n- Detecting Internal Compiler Errors (ICE) in compiler\n- Before committing code with new toolchain\n- During `toolchain-update` search (finding stable nightly)\n- After major Rust version updates\n\n**Integration with other toolchain scripts:**\n\n- **check.fish**: Uses quick mode to check toolchain before running tests; calls `toolchain-sync` if\n  invalid\n- **rust-toolchain-sync-to-toml.fish**: Performs quick validation after installing components\n- **rust-toolchain-update.fish**: Uses complete mode to find stable nightly\n\n#### 4. remove_toolchains.sh - Testing Utility\n\nRemoves ALL Rust toolchains for testing upgrade progress display (⚠️ DESTRUCTIVE).\n\n```sh\n./remove_toolchains.sh\n```\n\n**What it does:**\n\n- Removes ALL Rust toolchains from your system\n- Cleans up toolchain directories completely\n- Creates a clean slate for testing rustup installation progress\n\n**When to use:**\n\n- When developing/testing the upgrade progress display in `edi` and `giti`\n- To see full rustup download and installation progress\n- For testing `cmdr/src/analytics_client/upgrade_check.rs` functionality\n\n**Recovery after testing:**\n\n```sh\nrustup toolchain install stable \u0026\u0026 rustup default stable\n# Or\nfish run.fish toolchain-update\n```\n\n**⚠️ Warning:** This is a destructive testing utility. Use only when you understand the implications\nand are prepared to reinstall toolchains.\n\n#### Log File Output\n\nAll toolchain management scripts display detailed log file locations to stdout at startup:\n\n```\n📋 Detailed log: /home/nazmul/Downloads/rust-toolchain-sync-to-toml.log\n```\n\nThis makes it easy to monitor progress and check detailed logs after operations complete:\n\n```sh\n# Watch logs in real-time\ntail -f /home/nazmul/Downloads/rust-toolchain-update.log\n\n# Or review after completion\ncat /home/nazmul/Downloads/rust-toolchain-sync-to-toml.log\n```\n\n#### Comprehensive Toolchain Management System\n\nThe four scripts work together to provide a complete toolchain management solution:\n\n**Four complementary scripts:**\n\n- **validate** (`rust-toolchain-validate.fish`): Non-destructive validation of current\n  toolchain\n- **update** (`rust-toolchain-update.fish`): Smart search for stable nightly with comprehensive\n  validation\n- **sync** (`rust-toolchain-sync-to-toml.fish`): Install toolchain matching rust-toolchain.toml\n- **remove** (`remove_toolchains.sh`): Testing utility to clean all toolchains (destructive)\n\n**Key benefits:**\n\n- **Stability**: Month-old nightlies have proven stability while providing recent features\n- **Disk space savings**: Aggressive cleanup removes accumulated old toolchains\n- **Consistency**: All developers use the same Rust version via `rust-toolchain.toml`\n- **Automation ready**: `update` script designed to run weekly via systemd timer\n- **Recovery ready**: `sync` script fixes environment after git operations\n- **Validation ready**: `validate` script enables automated health checks in CI/CD pipelines\n- **Testing support**: `remove` script enables testing upgrade workflows\n- **Integrated monitoring**: `check.fish` automatically validates and repairs toolchain before\n  running tests\n\n### Unified Script Architecture\n\nThe project uses a clean separation of concerns across three main scripts with shared utilities:\n\n```\n┌──────────────────────────────────────────────────────────────────────────┐\n│                           Bootstrap Flow                                 │\n└──────────────────────────────────────────────────────────────────────────┘\n\n    ┌─────────────────┐     calls     ┌───────────────────────────────────┐\n    │  bootstrap.sh   │──────────────▶│  fish run.fish install-cargo-tools│\n    │  (OS-level)     │               │  (Rust development tools)         │\n    └─────────────────┘               └───────────────────────────────────┘\n            │                                       │\n            │ installs                              │ uses\n            ▼                                       ▼\n    ┌─────────────────┐               ┌──────────────────────────────────┐\n    │ rustup, clang,  │               │        script_lib.fish           │\n    │ fish, fzf,      │               │   (shared utility functions)     │\n    │ inotify-tools   │               │                                  │\n    └─────────────────┘               │  • install_windows_target        │\n                                      │  • install_if_missing            │\n                                      │  • install_cargo_tool            │\n                                      │  • generate_cargo_config         │\n                                      │  • read_toolchain_from_toml      │\n                                      │  • acquire_toolchain_lock        │\n                                      │  • ... 25+ shared functions      │\n                                      └──────────────────────────────────┘\n                                                    ▲\n                    ┌───────────────────────────────┼───────────────────────┐\n                    │                               │                       │\n                    │ sources                       │ sources               │ sources\n                    │                               │                       │\n    ┌───────────────────────┐  ┌─────────────────────────────┐  ┌───────────────────────┐\n    │       run.fish        │  │ rust-toolchain-update.fish  │  │ rust-toolchain-sync-  │\n    │  (dev commands)       │  │ (smart toolchain updater)   │  │ to-toml.fish          │\n    │                       │  │                             │  │ (sync to TOML)        │\n    │  • build, test, docs  │  │  • install_windows_target   │  │                       │\n    │  • clippy, rustfmt    │  │  • acquire_toolchain_lock   │  │  • install_windows_   │\n    │  • install-cargo-tools│  │  • read_toolchain_from_toml │  │    target             │\n    │    (calls install_    │  │  • set_toolchain_in_toml    │  │  • acquire_toolchain_ │\n    │     windows_target)   │  │  • ...                      │  │    lock               │\n    └───────────────────────┘  └─────────────────────────────┘  └───────────────────────┘\n```\n\n**Key DRY Principle**: All shared functionality lives in `script_lib.fish`. Individual scripts\nsource this library and call shared functions, ensuring consistent behavior and eliminating code\nduplication. When a function like `install_windows_target` needs updating, it only needs to be\nchanged in one place.\n\n**[`bootstrap.sh`](https://github.com/r3bl-org/r3bl-open-core/blob/main/bootstrap.sh)** - **OS-Level\nSetup**\n\n- System package manager detection and OS dependencies\n- Rust toolchain installation via rustup\n- Development environment setup (Fish shell, fzf, file watchers)\n- Cross-platform compatibility (Linux, macOS)\n- Calls run.fish for Rust-specific tooling\n\n**[`run.fish`](https://github.com/r3bl-org/r3bl-open-core/blob/main/run.fish)** - **Rust Development\nCommands**\n\n- **Workspace-wide commands** that operate on the entire project\n- **Cargo tool installation** (install-cargo-tools with cargo-binstall, uv, bacon, etc.)\n- **TUI-specific commands** for running examples and benchmarks\n- **cmdr-specific commands** for binary management\n- **Cross-platform file watching** using inotifywait (Linux) or fswatch (macOS)\n- **Smart log monitoring** that detects and manages log files from different workspaces\n\n**[`script_lib.fish`](https://github.com/r3bl-org/r3bl-open-core/blob/main/script_lib.fish)** -\n**Shared Utilities**\n\n- Common functions used by both bootstrap.sh and run.fish\n- Utility functions: install_if_missing, generate_cargo_config, install_cargo_tool\n- Cross-platform package manager detection\n\nAll commands work from the root directory, eliminating the need to navigate between subdirectories.\nThis architecture ensures no redundancy - each tool is installed in exactly one place with clear\nownership.\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#r3bl-org/r3bl-open-core\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=r3bl-org/r3bl-open-core\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=r3bl-org/r3bl-open-core\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=r3bl-org/r3bl-open-core\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## Archive\n\nAs this repo grows, changes, and matures, pruning is necessary. The\n[`r3bl-open-core-archive`](https://github.com/r3bl-org/r3bl-open-core-archive) is where all the code\nand artifacts that are no longer needed are moved to.\n\nThis way nothing is \"lost\" and if you need to use some of the code that was removed, you can find it\nthere.\n\nAlso if you want to make changes to this code and maintain it yourself, please let us know.\n\n1. You can submit PRs and we can also accept them, and publish them to crates.io if that makes\n   sense.\n2. Or we can even work out and arrangements to move ownership of the code \u0026 crate to you if you\n   would like to commit to maintaining it.\n","funding_links":["https://github.com/sponsors/nazmulidris"],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr3bl-org%2Fr3bl-open-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr3bl-org%2Fr3bl-open-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr3bl-org%2Fr3bl-open-core/lists"}