Shell integration (zsh, bash, fish)
Prompt the agent without leaving your shell. The integration is generated by the binary itself — hotl init <shell> prints it. zsh gets the prefix plugin and tab completion in one line; bash and fish get tab completion (the : prefix plugin is zsh-only today — tracker #7). The zsh plugin gives you four things:
- The
:prefix. A command line starting with:becomes an agent prompt:: fix the failing testrunshotl -p "fix the failing test". Everything else runs as normal shell. @[path]file capture. Inside a prompt,@[path]tokens are replaced by that file’s contents, wrapped in a source-labeled block so the model knows where the text came from. An unreadable path leaves the token in place with an inline note — never silently dropped, never a hard error.- OSC-133 marks. The plugin emits shell-integration escape sequences around each prompt and command, so terminals that understand them (and
hotl watch) can find prompts and command boundaries in the scrollback. - The last command rides along.
: why did that failcarries the command you just ran, its exit status, how long it took and — inside tmux — the last 200 lines it printed, so the agent sees the failure, not just the question. See What:attaches.
Assumes a working agent (quickstart.md) and zsh.
Install
Section titled “Install”Add one line to ~/.zshrc:
eval "$(hotl init zsh)"Reload (exec zsh or open a new terminal). mutates: this rebinds zsh’s accept-line widget, adds precmd/preexec hooks and keeps a few _hotl_* shell variables per command (the last command line, its start time and exit status, one tmux pane position); it changes no files other than your ~/.zshrc edit, and the trace files it writes under $TMPDIR are deleted by hotl -p as soon as they are read.
bash and fish get completion only:
eval "$(hotl init bash)" # ~/.bashrchotl init fish | source # ~/.config/fish/config.fishCompletion
Section titled “Completion”hotl <Tab> lists the subcommands and the global flags; hotl gc <Tab>,
export, stats, update, init, mcp, skills, plugins and workflows
complete their own flags and verbs. After -r, --resume, --fork-from and
export, the newest 20 session ids and names complete — the source is the
hidden hotl __sessions verb, which prints id<TAB>name lines. The scripts are
hand-written and tied to the binary’s dispatch table by a test, so a verb cannot
exist in one and not the other; a new flag is added to the scripts by hand.
There is no PowerShell completion.
Use it
Section titled “Use it”From any prompt:
: what does the Makefile's deploy target actually do? @[Makefile]The line becomes hotl -p '…' with the Makefile contents attached; the agent answers in your terminal and exits. It’s a normal headless run — the permission gate, sandbox floor, and session log all apply, and the session shows up in hotl resume like any other.
Plain commands are untouched:
ls -la # runs as ls, no agent involved:ls # also plain shell — the prefix is colon-spaceWhat the colon prefix attaches
Section titled “What the colon prefix attaches”The preexec/precmd hooks remember the last command line, its exit status
and its duration. When you type a : prompt, the plugin writes those — and,
inside tmux, the pane scrollback from the command’s first output line to its
last, bounded to the newest HOTL_TRACE_LINES (default 200) lines — to a
0600 file under $TMPDIR and passes it as hotl -p … --shell-trace FILE.
hotl reads and deletes the file, masks it (the values of secret-named
environment variables, plus common token shapes: sk-…, ghp_…, AKIA…,
xox…, JWTs, Bearer …, PEM private keys), wraps it in a
<shell_trace trust="untrusted" exit="…" ms="…" captured="…"> block marked as
data rather than instruction, and appends it to your prompt. Outside tmux the
block carries the command, exit status and duration and says
captured="none" — zsh cannot recover output nobody recorded. A trace older
than HOTL_TRACE_MAX_AGE (default 1800 s) is not attached, and neither is the
output of a previous : prompt. HOTL_SHELL_TRACE=0 turns the hooks off.
Cost: one tmux display call per command (measured 3.4 ms on the owner’s
machine; the end position is read when you type the prompt, not after every
command); nothing shells out to the hotl binary until you type a prompt. A
prompt taller than one line needs HOTL_PROMPT_LINES=<n> so the capture ends
above it.
Remove
Section titled “Remove”Delete the eval "$(hotl init zsh)" line from ~/.zshrc and reload. Nothing else to clean up — the plugin lives in shell memory, not on disk. Full removal of hotl itself: uninstall.md.