hotl

A terminal agent dashboard. Run it in a pane of your own; it discovers AI-agent processes across your terminal multiplexer, shows their live status, and lets you jump focus to an agent — grouped by session → window.

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