Herdr WebUI

Herdr WebUI is a local browser UI for built-in or external Herdr-compatible terminals, workspaces, worktrees, Git operations, and file browsing.

It runs as a Rust Axum server, serves embedded frontend assets, and starts a built-in terminal multiplexer backend by default. It can also connect to an external Herdr backend protocol for compatibility. The UI supports desktop and mobile layouts.

Prebuilt binaries ship on the releases page: pick the tarball for your platform (Linux x86_64, macOS aarch64, macOS x86_64), extract it, and run the documented quick start without a Rust toolchain:

curl -LO https://github.com/alecuba16/herdr-webui/releases/latest/download/herdr-webui-macos-aarch64.tar.gz
tar -xzf herdr-webui-macos-aarch64.tar.gz
./herdr-webui-macos-aarch64/herdr-webui --https off --backend-mode builtin
# open http://127.0.0.1:8787

Each tarball contains herdr-webui, herdr-webui-tui, and a README.txt; a matching .sha256 checksum is published next to it. The binary can also install itself as a service: ./herdr-webui install-mac or install-linux (see docs/installation.md).

To build from source instead, the same quick start works with the Rust toolchain. From a fresh clone:

cargo run -- --https off --backend-mode builtin
# open http://127.0.0.1:8787

That command starts one process: the Axum WebUI server plus the embedded PTY backend. No separate herdr server process is required, and no herdr binary is needed for this mode.

Cargo picks the herdr-webui server automatically (default-run in Cargo.toml). If you need the other binary, cargo run --bin herdr-webui-tui runs the TUI client. When passing --bin, it must come before the -- separator: cargo run --bin herdr-webui -- --https off.

To use an external Herdr daemon instead (requires the official herdr binary, herdr 0.9.0 or newer), launch the daemon separately, then point WebUI at it:

herdr server
cargo run -- --https off --backend-mode external-herdr

The installed package also includes a first-party terminal UI. The TUI is a client; it does not start the backend by itself, so run it while WebUI is already running:

herdr-webui-tui              # interactive TUI against built-in session "default"
herdr-webui-tui --summary    # smoke summary
herdr-webui-tui --once       # one-shot text snapshot

For a named built-in WebUI session, use the same namespace:

cargo run -- --session demo --backend-mode builtin
cargo run --bin herdr-webui-tui -- --session demo

Or with installed binaries:

herdr-webui --session demo --backend-mode builtin
herdr-webui-tui --session demo

For external Herdr-compatible sockets, pass the explicit socket paths instead of a built-in session name:

herdr-webui-tui --api-socket /path/to/herdr.sock --terminal-socket /path/to/herdr-client.sock

make install-mac, make update-mac, make install-linux, and make update-linux install both herdr-webui and herdr-webui-tui. The browser WebUI and TUI can run in parallel against the same built-in backend session; both attach to the same terminal socket protocol. For predictable input, only type into one client for the same pane at a time.

The README is the project summary and documentation index. Detailed functionality, technical decisions, performance boundaries, styling rules, and project structure live under docs/.

• Multi-workspace terminal UI with desktop and mobile layouts, backed by the built-in backend by default.
• Browser terminals use a shared wterm/Ghostty renderer adapter with Settings-backed renderer choice, link detection, mouse-reporting opt-in, scroll speed, Tail follow, large-paste chunking, and temporary terminal parity.
• Backend-aware session manager that detects built-in and external Herdr sessions, switches between them, and can create or launch sessions in either backend.
• Built-in backend agent detection with Herdr-style argv/process-tree labels and screen status rules for visible idle, working, and blocked states across common coding agents.
• First-party herdr-webui-tui for terminal-native workspace/agent navigation, live attach/input/resize/detach, ANSI colors/styles, --theme dark|light|system, Ctrl-B help/menu, and smoke-friendly summary/once modes.
• Workspace and linked worktree navigation with per-panel terminal state.
• Git UI for status, diffs, staging, commits, stash, branches, cleanup, worktrees, conflicts, blame, and file history.
• Unified header search for workspaces/worktrees, panels, file names, folder names, and file-content matches, including match-case and regex options for content search.
• File explorer with backend Git status colors, parent-aware backend file/folder search, backend content search, type icons, CodeMirror editing (text files open editable by default with a lock toggle for read-only, plus dirty tab indicators and Cmd/Ctrl+S save), line numbers, matched-line opening, folding, in-editor find, and editable find/replace.
• Per-workspace file explorer state while workspaces/worktrees are open, including selected files, search selections, lock state, split panes, and drafts.
• Settings for keyboard shortcuts, theme colors, terminal renderer/input behavior, notifications, worktree defaults, file browser behavior, enabled search sections, search section ordering, and content-search defaults.
• Help button documents visible features and shortcuts in-app, including the terminal renderer switch, Tail behavior, copy/paste, PageUp/PageDown, and temporary terminal shortcuts.

See Features for full behavior details.

• Backend: Rust Axum server, explicit authenticated API routes, embedded assets, built-in terminal multiplexer, external Herdr protocol bridge, Git/file-system operations.
• Built-in status detection: argv/process-tree labels plus screen-text fallbacks for Amp, Antigravity, Claude, Claurst, Cline, Codex, Cursor, Devin, Droid, Gemini, GitHub Copilot, Grok, Hermes, Jcode, Kilo, Kimi, Kiro, Maki, OpenCode, Pi, Qoder CLI, and Qwen.
• Frontend: vanilla JS/CSS assets, no runtime framework, shared modules for the HTTP client, tree rendering, icons, editor mounting, content search, wterm/Ghostty terminal helpers, and theme tokens.
• Editor: CodeMirror bundle is preloaded before shared editor code so file previews mount directly with final editor styling; shared editor code provides find in preview plus replace in edit mode.
• File explorer/search: expensive work is backend-owned: tree listing, file/folder search, Git status propagation, content search traversal, safe file read/write, and hash-guarded snippet/file saves.
• Static assets: compiled into the binary with include_str!/include_bytes! and served from stable /assets/... routes.

See Technical details for routes, limits, data flow, and settings.

• Git status uses one porcelain scan per refresh and propagates parent folder state server-side with priority red > yellow > green.
• Content search skips dependency/build folders, caps traversal, skips large or binary files, paginates file groups, lazy-loads per-file match details, and validates regex patterns before traversal.
• Terminal output is frame-batched before terminal renderer writes, large paste input uses bounded WebSocket chunks with backpressure, browser terminal query replies such as OSC 10/11 colors are filtered before they can leak into PTY input, and mouse reports are stripped unless the user enables terminal mouse reporting.
• Large Git diffs use lazy loading, placeholders, context expansion, and server-side Git commands rather than browser-side repository scanning.
• Path inputs are cleaned before file-system operations. Mutating Git/file actions use backend validation, hash guards, and confirmation where destructive.

See Technical details and Development guide.

• Core theme colors live in desktop/mobile base CSS, with shared extension tokens in src/assets/shared/colors.css for cross-layout features.
• File icons are neutral monochrome by default and inherit Git status colors only when backend status marks a row changed.
• Desktop CSS/JS is split into modules under src/assets/desktop/app_css/ and src/assets/desktop/app_js/.
• Shared UI logic lives under src/assets/shared/ to avoid duplicated desktop/mobile maps and rendering code.
• Mobile keeps layout-specific controllers but reuses shared tree, editor, icon, content-search, and terminal helper modules when possible.

See Development guide for project structure and maintainability rules.

cargo test
node --test src/assets/app_core.test.mjs src/assets/app_load.test.mjs src/assets/app_boot.test.mjs src/assets/mobile_load.test.mjs

Or run all checks together:

just check

Use cargo fmt before committing Rust changes. Keep Help and docs updated when adding visible features.