# getting started
## install
macOS or Linux, plus at least one agent CLI on your PATH: codex, claude, pi or zot.
Update any time with hrdx update.
## run
# start$ hrdx# open several projects at once$ hrdx --cwd ~/Developer/api --cwd ~/Developer/web# pick your default agent$ hrdx --agent claude# resume each project's latest session$ hrdx --continue
## flags
| flag | purpose |
|---|---|
| --cwd PATH | open a project as a workspace, repeatable |
| --agent ID | default agent for new panes: zot, pi, claude, codex (default zot) |
| --provider ID | pass a provider to every zot pane (zot only) |
| --model ID | pass a model to every zot pane (zot only) |
| --reasoning LEVEL | set the reasoning level (zot only) |
| --continue | resume each project's latest session |
| --codex-bin PATH | use a specific codex binary |
| --claude-bin PATH | use a specific claude binary |
| --pi-bin PATH | use a specific pi binary |
| --zot-bin PATH | use a specific zot binary |
| --shell PATH | shell for shell panes (default $SHELL) |
| --state PATH | state file for workspace persistence (empty disables) |
| --fresh | ignore saved workspaces and start clean |
| --api | serve the control API on a unix socket (default on, --api=false disables) |
| --persist | keep pane processes alive across restarts via the session holder (default on) |
| --plugins | enable the experimental runtime for explicitly approved plugins (default off) |
| --plugin-views | allow approved plugin views, requires --plugins (default off) |
## persistence
Quitting hrdx does not kill your sessions. Pane processes live in a small background session holder. Close the TUI, reopen it, and every shell and agent reattaches exactly where it was: running commands keep running, scrollback and screen state are replayed, nothing restarts. If a held session is truly gone, agent panes relaunch resuming their latest conversation from the agent's own session store.
The holder serves one hrdx terminal at a time. Starting hrdx while another terminal is attached exits with already running in another terminal instead of opening a second, unpersisted session. Quit the other terminal first, or pass a different --state file for an independent instance.
To stop the background holder and everything it holds, quit the TUI first, then run:
$ hrdx stop
With no holder or no held sessions, it exits successfully without a prompt. Otherwise it lists the held sessions and asks before killing them. Only a yes answer proceeds. Declining or reaching end of input leaves them running and exits with code 1. If a TUI is attached, stop reports the holder as busy and asks you to quit it first (ctrl+b q). The prompt does not block a TUI from reconnecting, and stop refuses to shut down if the held sessions change while you decide. This command takes no options and targets the default state location. Stopping the holder does not delete saved layouts: the next launch starts fresh panes for the killed sessions.
State, keys, harnesses, themes, and plugins live in one directory: ~/Library/Application Support/hrdx on macOS, $XDG_CONFIG_HOME/hrdx on Linux, %AppData%\hrdx on Windows. An absolute XDG_CONFIG_HOME is honored on macOS too. An existing Application Support directory keeps being used until you move it under the XDG path, so exporting the variable never orphans running sessions.
The API and holder sockets normally live beside the state file. If that directory cannot host Unix sockets, macOS and Linux use a private directory under $XDG_RUNTIME_DIR/hrdx/ when available. Existing socket paths stay in use when they work. See the socket API docs for runtime socket names and scripting examples.
## durable agents
Optionally, zot agents can run on a zot continuous host so their work survives closed panes, quits, and restarts. Pick zot (durable) in any agent picker and manage hosts with hrdx continuous. See durable agents.