# Run Qesh in your terminal

## Requirements

Use macOS with Bun 1.3.5 or newer and Node.js 22.13 or newer. The project CI uses Node.js 24. Run `bun --version` and `node --version` to check them.

## Install and launch

```sh
git clone https://github.com/qentrah/qesh.git
cd qesh
bun install --frozen-lockfile
./bin/qh --help
./bin/qh
```

Qesh takes over the current terminal window. It starts a shell in the current directory using `$SHELL`, with `/bin/zsh` as the fallback. Press Ctrl+B, release it, then `q` to quit; confirm the live-session dialog. The host terminal should return.

To start in another folder, use the absolute path to the cloned launcher:

```sh
cd ~/Documents
/path/to/qesh/bin/qesh
```

Replace `/path/to/qesh` with your actual clone path. The launcher needs Bun and Node.js on `PATH`. The desktop download does not install a global `qesh` command. If you want a global command from the source checkout, run `bun link` in the repository, then `qesh --help`.

## Keyboard controls

All commands below follow Ctrl+B, then release the keys before the next key:

| Key | Action |
| --- | --- |
| `c` | New tab |
| `n` / `p` | Next / previous tab |
| `%` / `"` | Side-by-side / stacked split |
| Arrow keys | Focus a pane |
| Shift+arrow | Resize a divider |
| `r` | Rename the current tab |
| `x` / `w` | Close a pane / tab |
| Page Up / Page Down | Scroll history |
| `?` | Show keyboard help |
| `q` | Quit |
| Ctrl+B again | Send a literal Ctrl+B to the shell |

Ctrl+C and ordinary typing go to the focused shell. Do not type desktop commands such as `/config` at the shell prompt; those belong in the desktop Commands panel.

## Keep your own zsh prompt

```sh
QENTRAH_SHELL_STYLE=original ./bin/qh
```

This disables Qesh's prompt and command-highlighting customization. User startup files still load. See [themes](/docs/qesh/themes) for CLI colors.