Skip to content

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 test runs hotl -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 fail carries 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.

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)" # ~/.bashrc
hotl init fish | source # ~/.config/fish/config.fish

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.

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-space

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.

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.