Run Claude Code in the Background: amux start --detach

Start AI coding agent sessions without occupying a terminal. Return to your shell immediately. Monitor from your phone.

By default, amux start SESSION_NAME creates a tmux session and attaches your terminal to it — you see the agent's output live. This is great for interactive work. But for boot scripts, justfiles, SSH one-shots, CI triggers, and overnight batch runs, you need the session to start without attaching. That's what amux start --detach (or -d) does: it launches the agent and returns immediately, leaving you in your own shell. Updated July 2026.

The one-flag difference

# Without --detach: attaches terminal, blocks until you exit the session
amux start my-agent

# With --detach: starts session, returns immediately (exit 0)
amux start my-agent --detach
# or
amux start my-agent -d

Under the hood, both commands create the tmux session with new-session -d (detached by default at the tmux level). The difference is what amux does next: without the flag it calls attach-session; with the flag it skips that step and exits. The agent is identically configured either way.

If the session is already running and you call amux start NAME -d, amux reports its status and exits without attaching — useful for idempotent scripts that shouldn't fail if the session is already up.

When to use detached mode

Boot scripts and system autostart

Starting agents on machine boot is the classic use case. Without --detach, a launchd plist or systemd unit that calls amux start would block waiting for a terminal that never comes.

# macOS launchd plist (~/Library/LaunchAgents/com.amux.agents.plist)
<key>ProgramArguments</key>
<array>
  <string>/usr/local/bin/amux</string>
  <string>start</string>
  <string>overnight-agent</string>
  <string>--detach</string>
</array>

Justfiles and Makefiles

Launch multiple agents as part of a project bootstrap, then continue with other setup steps:

# justfile
bootstrap: agents serve
  echo "Project ready"

agents:
  amux start feature-agent -d
  amux start test-agent -d
  amux start docs-agent -d

serve:
  amux serve &

SSH one-shots

Trigger a session remotely and disconnect without the session dying:

# Start an agent on a remote machine and disconnect
ssh myserver "amux start overnight-refactor --detach"
# Session keeps running after SSH exits

CI pipelines

Some teams use amux in CI to kick off a long-running agent task (documentation generation, test fixture creation, dependency updates) and check results in a separate step:

# GitHub Actions step
- name: Start docs agent
  run: amux start docs-agent -d

# ... other steps ...

- name: Check docs output
  run: amux peek docs-agent --lines 50

Overnight batch jobs

The most common use: go to bed with your agent running. Start it detached, enable self-healing, and wake up to completed work.

# Evening: kick off the sprint backlog
amux start sprint-agent -d
# Agent runs overnight, self-heals on crash, you monitor from phone
# Morning: check output
amux peek sprint-agent

How to start a detached agent session

1. Register your project (once):

   amux register myproject --dir ~/Dev/myproject --yolo

   The --yolo flag enables auto-approval for non-destructive operations — recommended for truly unattended sessions.
2. Start in detached mode:

   amux start myproject --detach

   The command prints the session name and exits. Your shell prompt returns immediately.
3. Verify it's running:

   amux status
   # or
   amux ls

   You'll see the session listed as active.
4. Start the dashboard (if not already running):

   amux serve &

   The dashboard at https://localhost:8822 shows all sessions with live streaming output. Access it from your phone via the iOS app or browser PWA.
5. Peek at session output without attaching:

   amux peek myproject --lines 100

Monitoring detached sessions from your phone

The whole point of detached sessions is that you're not at your terminal — you're somewhere else. amux is built for this. The iOS app and browser PWA both show live streaming output from all sessions, let you send new instructions, approve pull requests, and steer sessions mid-task.

# Make the dashboard reachable from your phone on the same network
amux serve --host 0.0.0.0

# Or use the amux tunnel for remote access from anywhere
amux tunnel start 8822

See Managing agents from your phone for the full setup.

Detached sessions and self-healing

Self-healing runs at the amux server level — it's independent of how the session was started. A detached session gets the same watchdog behavior as an interactive one:

• Context compaction: when a session's context window fills, amux auto-compacts and continues.
• Crash detection: if the agent process exits unexpectedly, amux detects it within seconds.
• Automatic restart: amux restarts the session and replays the last message so the agent picks up where it left off.

This combination — --detach plus self-healing — is what makes overnight unattended operation practical. You don't need to babysit a terminal or worry about context exhaustion killing your agent at 2 AM. See Self-healing configuration for tuning options.

Attaching to a detached session

Any time you want to see the live terminal output, attach directly with tmux:

tmux attach -t myproject

Or use amux peek myproject for a non-interactive snapshot without occupying your terminal.

Frequently asked questions

See also

• Self-healing configuration — keep agents running overnight automatically
• Managing agents from your phone — monitor detached sessions from anywhere
• Running 10+ agents in parallel — launch a full fleet in detached mode
• AI coding while you sleep — overnight unattended workflows
• Expose a localhost port to the internet — access your dashboard remotely without VPN

amux start my-agent --detach  # non-blocking, returns immediately
amux serve &                  # dashboard at localhost:8822
# agent runs, self-heals, you sleep