rootle 0.4.4

Modal TUI for browsing remote source-control systems (GitHub in-tree, any forge via stdio providers) from the terminal
Documentation

rootle — browse remote source-control systems from your terminal

status: alpha — features, keys, and config may still shift between releases; pin a version if it matters to you.

ci release audit crates.io version status website

A modal TUI (ratatui) with a yazi-style miller-column browser, syntax-highlighted previews, Zed-style global search, and a pluggable provider seam — GitHub ships in-tree, anything else wraps in via a small stdio script.

demo

Contents

What it does

  • Browse orgs → repos → trees → files in three miller columns with a live syntax-highlighted preview — no clone required.
  • Find (␣ f) and grep (␣ g) full-screen, Zed-style: result blocks with match chips, folded regions, and per-file counts.
  • Open any file read-only in your editor (Enter); yank the browser URL of anything (␣ y).
  • Clone repos through a wizard (v marks, :clone) — orgs fan out, destinations get <dest>/<org>/<repo>.
  • Configure in-app with :settings (writes config.toml, hot reloads themes); every keybinding is in the ? popup.

Quick start

curl -fsSL https://rootle.dev/install.sh | sh   # linux x86_64, to ~/.local/bin
brew install rootledev/tap/rootle   # linux (builds from source)
brew install --cask rootledev/tap/rootle   # macOS (prebuilt binary)
cargo install rootle                # or from crates.io (Rust 1.88+)

rootle                # repo search on first run; browser after that
rootle owner/repo     # jump straight into a repo

Auth is zero-friction: if gh auth login or ROOTLE_TOKEN is already set up, rootle just uses it; anonymous works everywhere except code search (it says so in the status line when it matters).

Documentation

Doc Contents
settings every config key, env var, CLI flag
themes writing your own palette (role reference)
provider protocol wrap your own backend (NDJSON-RPC over stdio)
development architecture, dev workflow, e2e harness
house style the component behavior contract
provider scaffolding public skill: scaffold a provider + conformance gate

Providers

rootle talks to backends through a small protocol, not to GitHub directly. [provider] kind = "github" is the default in-tree implementation; kind = "stdio" spawns your adapter as a child process — four methods make a minimal useful provider, and the conformance suite in skills/rootle-provider gates correctness. More providers are planned and the protocol will evolve with them.

Development

cargo test                          # unit + TestBackend render tests
cd e2e && uv run pytest             # PTY end-to-end suite
docker compose run --build --rm test  # fmt + clippy -D warnings + cargo test
docker compose run --build --rm e2e # same e2e suite in a container

CI runs the gate + e2e on every push; the demo workflow re-renders the demo GIFs above (one per palette) whenever the app or its tooling changes and opens a PR with the refreshed artifacts — this README always shows the current look and feel.