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

Run it in a pane of your own; it discovers AI-agent processes across your terminal multiplexer, shows their live status, gives an (optional) audible ping when an agent is waiting on your input, and lets you jump focus to an agent.

hotl never owns a terminal. The multiplexer owns your agents' panes; hotl observes them from the outside and can switch your focus to one. Today it observes tmux; the observation layer is surface-agnostic so other backends (e.g. zellij) can be added without changing the rest of the tool.

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.

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