Attach to a running session

Start a session from the Happier app, attach to it later in your terminal, and switch between remote and local control.

This guide explains how to start a supported session from the Happier app, leave it running on your machine, and then reconnect to that same session later from a terminal.

This is the main workflow behind:

starting a session from the app UI while you are away from your terminal,
reconnecting later with happier attach <session-id>, and
switching the same session between remote control (from Happier) and local control (from the provider TUI in your terminal).

When to use it

This workflow is useful when you want to:

start a session from the web or desktop app,
let the agent begin working immediately,
come back later and continue from a shell on the same machine,
switch back to the app without losing the session history.

Common examples:

start a Codex or Claude session from the app, then attach later from your terminal,
start an OpenCode session from the app, then reopen it locally without creating a second Happier session,
begin a task from the UI, then run happier attach <session-id> when you want to use the provider’s native TUI directly,
leave a session running in the background and reconnect later without starting a new one.

How attach works

happier attach reconnects to a session that is already running.

happier attach
happier attach <session-id>

What happens depends on how that session was started:

tmux-backed session: Happier reattaches you to the live tmux session
zellij- or Herdr-hosted session: Happier opens the existing pane that owns the session
Windows Terminal session: Happier focuses the existing Windows Terminal host for that session
Windows Console session: Happier brings the existing console host to the foreground
provider-native attach session: Happier uses the provider’s own attach flow for that session

happier attach reconnects to the existing session. It does not start a new one.

If you run happier attach without a session id in a supported terminal, Happier opens an interactive list of active sessions:

attachable sessions on the current machine are selectable
active sessions that are visible but not attachable stay disabled with an explanation
remote-capable provider sessions are labeled as remote; press P to check reachability before attaching

Stopped sessions are not shown in this picker. Use happier resume for inactive sessions.

Requirements

Attach support depends on the session type.

Terminal-hosted sessions

Herdr hosting and automatic terminal presentation for supported server-backed sessions are available in current development builds; they are not yet a released contract.

Older released Happier apps can still read and manage the session's core metadata. Herdr-specific selection and attachment controls require an updated app; they are not added to an older app by upgrading only its machine's CLI.

Happier can host supported sessions in tmux, zellij, or Herdr on macOS and Linux.

Requirements:

the session must run on a machine where Happier CLI/daemon is available,
the terminal host must be selected before the session starts,
you must attach from the same machine that owns the running session,
you must be using the same Happier account/server profile that started the session.

The host keeps the interactive process available so Happier can reconnect later. Herdr requires a stable release, version 0.9.2 or newer.

Windows interactive-host sessions

On Windows, tmux is often not the right answer. Happier also supports Windows-specific remote session modes:

Hidden — best for purely remote usage from the app
Windows Terminal — best when you want to come back later and continue in a Windows Terminal window
Console — starts the session in a regular visible console host

If the session was started in Windows Terminal or Console mode, happier attach <session-id> focuses that existing interactive host instead of using tmux.

Provider-native attach sessions

Some providers can attach through their own native session model.

For example, Codex App Server sessions on macOS and Linux can open the Codex TUI against the same running thread, and OpenCode can reopen a supported existing provider session. Neither flow requires a terminal host. If a host is selected for new sessions, Happier can open that TUI there immediately instead of waiting for a manual attach. You still attach from the machine that owns the running session.

Choose how app-started sessions should launch

Choose a terminal host

Use this when you want supported sessions to appear immediately in tmux, zellij, or Herdr and remain attachable there.

In the app:

Open Settings
Open Session
Choose Terminal host for new sessions: None, tmux, zellij, or Herdr

New sessions with a real terminal surface start in the selected host. Server-backed Codex and OpenCode sessions open their local TUI against the same provider session. ACP and other headless runtimes stay headless. Machine details can override the account-wide choice.

In development builds, a server-backed Codex or OpenCode terminal is an optional local client. Closing that managed terminal leaves the session available in Happier; it does not stop the shared controller or automatically reopen the terminal. Use Detach terminal to release it from the app, or Stop to end the session.

Choose the default Windows mode

For Windows machines:

Open Settings
Open Session
In the Windows section, choose the default remote session mode:
- Hidden
- Windows Terminal
- Console

You can then refine that default in two places:

Per machine: open the machine details screen and override the global Windows mode for that machine
Per session: in the new-session flow, use the Windows mode chip when the selected machine is Windows

Precedence is:

per-session choice
machine override
global Windows default

Typical flow

The most common flow looks like this:

Start the session in the Happier app
Use it normally in remote mode
Run happier attach <session-id> on the owning machine
Open the provider TUI for the same session
Continue working in the terminal
Keep using the app at the same time on shared-control paths, or switch back later on exclusive-control paths

Starting local control is terminal-driven. To take local control, attach from the terminal on the owning machine with happier attach <session-id>.

Shared-control sessions keep Happier connected while the provider TUI is open. On exclusive-control sessions, Happier queues app messages and waits for the local turn to finish, abort, or otherwise reach a safe boundary before switching back to remote processing.

Remote control vs local control

The same session can move between two control styles:

Remote control: you interact from Happier’s UI and Happier drives the provider in the background
Local control: you interact from the provider’s own terminal UI after attaching locally

This is a control switch inside the same session, not a new session. The transcript, session id, and session settings stay the same.

Remote-to-local control starts from the terminal with happier attach. Local-to-remote control can be requested from the app when the session is currently locally controlled. On exclusive-control paths, Happier may wait until the current local turn is done before it takes remote control. Shared-control paths keep the app connected while the TUI is attached.

In current development builds, shared-control sessions offer Detach terminal only for a TUI managed by the session runner. Detaching that TUI keeps the session and app writable. A separate native happier attach client is independent: close it in its terminal, rather than expecting the app to close it. If the session has a terminal host, happier attach restores its managed TUI there before opening or focusing the host. An already-attached TUI is reused.

After a Herdr restart, development builds can also admit a native client started inside the session's restored pane while its shared controller remains running. Happier verifies the same conversation and current client before showing managed attachment and Detach terminal. Detaching closes that client, not the restored shell or pane, and leaves the session writable in the app. A restored pane alone does not grant this managed association; failed admission leaves it unbound. The saved Happier resume command must be available in the restored shell. If it is not, invoke the matching Happier CLI's attach <session-id> there yourself.

Supported providers

Claude

Claude supports local and remote control in Happier.
In local mode, you use the normal Claude terminal UI directly.
App messages sent while Claude is locally controlled are queued and delivered after the current local turn reaches a safe stopping point.
On macOS and Linux, this can use tmux, zellij, or Herdr.
On Windows, use Happier’s Windows remote session modes instead of expecting tmux.
If local permission bridge is enabled, some permission prompts can still appear in Happier while the session is locally attached.

Codex

Codex supports app-started sessions plus later terminal attachment.
App Server sessions use shared local control with Codex CLI 0.131.0 or newer on macOS and Linux: the TUI and Happier remain connected to the same App Server thread.
App messages and approvals remain available while the TUI is attached; the normal Happier input flow waits when a turn is already active.
The shared path uses Codex’s native local socket and does not require a terminal host. A selected host controls where its TUI opens.
Windows, ACP sessions, and older App Server installations retain the existing exclusive attach behavior.

OpenCode

OpenCode supports app-started sessions plus later terminal attachment.
For supported sessions, Happier can use OpenCode’s native attach flow without requiring a terminal host. A selected host controls where its TUI opens.
OpenCode uses shared local control, so the app can remain writable while the OpenCode TUI is attached.
The session remains the same Happier session while you move between remote and local/shared control.

What happens to messages while switching

Happier keeps one canonical session state. During switching:

transcript history remains shared,
permission mode follows the session,
queued messages stay attached to the session,
app-sent messages may wait in the pending queue if the session is not ready to process them immediately.

This is expected. It prevents messages from being lost during mode switches or reconnects.

For Claude and Codex’s exclusive compatibility paths, the pending queue also protects the current terminal turn. Happier waits for the local turn to complete or stop, then resumes remote control and processes the queued message from the same session. Shared Codex App Server sessions remain writable while attached.

Troubleshooting

`happier attach` does not find the session

Check that:

the session was started with an attachable mode before it began running,
the session was started on this same machine,
you are authenticated against the same Happier server/account,
for shared Codex attachment, the session uses App Server with Codex CLI 0.131.0 or newer on macOS or Linux.

The session starts in the app but cannot be attached later

This usually means one of the following:

the session was started in a non-attachable mode such as Hidden on Windows,
the session was not launched in the configured terminal host,
the Windows interactive host is no longer running,
the local machine/session ownership does not match the attach attempt.

On Windows, `Windows Terminal` is unavailable

If Happier cannot use Windows Terminal on that machine:

install or update Windows Terminal, or
choose Console or Hidden instead.

The app briefly shows queued or waiting states during switching

Short “waiting”, “pending”, or “resume” states during local ↔ remote switching are normal. Happier may wait for the provider process, transcript source, or daemon heartbeat to settle before the UI fully reflects the new mode.

Attach to a running session

On this page