Omarchy Tmux guide: sessions, panes, detach and return

Tmux keeps shells and their processes in a server that terminal clients can attach to. You can leave the view and later return to the same work. It does not preserve running processes through a reboot or power failure; persistence here means the server is still alive on that machine. The upstream introduction explains the object model; this guide adds Omarchy’s bindings and a bounded practice session.

Understand the four objects

server (owns the running work)
  → session: a project/work context
    → window: a named page of terminal work
      → pane: one shell or running program
client (a terminal viewing a session; can detach)

Action	What happens	What remains
Detach client	Leave the view	Session, panes and their running processes
Close a client terminal	Client disconnects	Normally the server’s work remains
Exit the last shell in a window	Its last pane closes	Other windows/sessions can remain
Kill a session	Ends that session’s panes/programs	Other sessions on the server can remain
Reboot machine	Stops processes including the server	Files on disk, not live Tmux processes

Saving editor files and backing up documents remain necessary. A detached unsaved editor is still an unsaved editor.

Omarchy’s launcher is not always “new session”

The official terminal guide uses Super + Alt + Enter for Tmux. The pinned launcher actually runs tmux attach || tmux new -s Work: it first tries attaching to existing work. Multiple launches can therefore view an existing session rather than create one session per terminal.

If two terminals show the same panes, that can be two clients of the same session. It is not necessarily accidental duplication. Inspect tmux list-sessions and tmux list-clients before creating or terminating anything.

Learn the configured keys, not upstream defaults alone

In the pinned Omarchy configuration, the main prefix is Ctrl + Space, with Ctrl + B as a second prefix. “Prefix, then c” means press/release the prefix before pressing c, not hold all keys together.

Task	Pinned Omarchy binding
Help	Prefix, then ?
Detach	Prefix, then d (retained upstream binding)
New window	Prefix, then c
Rename window	Prefix, then r
Split top/bottom	Alt + Enter, or prefix then h
Split side-by-side	Alt + Shift + Enter, or prefix then v
Move between panes	Ctrl + Alt + Arrow
Resize pane	Ctrl + Alt + Shift + Arrow
Go to numbered window	Alt + 1…9
Copy mode	Prefix, then [; in vi copy mode v selects and y copies
Reload configured file	Prefix, then q

The “vertical/horizontal split” labels are easy to misread; the table names what you see. Window indexes start at 1 in this configuration. Copy behavior still depends on terminal clipboard support; a copied Tmux buffer and the desktop clipboard are not universally identical.

Practice without disturbing your Work session

Use an ordinary terminal outside Tmux. Check that the intended configuration exists, and whether an earlier practice server is already running:

test -f ~/.config/tmux/tmux.conf && echo "Configuration exists"
tmux -L omarchy-guide list-sessions

“No server running” for this named socket is expected on the first attempt. If practice already exists, attach to it rather than replacing it. If it is absent and the config exists, create it:

tmux -L omarchy-guide -f ~/.config/tmux/tmux.conf new-session -s practice

-L omarchy-guide uses a separate server socket. All commands targeting this exercise must retain -L omarchy-guide; the normal Omarchy shortcut uses the default server and will not find this practice session. The -f file is loaded when the named server starts; an already running server can have different settings.

Inside the practice pane, run a harmless repeating task:

while true; do date; sleep 5; done

Split side-by-side, then run pwd in the new pane. You now have one ongoing program and another shell in the same window. Create a new window with prefix then c, rename it notes with prefix then r, and list its contents with ls. Switch back to window 1 with Alt + 1.

Detach with prefix then d. Back in an ordinary terminal, inspect and reconnect:

tmux -L omarchy-guide list-sessions
tmux -L omarchy-guide attach-session -t =practice

The leading = makes the session target exact, as documented in the Tmux manual. The date loop should still be running; this demonstrates client detachment, not survival across reboot. Focus its pane and press Ctrl + C to stop that loop. Confirm it returned to a prompt before closing the practice shells.

If you intentionally want to end everything in this exercise only, detach and use:

tmux -L omarchy-guide kill-session -t =practice

This stops programs in that practice session. Do not use a broad kill-server command to solve a single-pane problem on your normal server.

Diagnose input and persistence problems

Symptom	First check
Ctrl + Space changes input method	Try the configured Ctrl + B prefix; investigate interception in input/global bindings
Prefix works but Alt + Shift + Enter does not	Terminal key encoding; try prefix then v to isolate the split operation
Shortcut returns to old panes	Launcher attaches before creating; inspect sessions
Practice session cannot be found	Named socket retained? Same user and machine?
Work disappeared after reboot	Live server cannot survive reboot; files and deliberate restoration are separate
Clipboard differs from another terminal	Terminal support, Tmux copy mode and actual clipboard integration
Config edit seems ignored	Server loaded config earlier; inspect effective options before restarting

For the exercise, inspect tmux -L omarchy-guide show-options -g prefix, prefix2 and tmux -L omarchy-guide list-keys. For ordinary work omit -L only when you intend the default server. Reloading configuration can change bindings in all sessions on that server; restarting it can terminate their work.

Omarchy’s advanced layout/agent helpers are a later topic. Learn to create, identify, detach, reconnect and stop one task first. Continue with the terminal guide for emulator settings and backups for files that must survive a machine failure.