tmux new session: create, name and start detached

tmux new-session -s name (alias: tmux new -s name) creates a session called name and attaches to it immediately. Add -d to create it without attaching, -c path to set the directory it starts in, and -A to attach to an existing session of that name instead of failing. Running bare tmux does the same thing with an auto-generated numeric name, which is fine for a throwaway session and annoying for anything you plan to come back to.

How do you create a tmux session with a name?#

tmux with no arguments creates a session named 0, or the next free integer if 0 is taken. That works right up until you have three of them and tmux ls shows:

0: 1 windows (created Mon Jul 14 09:12:41 2026)
1: 1 windows (created Mon Jul 14 09:14:02 2026)
2: 1 windows (created Mon Jul 14 09:15:47 2026)

None of that tells you which one is running the deploy and which one is htop. Name it at creation time instead:

tmux new -s deploy
tmux new -s scratch

Now tmux ls reads deploy: 1 windows... and scratch: 1 windows..., and tmux attach -t deploy does what it says. Naming costs nothing at creation time and saves real time every attach after that — see tmux attach session for what you do with the name once you have it.

Session names are matched by prefix everywhere a -t appears, so tmux attach -t dep finds deploy as long as nothing else starts with those letters. Two sessions named api and api-old will make you type the whole thing; that is a good argument for names that differ early rather than late.

How do you start a tmux session without attaching to it?#

tmux new -s ci -d creates the session and returns you to your current shell instead of switching into it. This is the form you want from a script, a cron job, or anywhere you are bootstrapping a session you will attach to later — or never, if it is just running a build.

Without -d, tmux new -s ci would have taken over your terminal, which is wrong for a CI-style session you want to keep polling with tmux capture-pane rather than sit in front of.

If you need the new session's identity back in the script — to feed it to another command — -P prints it, and -F picks the format:

id=$(tmux new -d -s ci -P -F '#{session_id}')
echo "$id"   # $2

How do you set the starting directory for a new session?#

By default a new session starts in whatever directory you ran tmux from. -c overrides that:

tmux new -s work -c ~/projects/api

This matters more than it sounds like once you have a dotfiles script creating several sessions from $HOME — without -c every one of them starts in your home directory and you cd manually into each one. -c also accepts - in attach-session/switch-client to reuse the current client's directory, but for new-session you give it a real path.

Note that -c sets the directory for the session's first window only. Windows you create later inherit default-path behaviour, which since tmux 1.9 means "the directory the pane you were in was in" — a change that surprised a lot of people and is documented in the tmux changelog.

How do you rename a tmux session?#

Three ways: at creation with -s, or after the fact with rename-session from a shell, or prefix $ while attached.

Renaming does not touch the windows or panes inside — it only changes the label tmux and every other command uses to refer to the session. Nothing running notices.

Can you name the first window at the same time?#

-n on new-session names the initial window, which is worth doing if you already know what it is for:

tmux new -s work -n editor

That gives you work:editor instead of work:0, one step ahead of the renaming you would otherwise do with prefix ,. It also makes send-keys -t work:editor readable in a script, which is the real payoff — targeting work:0 works until you reorder windows.

How do you run a command when the session starts?#

Pass it as a trailing argument. new-session takes an optional shell-command, and when you give it one, tmux runs that instead of your login shell:

tmux new -d -s build 'npm run build'

The catch, and it is the one that catches everybody: the session ends when the command exits. A build that finishes in ninety seconds leaves you with no session and no output to read. If you want to inspect what happened, set remain-on-exit so the pane stays with the output frozen in it:

tmux new -d -s build \; set -t build remain-on-exit on \; \
  send-keys -t build 'npm run build' Enter

Or, more simply, start a normal shell and send-keys the command into it — which is what the bootstrap script further down does. Keeping a shell underneath means the pane survives whatever you run in it, and you can type the next thing without recreating the session.

How do you create a session only if it doesn't exist?#

The pattern that actually matters for automation is "create this session if it does not exist, attach to it if it does" — you do not want a bootstrap script to fail with duplicate session every time you re-run it. new-session -A does exactly that:

tmux new-session -A -s work

-A makes new-session behave like attach-session when the session already exists. Run it once and you get a fresh session; run it again from the same or a different terminal and you attach to the one already running. Combined with -d it becomes "ensure this exists", which is the form you want at the top of a script:

tmux new-session -A -d -s work

For anything with more than one window, has-session as an explicit guard reads more clearly:

has-session exits 0 if the session exists and non-zero if it does not, which is exactly the shape a shell && guard wants. This same pattern is worth stealing for any dev-environment bootstrap — see the scripting section of tmux commands for more of it, and tmux plugins if you would rather have tmux-resurrect restore the layout than write the script yourself.

What is a grouped session, and when do you want one?#

-t on new-session does something different from -t everywhere else: it creates a new session in the same group as the target, sharing its window list.

tmux new-session -d -s work-2 -t work

Both sessions now show the same windows, but each has its own current window and its own size. That is the fix for the resize problem two people hit when they attach to one session from a 27-inch monitor and a laptop: normally tmux shrinks the display to the smallest attached client, and a grouped session gives each client its own view instead. The tmux manual documents the flag under new-session; the sizing behaviour it works around is covered in tmux attach session.

Killing one session in a group does not kill the windows — they belong to the group, and survive as long as any member session does.

Why does tmux say "duplicate session"?#

Creating a session with a name that already exists does not silently attach you to it — it refuses:

That is tmux new-session, not -A. Either attach instead (tmux attach -t work), pick a different name, or use tmux new-session -A -s work if you want "create or attach" behaviour without checking first.

How do you check on a detached session?#

-d sessions are easy to lose track of, especially a long build kicked off before you left for the day. tmux capture-pane -p -t ci from another terminal will print the pane's current contents, which is the honest way to check on it without a second tool:

tmux capture-pane -p -t ci | tail -20

Add -S -2000 to reach back into scrollback rather than just the visible screen.

If you would rather open the session and look than shell in first, that is what a browser client is for — it serves the sessions you already created with tmux new -d to a tab on any device, including a phone with no SSH client and nothing forwarded to it. mtmux is one of those; the two-minute quickstart is the whole setup, and the session list shows what it does with the sessions tmux new created.