Chapter 4: Sessions - Create, Name, Detach and Reattach

So far, you have installed tmux, started your first session, and learned how the prefix key works.

Now we get to the feature that makes tmux genuinely useful. Sessions. A tmux session is a workspace that can keep running even after you leave it. This is what allows you to disconnect from a server and come back later without rebuilding everything from scratch.

Let's see how that works.

What Is a Tmux Session?

Whenever you run:

tmux

tmux creates a session for you. You can think of a session as a container for your terminal work.

For example:

Session: my-project 
          │ 
          ├── Window 0 
          ├── Window 1 
          └── Window 2

Later, those windows can contain multiple panes, but for now, focus on the session itself.A session usually represents one main context.

For example:

my-project
production
debugging

You might use separate sessions for separate projects, servers, or tasks.

Create a Named Session

If you know what the session is for, it's much better to give it a name. Use:

tmux new -s my-project

Here:new tells tmux to create a new session. -s means we are giving the session a name.my-project is the session name.

Now you have a session called my-project. Naming sessions becomes especially useful when you have more than one. Instead of wondering which session is which, the name tells you immediately.

See Your Sessions

Now let's say you have created a few sessions. How do you find out which ones are currently running?

Run:

tmux ls

or:

tmux list-sessions

You'll see something similar to:

The exact output will be different on your system. The important part is that tmux is showing you the sessions that currently exist.

This becomes one of the commands you'll use often when working with multiple sessions.

Detach Without Stopping Your Work

Now let's try the most important part. Suppose you're inside your my-project session and a command is running.

You don't want to close the session. You simply want to leave it for now. This is where detach comes in.

Press:

Ctrl+b d

Remember how the prefix works: Press Ctrl+b, Release both keys, Press d.

You should see something like:

You are now back in your normal terminal. But here's the important part: The tmux session is still running. You have left the session without shutting it down.

Reattach to Your Session

Now let's get back into the session. First, list your sessions:

tmux ls

Then attach to my-project:

tmux attach -t my-project

You can also use the shorter form:

tmux a -t my-project

You're back. Your windows are still there. Your windows are still there. Your panes are still there and any process that continued running is still there.

Rename a Session

Sometimes you create a session with a temporary name and later realize you want something clearer.

You can rename the current session using:

Ctrl+b $

Enter the new name and press Enter.

You can also rename a session from the command line:

tmux rename-session -t my-project api-server

Now the session is called:

api-server

It will look similar like this:

Kill a Session

When you are completely finished with a session, you can remove it.

From outside tmux:

tmux kill-session -t api-server

Or, while inside the session, you can simply exit all shells in that session. Be careful here. Killing a session closes it and terminates the processes running inside it.

Now you can now manage the basic lifecycle of a tmux session: Create, Name, Use, Detach, Reattach, Rename / Kill a session.

But a session alone isn't enough for a useful workflow.

Soon you'll want one place for logs, another for your editor, another for commands, and perhaps another for monitoring.

That's where windows come in. In the next chapter, we'll learn how to organize multiple tasks inside the same tmux session.