--- title: "Getting started" url: "https://docs.phux.sh/getting-started" source: "https://github.com/no-phux/phux/blob/55f11eff5e728ade431f9e53a4335b447f242f1d/docs/getting-started.md" projectVersion: "0.112.0" protocolVersion: "1.0.0" stability: "stable" --- # Getting started This page walks through a first session: start phux, split and move between panes, open tabs and sessions, detach, and come back. It assumes phux is installed. ```sh phux ``` Press C-a d (Ctrl+a, then d) to detach. Run `phux` again to come back to exactly where you were. ## Start phux ```sh 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](/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](/reference/keys) 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: ```sh 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. ```sh 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](/config). ## The sidebar 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](/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](/tmux-import) 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](#keep-c-b) 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](/compare). ### Keep C-b Put this in `~/.config/phux/config.toml`: ```toml [keybindings] prefix = "C-b" ``` Then reload with `phux config reload`. [Key bindings](/keys) covers rebinding and unbinding any key. ## Next - [Concepts](/concepts): sessions, tabs, panes, targets, and what survives a restart. - [Driving terminals from scripts](/scripting): everything above, from a shell or a coding agent. - [Key bindings](/keys): make the keys your own. - [Remote machines](/remote): attach to a server on another machine.