# 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.
## 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 . # 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, grouped by session → window, with
each agent's live status, and refreshes about once a second.
Keys:
- `j` / `k` (or ↓ / ↑) — move the selection
- `enter` — jump focus to the selected agent's pane (`hotl` stays open)
- `r` — refresh now
- `q` — quit
Detected agents (v1): `claude`, `codex`.
Each agent shows a live status glyph: `●` 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