Attaching

nexus attach <name> puts your terminal on the agent’s own interactive CLI — the real Claude Code or Codex screen, not a rendering of it. The agent keeps running when you leave.

nexus attach ada

If the agent is not running

Attach repairs before it connects. When the stored runtime points at a dead local target, Nexus prints that it found no live terminal target, reads the agent’s revive plan from durable state, re-submits the same daemon-owned launch command that nexus launch --detach uses, and attaches to the session that comes back.

A headless Claude runtime can also be repaired into a headed one this way, using its stored native session id. To revive without taking over the terminal, use nexus resume <name> instead.

Detaching

Backend	Detach with
Raw PTY (the default)	Ctrl-]
--tmux runtimes	your tmux detach binding, normally Ctrl-b d

Either way the harness keeps running daemon-owned and stays addressable on the bus. Detaching is not stopping.

Some 0.1.6 builds print detach: Ctrl-b d in the launch banner. Ctrl-] is the key for the default backend; Ctrl-b d applies only to --backend tmux.

Attaching by session id

nexus attach takes a name. nexus pty-attach takes the session id that nexus launch printed, which is what you want when a name is ambiguous or the agent has not claimed one yet:

nexus pty-attach s_4b1e7c0a9d5f42a8b3c6e01d7f28a95c

Attaching from another terminal

Because the PTY belongs to the daemon and not to a terminal emulator, any emulator can be the viewer. Open an agent in its own window:

alacritty -e nexus attach ada

If you are already inside tmux and the runtime is tmux-backed, attach opens the harness in a new tmux window rather than nesting a session inside your own.

When attach does not apply

Headless runtimes have no terminal. Apart from the Claude repair path above, an agent launched with --headless cannot be attached — talk to it with nexus dm and read its output with nexus history.

Troubleshooting

Attach records a lifecycle event before it hands your process to the terminal, and that event is operator/self-gated so a terminal takeover is never silent. If the record fails the attach stops rather than continuing quietly. An UNAUTHORIZED error here means the caller is neither the local operator nor the session itself. The gated sentence is appended in parentheses to the underlying contract error, so the line you see reads:

<underlying error> (attach lifecycle events are operator/self-gated for session s_...; use an
operator client or attach only your own session)

If Nexus reports no terminal endpoint for a session, that runtime is not a live raw-PTY headed session: the daemon is down, the session died, or the runtime is tmux-backed. Start with nexus daemon status.

Next

• Launching agents — headed and headless launches, and the backends behind them.
• Messaging — reach an agent without taking its terminal.