Wrap mode

In observe mode the agent lives in your terminal: close the window and it’s gone. Wrap mode moves the agent into a small holder process so it keeps running on its own.

pilothouse run claude

Output and keystrokes pass straight through. Your terminal, your keybindings, your clipboard — Pilothouse intercepts exactly one key.

Detach and re-attach

• Press ctrl+\ to detach. The agent keeps running.
• Press ctrl+\ twice to send a literal ctrl+\ to the agent.

pilothouse ls              # attachable sessions are marked
pilothouse attach s_4k2m   # any unique prefix of the session id

Only one terminal is attached at a time; attaching from a second terminal detaches the first with a message. On attach Pilothouse nudges the agent to redraw, so you see the current screen.

Options

pilothouse run [-n name] [-d] [--] <command> [args…]

Flag	Meaning
-n name	A name for the session in the inbox
-d	Start detached (attach later)
--	Everything after is the agent command and its arguments

pilothouse run -n api-refactor -- claude --model opus
pilothouse run -d codex "review the open PR"

Pilothouse picks the agent type from the command name (claude, codex; anything else is wrapped as a generic program).

What it survives

• Closing the terminal — the holder isn’t attached to it.
• Restarting the Pilothouse daemon or upgrading it — holders aren’t children of the daemon or the service manager. They re-register when the daemon comes back.
• The daemon not running at all — the agent still starts; the holder keeps retrying the daemon in the background.

When the agent exits, the holder reports the exit code and goes away a few seconds later.

What you get on top of observe mode

• Persistence and attach, as above.
• Better state: the holder reads the terminal status sequence (OSC 7501) that Codex (and Claude Code, when the terminal supports it) emits, as a second source alongside hooks. pilothouse explain shows which source decided a state.
• Every wrapped agent gets PILOTHOUSE_SESSION_ID and PILOTHOUSE=1 in its environment.

Wrap mode works inside tmux, herdr, screen or an SSH session just like any other program.