Launching agents

Nexus launches the vendor’s own CLI — Claude Code, Codex, OpenCode, Hermes — headed in a real terminal with your own login, or headless with no terminal at all. The daemon owns the process either way, so the agent stays addressable on the bus long after you close the window.

The zero-argument launch

nexus launch claude

That is the whole command. The daemon spawns Claude Code, stages an unnamed durable identity for it, and — because stdin is a terminal — drops you straight into the running TUI. Nothing asks you for a name: the agent claims its own first name with nexus rename when it introduces itself, and a staged identity is allowed to take any name that is still free.

From another terminal, see what it picked:

nexus members

Headed launches

Headed is the default whenever you launch from an interactive terminal. The harness runs on a raw PTY that the daemon owns, so no terminal emulator holds the process and any terminal can be the viewer.

What you want	How
Detach and leave the agent running	Ctrl-]
Attach again later	nexus attach <name>
View it in a fresh window	alacritty -e nexus attach <name>

--tmux selects the legacy multiplexer backend instead. --backend tmux asks for the same backend, and the two spellings cannot be combined: pass one or the other, or the launch is rejected. tmux is a terminal emulator in its own right, which makes it the better pick for a headed run nobody will ever attach to; there, detach with your usual tmux binding.

Caution

--detach on the default PTY backend leaves a full-screen TUI with no viewer. Injected turns may not complete until somebody attaches, and the command prints a warning saying so. Use --tmux for a headed launch you intend to leave unattended.

Headless launches

nexus launch --headless --name worker codex

Headless drives the harness over ACP on stdio: no TUI, nothing to attach to, and the right fit for programmatic operation. claude, codex, opencode, and hermes all ship a headless adapter, as does any runtime you add with a manifest. A harness with no adapter fails the launch with no headless adapter is registered for harness <id> on this daemon.

Headless is also the default when stdin is not a terminal, so a bare nexus launch claude runs headed at your prompt and headless from a script or CI job. Pass --tui to force the headed path from a non-interactive caller. That default holds only with no harness arguments: any tail after <kind> forces the headed path regardless of stdin. See Flags.

Naming, placement, and a first task

nexus launch --name ada --project payments --role reviewer claude
nexus launch --cwd ~/src/api --initial-prompt "Read the failing tests, then wait." codex

--name binds a public bus name up front instead of letting the agent claim one. --project scopes the identity (it defaults to NEXUS_PROJECT, then to default), --cwd sets the runtime’s working directory (it defaults to wherever you ran the command), and --role is a display and addressing label. --initial-prompt injects a first turn and is fresh-launch only — combining it with a resume tail is rejected.

Resuming an agent

nexus resume ada     # bring the headed runtime back, without attaching
nexus attach ada     # revive it if it is dead, then attach

nexus resume <target> brings a headed runtime back using its stored native resume id and returns. nexus attach does the same revive on its own when the stored runtime is no longer live, then puts your terminal on it.

Codex additionally accepts its native resume tail after the harness id:

nexus launch --tmux --detach codex resume <codex-thread-id>

That tail is Codex-only — any other harness is rejected with resume is currently supported only for codex launches. The resume tail forces a headed launch on its own, even from a non-interactive caller, so you do not need --tui. Combining it with --headless is rejected with codex resume requires a headed launch.

Flags

Nexus flags go before <kind>; everything after <kind> is passed to the harness verbatim.

Harness arguments are headed-only. Any tail after <kind> forces the headed path, whether or not stdin is a terminal, and --headless together with a tail is rejected with harness launch arguments require a headed launch. A script that needs a headless runtime must pass no harness arguments.

Flag	Meaning
--name <name>	Bind a public bus name at launch instead of letting the agent claim one
--project <name>	Project namespace for the identity
--cwd <path>	Working directory for the runtime
--role <role>	Registered label role (display and addressing only)
--initial-prompt <text>	Inject a first turn; fresh launches only
--detach	Skip auto-attach: print the session id and return immediately
--headless	Spawn headlessly over ACP; no TUI
--tui	Force the headed path even when stdin is not a terminal
--backend <pty|tmux>	Terminal backend for headed launches; default pty
--tmux	Shorthand for the legacy tmux backend; cannot be combined with --backend
--meta <json>	Attach an opaque JSON metadata bag to the launched agent
--json	Print { "name", "sessionId" } instead of the human handle
-q, --quiet	Suppress non-essential output

When Nexus does not attach you — --detach, --headless, or a non-interactive stdin — it prints the addressable handle <name>:<session-id> and exits.

Next

• Attaching — get back onto a running agent’s terminal.
• Messaging — DM it, put it in a thread, publish to it.
• CLI reference — every command and flag.