Getting started

phux

Press C-a d (Ctrl+a, then d) to detach. Run phux again to come back to exactly where you were.

Start phux

phux

The first run starts a server in the background and attaches you to a new session named after the current directory. Your shell runs in a pane inside it. Later runs attach to the session you used last.

Closing the terminal doesn’t end anything. The server keeps your shells and the programs in them running until you end them. Concepts explains the server and what survives what.

The prefix

Every phux key starts with the prefix, C-a (Ctrl+a). Press it, let go, then press the key for what you want. C-a % means “press C-a, then %”.

Keys you press without the prefix go to the program in the pane. phux binds none of them out of the box.

Find any key

You don’t need to memorize anything on this page. Two things show you the keys as you go:

The which-key popup. Press C-a and wait a moment. A popup lists every key you can press next, grouped into Pane, Tab, Session, and phux. It never eats a key: press one and it runs as if the popup weren’t there. Esc cancels the prefix.
The command palette. Press C-a Space (or : or ?) to search every action by name. Each row shows its key, so the palette is also how you learn them.

Default key bindings lists every key on one page.

Split and move between panes

A pane is one terminal. Split the one you’re in:

Keys	Does
`C-a` `%` or `C-a` `\|`	split right
`C-a` `”` or `C-a` `-`	split below
`C-a` `h` `j` `k` `l`	move to the pane left, down, up, right
`C-a` `H` `J` `K` `L`	resize the pane left, down, up, right
`C-a` `R`	resize mode: `h` `j` `k` `l` or the arrows resize one cell at a time; `Esc` leaves
`C-a` `o`	next pane
`C-a` `=`	the pane you were in before
`C-a` `z`	zoom the pane to fill the tab; again to unzoom
`C-a` `x`	close the pane

C-a x closes the pane right away, without asking, and ends the program in it. Capital letters mean Shift: H is Shift+h.

Tabs

A tab holds a set of panes. The status bar along the top shows your tabs.

Keys	Does
`C-a` `c`	new tab
`C-a` `n` or `C-a` `Tab`, `C-a` `p`	next, previous tab
`C-a` `0`–`9`	go to tab 0–9
`C-a` `w`	pick a tab from every session
`C-a` `,`	rename the tab
`C-a` `X`	close the tab and everything in it (asks first)

Sessions

A session is a named workspace, usually one per project. Each holds its own tabs.

Keys	Does
`C-a` `C`	new session
`C-a` `s`	pick a session
`C-a` `N`, `C-a` `P`	next, previous session
`C-a` `)`	the session you were in before
`C-a` `$`	rename the session

From a shell:

phux ls               # list sessions
phux new work         # create a session called "work" and attach
phux attach work      # attach to it later
phux kill work        # end it and everything in it (asks first)

Detach and come back

Press C-a d to detach. The UI closes; your shells, and whatever runs in them, keep going.

phux

Run phux again, from this terminal or any other, to pick up where you left off. Losing an SSH connection is the same as detaching.

Scroll and copy

Scroll a pane’s history with the mouse wheel. For keyboard selection, press C-a [ to enter copy mode:

Keys	Does
arrow keys	move the cursor; at the edge, scroll
`Shift`+arrows	extend the selection
`PageUp`, `PageDown`	scroll a page
`Tab`	switch between character, line, and block selection
`/`, `?`	search down, up; `n` and `N` repeat
`Enter`	copy the selection and leave
`w`, `v`, `A`	copy the word, the line, or everything, and leave
`]`	copy the last command’s output and leave
`Esc`	leave without copying

Copies go to your system clipboard through your terminal (OSC 52), so they work over SSH too if your terminal allows it.

Mouse

The mouse is on by default:

Click a pane to focus it.
Drag a divider to resize panes.
Drag across text to copy it.
Right-click for a menu of actions for that pane, tab, or session.
Click a tab to switch to it; drag it to reorder.

Programs that use the mouse themselves, such as htop or an editor, still get clicks over their own panes. To leave the mouse to your terminal’s own selection instead, set mouse = false under [defaults] in your config file.

The sidebar lists your coding agents (with which ones need you) and your sessions. Press C-a b to show or hide it. On a narrow terminal it stays hidden so your panes get the room.

When an agent is waiting on you, C-a q jumps to it and C-a Q takes you back. C-a A opens every agent and its state. Coding agents covers the rest.

Coming from tmux

Already have tmux configured the way you like? Run phux config import-tmux to preview a native config layer and a report of what carries over. See Bring your tmux keys to phux before applying it.

Most keys match tmux, with C-a where tmux uses C-b. What’s different:

In tmux	In phux
prefix `C-b`	prefix `C-a`; set it back if you like
“window”	“tab” in the UI; actions in the config file still say `window` (`new-window`)
arrow keys move between panes	`h` `j` `k` `l`
`;` last pane	`=`; `;` is the previous pane
`x` asks before closing a pane	`x` closes it right away
`&` closes a window	`X` closes a tab (asks first)
`(` `)` previous, next session	`P` `N`; `)` is the last session
`q` shows pane numbers	`q` jumps to the next pane that needs you
`send-prefix` sends the prefix through	press the prefix twice: `C-a` `C-a` sends `C-a` to the program. Any key with no binding after the prefix goes to the program
copy mode with vi or emacs keys	arrow keys; `Enter` copies to the system clipboard
`tmux source-file ~/.tmux.conf`	`phux config reload`
`tmux capture-pane -p`	`phux snapshot`
`tmux kill-server`	`phux kill --server`

For when tmux is still the better fit, see phux vs tmux, Herdr, and cmux.

Keep C-b

Put this in ~/.config/phux/config.toml:

[keybindings]
prefix = "C-b"

Then reload with phux config reload. Key bindings covers rebinding and unbinding any key.

Concepts: sessions, tabs, panes, targets, and what survives a restart.
Driving terminals from scripts: everything above, from a shell or a coding agent.
Key bindings: make the keys your own.
Remote machines: attach to a server on another machine.