# hotl — a human-on-the-loop terminal agent dashboard
[](https://crates.io/crates/hotl)
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](https://github.com/tmux/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](https://github.com/nrakochy/hotl/releases/latest).
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