Shell integration recipes

July 30, 2026 · View on GitHub

Small, complete HTP recipes for each supported shell. For the higher-level overview see Shell integration; for the wire format see HTP protocol.

What ships

shell-integration/bash.sh
shell-integration/zsh.zsh
shell-integration/fish.fish
shell-integration/powershell.ps1

The Python OSC transport client is at scripts/hollow-cli. See Python hollow-cli.

bash

Source from .bashrc:

source /path/to/hollow/shell-integration/bash.sh

The snippet installs prompt hooks that emit cwd_changed and command_started / command_ended. It does not implement OSC reply capture; for queries and ad hoc emits, call hollow-cli directly:

hollow-cli get current-pane
hollow-cli emit split_pane '{"floating":true}'

zsh

Source from .zshrc:

source /path/to/hollow/shell-integration/zsh.zsh

For queries and ad hoc emits, call hollow-cli directly:

hollow-cli get current-workspace
hollow-cli emit new_workspace '{"cwd":"/repo","name":"repo"}'

fish

Source from config.fish:

source /path/to/hollow/shell-integration/fish.fish

For queries and ad hoc emits, call hollow-cli directly:

hollow-cli get current-tab
hollow-cli emit close_pane '{}'

Hollow auto-dot-sources shell-integration/powershell.ps1 when launching the pwsh or powershell domain — no manual setup required. The snippet reports cwd via OSC 7 and updates the window title via OSC 0 on every prompt.

For queries and ad hoc emits, call hollow-cli directly:

hollow-cli get current-pane
hollow-cli pane split vertical --cmd "npm run dev"
hollow-cli emit notify '{"text":"done"}'

hollow-cli is a Python 3 script with no third-party dependencies. It uses the host command socket when reachable and falls back to the active tty.

OSC over tty vs. host socket

	`hollow-cli`	`hollow cli …`
Needs a tty	only for OSC	no
Needs shell integration sourced	no	no
Brief tty ownership during the call	only for OSC queries	no
Works over SSH from another host	no	no
Best for	portable Python automation	native host automation

The two are not mutually exclusive. Use the shipped shell-integration/ snippets for ambient metadata and the native CLI for explicit mutations.

Shell integration recipes

What ships

bash

zsh

fish

PowerShell

OSC over tty vs. host socket

See also