# Install

Install pumi on macOS, Linux or Windows, and find your way around.


pumi is a terminal app for running coding agents side by side. A window holds sessions, a session holds views, a view holds panes, and a pane holds tabs. Every part of it is a plugin you can turn off, replace or write yourself.

One line installs the app, its server and the `pumi` command, then opens the app. On macOS and Linux:

```sh
curl -fsSL https://pumi.dev/install.sh | sh
```

On Windows, in PowerShell:

```powershell
irm https://pumi.dev/install.ps1 | iex
```

pumi runs on macOS 14 or later (Apple silicon and Intel), Linux with glibc 2.35 or later (Debian 12, Ubuntu 22.04, Fedora 36, Arch; x86_64 and arm64), and Windows 10 1809 or later (x86_64).

Flags go after `sh -s --` (`curl -fsSL https://pumi.dev/install.sh | sh -s -- --version 0.42.0`):

| Flag | |
| --- | --- |
| `--version X` | Install a specific version. |
| `--dir PATH` | Where `pumi.app` goes. macOS: `/Applications`, or `~/Applications` when that is not writable. Linux: `~/.local`. |
| `--no-bin` | Don't put `pumi` on your `PATH`. By default the installer links it into `~/.local/bin` and, when that is not on your `PATH`, adds it in your shell's startup file (`~/.zshrc`, `~/.bash_profile` or `~/.bashrc`, fish's `conf.d`). |
| `--no-open` | Don't open pumi when it is installed. |
| `--uninstall` | Remove the app. Your settings stay. |

On Windows the same are `-Version`, `-Dir` (`%LOCALAPPDATA%\Programs\pumi` by default), `-NoOpen` and `-Uninstall`: `& ([scriptblock]::Create((irm https://pumi.dev/install.ps1))) -Version 0.42.0`. The installer adds `pumi` to your user `PATH` and pumi to the Start menu, and Settings → Apps can uninstall it.

The environment variables `PUMI_INSTALL_VERSION`, `PUMI_DIR`, `PUMI_NO_BIN` and `PUMI_NO_OPEN` do what the flags do. The installer checks the archive's SHA-256 against the release manifest, and the manifest's signature when `minisign` is installed. On Linux it also tells you which desktop libraries (GTK, WebKitGTK, xkbcommon, Vulkan) are missing.

Automatic updates are off by default. Set `autoupdate` to `true` to download new versions in the background and apply them on restart.

The first time pumi opens, its start screen sets it up: the plugins to install, whether agents open in a chat or in their own terminal, whether the window is transparent, and the color scheme. It shows once; Settings changes any of them later.

## From source

You need Rust (the version in `rust-toolchain.toml`), Zig 0.16 and Bun. On macOS you also need the Xcode command line tools. On Debian or Ubuntu, `sudo -E scripts/release/linux-deps.sh` installs what the build links. On Windows you need the MSVC build tools.

```sh
git clone https://github.com/pumi-dev/pumi
cd pumi
(cd runtime/app && bun install)   # the app's JS dependencies, first
./scripts/install.sh              # macOS: build pumi.app and put it in /Applications
scripts/release/build.sh          # any OS: a release build for this machine, into target/<triple>/release
```

## How it fits together

`pumid` is the server. It owns every session, view, pane and tab, and the programs in them, so they keep running when you close the window. The app draws the window and runs the plugins. The `pumi` command talks to the server, and is on the `PATH` of every tab.

```text
session ─ view ─ pane ─ tab      %3 is a tab, :4 a pane, @2 a view, $1 a session, +7 a request
```

A view is what the window shows: its panes, split side by side. A session can have several views, and each window shows one of its own — a second window opens a view of its own, and the view bar switches only that window. A pane holds tabs, with a strip of them on top and one in front; a tab holds a terminal, an agent, a page or a file. Set `pane_tabs` to `false` for one tab to a pane, as in tmux.

pumi opens nothing by itself: every tab is a plugin's. The server runs terminals, but a shell in a tab is the [Terminal](https://github.com/pumi-dev/plugins/tree/main/terminal) plugin, agents are the [Agents](https://github.com/pumi-dev/plugins/tree/main/agents) plugin, and the list of what to open is the [Launcher](https://github.com/pumi-dev/plugins/tree/main/launcher) plugin. On the first run the start screen offers Launcher, Terminal, Agents and Browser, all ticked; untick what you don't want. New tabs then open the first of them you installed, in that order. Settings ▸ General ▸ New tabs open (the `new_tab` option) changes it, from the same list as the `+` menu: Terminal, each agent, the Launcher's list, and the blocks of plugins that add nothing to the menu (Film, Diff). While it names nothing installed, new tabs open the Launcher's list, else a shell, else the first thing on that list. With nothing installed, a new tab doesn't open, and pumi says to install a plugin.

## Files

Everything pumi keeps is in plain files you can read, edit and commit. On macOS and Linux:

| Path | |
| --- | --- |
| `~/.config/pumi/settings.json` | Options and keys you write yourself, `{"options": {…}, "keymaps": [{…}]}`: [Command line](https://pumi.dev/docs/cli/) says what goes in it. Watched: edits apply within a second. |
| `~/.config/pumi/config.ghostty` | The terminals' settings (font, cursor, colours, padding), in Ghostty's config syntax: [Command line](https://pumi.dev/docs/cli/#settings) lists the keys. Watched too. |
| `~/.config/pumi/plugin-lock.json` | Installed plugins and where they came from. |
| `~/.local/share/pumi/installed/` | The plugins themselves (their logs are beside them, in `plugins/`). |
| `~/Library/Application Support/pumi/` (Linux: `~/.local/share/pumi/`) | The server's state: its sessions, views, tabs and options, its log, and its socket (`$PUMI`). |
| `~/.local/state/pumi/plugins/<owner.name>/` | What a plugin keeps between runs. |

On Windows, settings and the plugin lock are in `%APPDATA%\pumi\`, the plugins in `%LOCALAPPDATA%\pumi\data\installed\`, what they keep in `%LOCALAPPDATA%\pumi\state\plugins\<owner.name>\`, and the server's state in `%LOCALAPPDATA%\pumi\`; `$PUMI` is a named pipe. A set `XDG_CONFIG_HOME`, `XDG_DATA_HOME` or `XDG_STATE_HOME` moves the matching directory on every OS.

## Next

- Drive pumi from a shell, set options and bind keys: [Command line](https://pumi.dev/docs/cli/).
- Add a tab, a button or a command: [Plugins](https://pumi.dev/docs/plugins/).
- Redraw the window: [Themes](https://pumi.dev/docs/themes/).

## Work safely

Plugins run with your permissions: your files, your network, every terminal. pumi does not sandbox them. Install what you would run as code.

If a plugin or theme breaks the window, start the app with `--safe`: it draws the default theme and runs no plugin. Settings → Plugins → Safe mode does the same from inside the app.

```sh
open -a pumi --args --safe                                            # macOS
~/.local/pumi.app/bin/pumi --safe                                     # Linux
& "$env:LOCALAPPDATA\Programs\pumi\pumi.app\bin\pumi.exe" --safe       # Windows
```

---

Source: https://pumi.dev/docs/install/ · Index for agents: https://pumi.dev/llms.txt