ht — overview

ht is the τ-mux CLI. It talks to a running τ-mux instance through a Unix socket using JSON-RPC. Since 0.3.187 the default socket lives in the app’s config dir (macOS: ~/Library/Application Support/hyperterm-canvas/hyperterm.sock), so ht works from any shell — not just panes τ-mux spawned. HT_SOCKET_PATH overrides; ht doctor diagnoses drift.

Install

In a production build, click τ-mux → Install ‘ht’ Command in PATH from the menu — it symlinks the bundled binary at Contents/MacOS/ht to /usr/local/bin/ht. See Installation.

For development:

bun link              # exposes ./bin/ht as `ht`

For a standalone binary on another Mac:

bun run build:cli     # → ./build/ht-cli

Verify

ht ping               # → PONG
ht version            # build version
ht identify           # focused surface + workspace

Targeting

Most commands operate on a surface. The CLI resolves the target in this order:

1. --surface <id> flag (e.g. --surface surface:3)
2. HT_SURFACE env var (auto-set inside τ-mux panes)
3. The currently focused surface

So inside a τ-mux pane, ht ps “just works” — it reads from your own pane. Outside τ-mux, pass --surface explicitly.

Workspace-targeted commands accept --workspace <id> (e.g. --workspace ws:2).

JSON output

Every command supports --json (or -j) to emit raw JSON:

ht metadata --json | jq .ports
ht ps --json | jq '.tree[0]'

Without --json, output is human-friendly text — tables for lists, summary lines for status calls.

Environment variables

Variable	Purpose
HT_SOCKET_PATH	Override the default socket path (<config dir>/hyperterm.sock)
HT_SURFACE	Auto-set per spawned shell (CLI default for --surface; the server resolves the owning workspace from it for workspace-scoped commands)
HT_WORKSPACE_ID	Optional override for --workspace. Not auto-set — export it manually if you want a non-pane shell to default to a specific workspace.
HYPERTERM_WEB_PORT	Overrides webMirrorPort and force-starts the mirror
HYPERTERM_DEBUG	Enables debug logs in the Python / TS sideband clients

Discoverability

ht capabilities --json    # full method catalogue
ht --help                 # top-level command list
ht <command> --help       # per-command help

Command groups

• System — ping, version, identify, tree, capabilities
• Workspaces — list, new, select, close, rename, next, prev
• Surfaces & I/O — split, focus, close, send, send-key, read-screen, screenshot
• Sidebar & status — set-status, set-progress, log
• Notifications — notify, list, clear
• Process & ports — metadata, ps, cwd, git, ports, open, kill
• Browser — 40+ commands for built-in browser automation
• Telegram — status, chats, read, send
• Ask-user — yesno, choice, text, confirm-command (block on a structured question)
• Plan — set, update, complete, clear, list (publish multi-step agent plans)
• Auto-continue — status, audit, set, fire, pause, resume (engine that auto-sends Continue on turn-end)

tmux compat

ht capture-pane --lines 50    # alias for read-screen

The set is intentionally small — only the calls scripts most commonly assume. There is no plan for full tmux compatibility.