hotl — a human-on-the-loop terminal agent dashboard

I was inspired by herdr, but I wanted to retain those sweet sweet navigation bindings from neovim-tmux navigation.

So, byo-keybindings. Run this tui in a pane of your own. It discovers AI-agent processes across your ze multiplexer, shows their live status, gives an (optional) audible ping when an agent is waiting on your input.

Quick start

Requirements: tmux on your PATH (run hotl from inside a tmux session) and ps (standard on macOS/Linux).

Install a prebuilt binary — no toolchain needed:

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nrakochy/hotl/releases/latest/download/hotl-installer.sh | sh

Windows (PowerShell)

powershell -c "irm https://github.com/nrakochy/hotl/releases/latest/download/hotl-installer.ps1 | iex"

Or grab a .tar.xz / .zip for your platform directly from the latest release.

With Rust installed, you can instead build from crates.io:

cargo install hotl

Then, from inside tmux, open a pane and run it:

hotl

Keys: j/k (or ↓/↑) move · enter jump to the selected agent · r refresh · q or Ctrl-c quit · Ctrl-h/j/k/l switch tmux panes.

Run it locally

Build the optimized binary:

cargo build --release

The binary is then at target/release/hotl. You have a few ways to run it.

Option A — run by path (no install)

From inside a tmux session, open a pane and run the absolute path:

~/sources/hotl/target/release/hotl

Option B — put it on your PATH

cargo install drops binaries in ~/.cargo/bin. If that directory is on your PATH (this machine's zsh config adds it), install and run by name:

cargo install --path crates/hotl   # installs to ~/.cargo/bin/hotl
hotl

If ~/.cargo/bin is not on your PATH, either add it, or symlink the built binary into a directory that already is:

ln -sf ~/.cargo/bin/hotl ~/.nix-profile/bin/hotl

Usage

Inside tmux, create a pane (e.g. Ctrl-b % for a vertical split), then run hotl in it. It lists the AI agents it finds, with each agent's live status, and refreshes about once a second.

Keys:

• j / k (or ↓ / ↑) — move the selection
• gg / G — jump to the top / bottom of the list
• enter (or gd) — jump focus to the selected agent's pane (hotl stays open)
• Ctrl-h / Ctrl-j / Ctrl-k / Ctrl-l — switch to the neighboring tmux pane
• r — refresh now
• q or Ctrl-c — quit

(Ctrl/arrow keys work regardless of vim_mode; the j/k/gg/G/gd letter bindings require vim_mode = true, the default.)

Detected agents (v1): claude, codex.

Each agent shows a live status glyph: an animated braille snake while working · ! blocked (needs your input) · √ idle · · unknown. When an agent transitions into blocked, hotl plays an audible ping so you know it's waiting on you.

tmux + vim-tmux-navigator

hotl handles Ctrl-h/j/k/l itself by switching tmux panes, so it works out of the box. If you also use vim-tmux-navigator, add hotl to its vim_pattern so tmux forwards those keys into hotl (which does the pane switch) instead of stepping around it — this keeps movement seamless whether the focused pane is Vim, another navigator-aware app, or hotl. In ~/.config/tmux/tmux.conf:

# add `hotl` to the alternation (…|fzf|hotl)
vim_pattern='(\S+/)?g?\.?(view|l?n?vim?x?|fzf|hotl)(diff)?(-wrapped)?'
is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
    | grep -iqE '^[^TXZ ]+ +${vim_pattern}$'"
bind-key -n 'C-h' if-shell "$is_vim" 'send-keys C-h' 'select-pane -L'
bind-key -n 'C-j' if-shell "$is_vim" 'send-keys C-j' 'select-pane -D'
bind-key -n 'C-k' if-shell "$is_vim" 'send-keys C-k' 'select-pane -U'
bind-key -n 'C-l' if-shell "$is_vim" 'send-keys C-l' 'select-pane -R'

Reload with tmux source-file ~/.config/tmux/tmux.conf.

Config

Optional ~/.config/hotl/config.toml (absent → sensible defaults):

[settings]
ping_on_blocked = true         # audible ping when an agent needs input
poll_interval_ms = 1000        # scan cadence
agents = ["claude", "codex"]   # process names counted as agents
vim_mode = true                # vim list keys (j/k/gg/G/gd); false = arrows only

[settings.theme]
preset  = "tokyo-night"        # base palette; omit → default
blocked = "#ff0000"            # optional: override any slot on top

Built-in presets: default, tokyo-night, catppuccin, gruvbox, nord, dracula. Overridable slots: active, blocked, idle, ink, muted, faint, accent, band. An unknown preset name falls back to default.

A [plugins] section is reserved for future use (parsed but inert).

Requirements

• A supported multiplexer on your PATH — today tmux (run hotl from inside a tmux session)
• ps (standard on macOS/Linux)

Build

cargo build --release
./target/release/hotl