rootle 0.3.0

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

cargo install rootle    # from crates.io (Rust 1.88+)
# or download the static binary from a release, or build:
docker compose run --build --rm release    # → ./dist/rootle-linux-x86_64-musl

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
getting-started first run, every flow with screenshots, key map
settings every config key, theme role, env var, CLI flag
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 GIF and screenshots above whenever the app or its tooling changes and opens a PR with the refreshed artifacts — this README always shows the current look and feel.