Sesh Terminal Sessions

Starting work with sesh

When work needs to start somewhere other than the shell you're in, call sesh, not tmux.

Reaching for tmux new-session -s <name> or tmux new-window -t <session> throws away what the user set sesh up to do: resolve a rough name or a directory to the right session, start it from its configured root with its startup commands, reuse what's already running instead of duplicating it, and decide whether to move the user or leave them where they are.

If sesh is not on PATH, fall back to raw tmux. Otherwise use the commands below.

Session or window?

This is the first decision, and the one most worth getting right.

A session per unit of work. That's the model — a project, a repo, a directory. If the work has its own directory, it wants its own session:

sesh connect ~/c/sesh
sesh connect sesh          # a name works too; sesh resolves it

A window when it belongs inside a context that already exists. Reach for a window when the work is part of a session that's already running rather than a thing of its own:

sesh window connect claude -t 'second brain' -c 'claude "<prompt>"'

Good reasons to add a window instead of a session:

• The user named a session to put it in ("in my dotfiles session", "next to what I'm working on")
• The work is a second track in the same project — tests, logs, an agent, a dev server — and the session for that project is already open
• You're already inside the right session and just need another place to run something

If neither applies, use a session. Don't create a window in an unrelated session just because that session happens to be attached.

Either way, both commands select-or-create: they reuse what's there and only create on a miss, so it's safe to run them without checking first.

Sessions

sesh connect <name|directory>

Connects to the session, creating it if it isn't running. The argument can be a path, a session name, a zoxide result, a configured session, or a tmuxinator config — sesh resolves across all of them, which is the main reason to call it instead of tmux.

sesh connect ~/c/sesh              # by path
sesh connect sesh                  # by rough name
sesh connect 'second brain' -s     # names with spaces need quoting
sesh connect ~/c/api -c 'npm run dev'

That -c caveat is the sharp edge: if the user might already have the session open, sesh connect -c may do nothing at all. To run a command in a session that may already be running, add a window (next section).

Two related entry points, for when the directory doesn't exist yet:

sesh mkdir ~/c/new-project -c '<command>'   # create the directory, then connect to it
sesh clone <repo>                           # clone a git repo and connect to it

Use sesh mkdir rather than mkdir && sesh connect — it's one step and doesn't wait on zoxide.

Windows

sesh window connect <name|directory> -t <session> -c '<command>'

Selects the window called <name> in <session>, creating it if it isn't there. Prints the window's session:index target.

sesh window connect tests -c 'npm test -- --watch'   # in the current session
sesh window connect ~/c/sesh -t dotfiles             # window "sesh", rooted at that path

A directory argument is named after its basename and rooted there, so running it twice selects the window the first run created rather than duplicating it.

--command means different things on create and reuse

Identity is the window name:

• Created window — the command becomes the window's process. The window closes when it exits.
• Existing window — the command is typed in as keystrokes, into whatever is already running. If that's a shell, it runs. If it's a long-running process, you just typed at that process.

So launching an agent twice with the same window name starts one agent, then types the second prompt into the first agent's input. When each invocation must get its own window, pass --new:

sesh window connect claude -t 'second brain' --new -c 'claude "<prompt>"'

--new always creates, letting windows share a name; a later connect without it reuses the lowest-indexed one. Omitting the name also always creates — there's nothing to match on.