The docs.
every command, key and setting, on one page · new here? start with install and your first run
Install
pando ships a ready-made binary for macOS (Apple silicon and Intel) and Linux (x86_64 and arm64). Homebrew and the install script need no Rust. On Windows it runs inside WSL 2 as the Linux binary: see Platforms.
With Homebrew
On macOS or Linux, WSL 2 included:
brew install mertkaradayi/tap/pandoWith the install script
With nothing else installed, this one line does the same:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mertkaradayi/pando/releases/latest/download/pando-cli-installer.sh | shThe script puts pando in $XDG_BIN_HOME when that is set, and otherwise usually in ~/.local/bin, and adds that directory to your PATH in your shell's startup files. To leave those files alone, run it with PANDO_CLI_NO_MODIFY_PATH=1 set. Running the line again later installs the newest release.
From source
Building pando yourself needs Rust 1.88 or newer. With no Rust on the machine, rustup installs the current stable toolchain first, and a new terminal then has cargo:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh $ cargo install --locked --git https://github.com/mertkaradayi/pando pando-cli
--locked builds with the exact dependency versions CI tested. Without it, cargo may pick newer ones that need a newer Rust. On a new Mac, git comes with the Xcode Command Line Tools (xcode-select --install).
There is no crate on crates.io yet.
Checksums and attestations
Every download has a checksum and a GitHub attestation. To prove a file was built from this repository, run gh attestation verify <file> -R mertkaradayi/.
Staying current
pando updateIt updates pando to the latest release the same way it was installed, and leaves your shell's files alone:
| Installed with | What pando update runs |
|---|---|
| Homebrew | brew upgrade of the formula |
| cargo | cargo install --locked again, at the latest release's tag |
| the install script, or a copy anywhere else | the install script, into the directory the binary is in |
| a build made in a checkout of pando | nothing: it says how to update that checkout |
pando --version says which version you have. pando update --check says whether a newer release is out and which command would install it, and runs nothing. What changed in each release is in the changelog.
Shell completions
pando completions zsh prints a completion script, and so does the same command for bash, fish, elvish or PowerShell. In bash, zsh and fish it completes worktree names too.
Trying it on a fixture first
Want to see pando before you point it at your own project? In a clone of pando's repository, with Rust installed, the test suite can build repositories of every shape it knows. One of them is a good place to start:
# the shapes the tests use $ scripts/fixture-repo.sh --list # build one in a temporary directory, and print how to run pando in it $ scripts/fixture-repo.sh mono-web-api --listener
Your first run
Open a terminal in a git repository you work on, the one with the dev server you wish you could run on two branches at once, and run pando:
$ cd your-project $ pando
There is nothing to configure first, and what pando learns about the project is kept in ~/.pando, outside your repository. The first time, in a project with nothing to run yet, pando opens its setup screen instead of the list.
The setup screen
The screen is drawn over a grove grown from your project's name, whose roots light up when the setup passes. Every project is a little different, so the surest start is to let your own coding agent look at it:
- Copy one line. Press a to copy this prompt:
Set up pando here: run `pando init --agent` and follow what it says. - Paste it into your agent. Claude Code or Codex, opened in the same project.
- Come back. The screen turns green by itself when the setup is done. From then on,
pandoopens the list.
What your agent does
pando init --agent prints the job for this project and this version of pando: what pando already sees, the questions still open, and the steps. Your agent then:
- Decides what pando's rules leave open, from the project's own evidence, and asks you nothing.
- Answers through pando, with
pando init --answers -on stdin, never a file in your repository.--dry-runpreviews, and--replacecorrects an answer. - Proves it with
pando check: a throwaway worktree, installed, started, asked for its first page, and removed. - Reports what it set, why, how to change it, and what one worktree costs on disk. It never ends on a question.
It can also remember how to run the project with pando, in its own memory, if you say so.
No agent, or no setup
No agent? Press ⏎ on the setup screen and pando tries its own guess, tested by the same pando check. Press esc to skip the setup and go straight to the list. Nothing is ever gated on it, and the screen is not shown again. A project configured before the setup screen existed is never sent there.
pando new and pando start work on a project that was never set up, too: they take pando's first choice and say so.
Your first worktree
Work on a second branch next to the first:
$ pando new feat/checkout # its own checkout, dependencies installed $ pando start feat/checkout # its own dev server, on ports of its own $ pando open feat/checkout # in your browser
Your main checkout is untouched and still runs as before. In the TUI: n, type the branch, ⏎ to make it; ⏎ on its row to pick a mode and start; o to open. pando rm feat/checkout stops the worktree and removes the checkout and its data. The branch stays.
Then run pando doctor to see which tools the project will need.
What it needs
pando itself is one binary. Only git is required. Every other tool is needed only for the feature beside it, and only when your project uses that feature. pando doctor checks each one, says which command needs which, and prints the install command for any that is missing. pando never installs anything on your machine by itself.
| Tool | Needed for | macOS | Linux |
|---|---|---|---|
git | everything | xcode-select --install | your distribution's git |
curl | pando update, to find the latest release | comes with macOS | your distribution's curl |
cloudflared | pando share, a public URL for a worktree. No account. | brew install cloudflared | Cloudflare's package |
gh, signed in | the TUI's pull request picker | brew install gh | the GitHub CLI's package |
| Docker with Compose | isolated starts, when the project's services are in a compose file | Docker Desktop or OrbStack | Docker Engine and its compose plugin |
redis-server, redis-cli | a private Redis without Docker; redis-cli alone for namespaced starts | brew install redis | redis-server, redis-tools |
mariadbd, mariadb | a private MariaDB without Docker; the mariadb client alone for namespaced starts | brew install mariadb | mariadb-server, mariadb-client |
postgres, psql | a private Postgres without Docker; psql alone for namespaced starts | brew install postgresql@16, or brew install libpq for psql alone (keg-only: put its bin on PATH) | postgresql, postgresql-client |
mongod, mongosh | a private MongoDB without Docker | brew install mongodb/ | MongoDB's package |
A namespaced start needs no server of its own. It uses the servers your main checkout already runs, with their client on the host or inside the container that runs the server. A search, queue or cache engine whose app reads a name prefix needs nothing at all.
The usual pair on a Mac, for sharing and pull requests:
brew install cloudflared ghYour project's own toolchain, such as Node and its package manager, Python or Go, is whatever you already run it with. pando finds it the way a bash login shell (bash -l) does, and never replaces it. pando doctor names any it cannot find, with how to get it.
Platforms
macOS
pando is developed on macOS, on Apple silicon and Intel. On APFS, a new worktree is a copy-on-write clone of your main checkout (see Light on disk).
Linux
Binaries ship for x86_64 and arm64. CI runs the whole test suite on Linux for every change, and it must pass, but nobody has used pando on Linux for real work yet. Copy-on-write works on btrfs, XFS and bcachefs. On ext4, which cannot clone, pando uses git's own checkout.
Windows, with WSL 2
On Windows, pando runs inside WSL 2 as the Linux binary. Install it in your distro any of the ways under Install.
- Keep the repository under
~in WSL, not on/mnt/c. git is several times slower on a Windows drive, and an edit there sends no file event, so dev servers never reload. - Install your tools inside WSL too, Node and Docker among them. For Docker, turn on Docker Desktop's WSL integration.
pando doctorsays when the shell finds Windows' copy of a tool instead, or when the repository sits on a Windows drive. - URLs work from Windows. A worktree's
localhostURL opens in Windows' browser, andpando openopens it there (throughwslview, thenrundll32.exe, thenxdg-open). The TUI copies throughclip.exe.
A native Windows build compiles, but it runs nothing yet except completions: starting and stopping processes is written for Unix only so far. It says to use WSL 2.
Expo and mobile apps
pando recognises Expo apps. Metro, Expo's bundler, is a process no browser opens (page = false), so it is never a worktree's URL.
Instead, pando open and the TUI's o open the app: on the booted iOS simulator, else on a connected Android device or emulator, else on a simulator pando starts, on a Mac with Xcode. With none of those, it prints the commands.
pando status gives each app's links. When a branch changed native code, it names the changes and gives the build command Expo accepts, such as npx expo run:ios --port <port>. It also says when the build on the simulator is for another SDK.
Worktrees
pando does not invent a new kind of checkout. It drives git worktree, the side-by-side checkouts git has had since version 2.5, and keeps everything around them in its own home, ~/.pando: the ports, the processes, the logs, the private services, and the record of what runs where.
A worktree is an ordinary directory on a branch of its own: cd into it, open it in your editor, commit from it. Every worktree shares the repository's one .git, so a commit made in one is visible from all of them at once.
~/code/acme-shop/ ← the main checkout │ .git/ one object store, one history │ ~/.pando/projects/acme-shop-2bdf70d7/ └─ worktrees/ ├─ feat+checkout/ ● :23001 branch feat/checkout ├─ fix+login-loop/ ● :22553 branch fix/login-loop └─ feat+search/ ○ stopped branch feat/search
Names
A worktree is named by its branch, feat/login, or by its directory, feat+login. A slash cannot be in a directory name, so it becomes a plus. Every command takes either spelling.
Inside a worktree, start, stop, restart, logs, open, share and unshare need no name at all: they act on the worktree you are in.
What pando new does
- Finds the branch. A local branch is checked out as it is. Otherwise pando looks for it on
origin, and fetches it if it is missing, never prompting for a password. Otherwise it makes a new branch, forked from the base (see below). - Checks it out. It runs
git worktree addinto~/.pando/. The project id is the checkout's directory name and eight hex characters of a hash of its path. Where the disk can clone, the files are copy-on-write clones of your main checkout's, and git writes only what the branch changed: see Light on disk.projects/ <id>/ worktrees/ feat+login - Provisions. The gitignored files you listed in
provision, such as.env, are linked in from the main checkout. They are symlinks by default, so editing one edits main's.provision_mode = "copy"gives each worktree its own copy. A path the project does not gitignore is refused. - Installs. The project's install step, such as
pnpm install --frozen-lockfile, runs in the new worktree, so its dependencies are its own. The paths inclone, such asnode_modules, are cloned in first, so the install only fixes what differs.
A new branch forks from the first of these that applies:
--base- a matching glob in
[branches] rules [project] baseorigin/HEAD, thenmain, thenmaster
It forks from the last-fetched commit, so run git fetch first when you need the newest.
A worktree made before provision was answered, or one that lost a file since, gets the file at its next start, never over one that is there.
$ pando new feat/checkout pando: checking out feat/checkout pando: provisioning pando: installing created feat+checkout at ~/.pando/projects/mono-web-api-3cb31588/worktrees/feat+checkout $ pando start feat/checkout pando: using postgres as this project's services (detected: docker-compose.yml, postgres:16 → DATABASE_URL) pando: starting api pando: starting web started feat+checkout — http://localhost:22809 $ pando ls NAME STATUS URL PORTS GIT main stopped - - clean main checkout fix/login-loop stopped - - clean feat/checkout running http://localhost:22809 api:22808 web:22809 clean
The fixture is scripts/, with two stand-in dev processes. The services line is detection at work: pando read the compose file and the env example, and chose. pando doctor says what it found and where.
When something fails
If anything fails after the checkout, new undoes it. The worktree is removed, and so is the branch if this new created it. A new stopped by Ctrl-C during the checkout cleans up the same way.
A failed install is the exception: it keeps the worktree, and the next start tries the install again. Removing a worktree with rm always keeps its branch.
The main checkout
The main checkout runs too. It is always the first row, marked ⌂, and goes by its directory's name, or by its branch when no other worktree is on it: in a checkout of main, pando start main starts it, and so does pando start with no name from inside it.
The checkout is yours and you set it up, so pando runs its processes on ports it allocates and nothing else: no install, no hooks, and always on the project's own services. rm never removes it.
pando stop with no name, run from the main checkout or from outside any worktree, stops every worktree and the main checkout, not only the one you are in. Name it to stop only the main checkout, by its branch or its directory's name, such as pando stop main.
Worktrees you made yourself
pando manages every worktree git worktree list reports, so the ones you made by hand are listed, started and stopped too. They are marked adopted.
pando never writes into an adopted worktree, so the files provision names are not given to it. start and doctor say which it lacks, each with the command that supplies it.
Several repositories
A product split across repositories cloned side by side is one project. Run pando in the plain folder that holds them:
product/ a plain folder, not a repository ├── backend/ a git repository └── frontend/ a git repository
Its worktree is a set, laid out like the folder. pando new feat/x makes <set>/backend and <set>/frontend, each a worktree of its own repository on feat/x. A repository that already has the branch, locally or on origin, uses it. One that does not forks a new branch from its own base.
One branch, one row, one port window
start runs every process of the set in one port window, so a process with cwd = "frontend" reaches the backend's port through {port:api}. Stopping, removing, status, opening, sharing and checking act on the whole set too.
The TUI shows a set as one row, with each repository's branch and changes in its detail. pando status lists each repository of a set, and pando logs --source backend reads the processes that run in it.
Choosing the repositories and their bases
Every repository directly under the folder is in the project. In the project's pando.toml, [repos] members narrows that, and [repos.base] gives one repository a base other than its own default. A [branches] rule that matches the branch still comes first.
[repos]
members = ["backend", "frontend"]
base = { backend = "develop" }A path in config names its repository first: provision = ["backend/.env"].
Setup, and finding the project
pando init --agent, run from the folder, hands the setup to your coding agent as it does for one repository. Detection reads each repository as an app: its process, its install, its .env, a compose file at its root, and the port one app reaches another on.
A set that lacks a repository's checkout, lost or added since, gets it back from pando new on its branch. From inside a set, or one of its checkouts, pando finds the folder's project. From a repository's own main checkout, the project is that one repository, as before.
The git menu moves one checkout at a time. On a set it opens on the first repository's checkout, measured against that repository's base, and tab goes to the next.
Running
Detached, with no daemon
Every process runs as bash -lc '<cmd>' in a session of its own, which gives it its own process group and no terminal. Its input is /dev/null, and its output is appended to logs/ in pando's home. Close the terminal or quit the TUI, and it keeps running.
There is no pando daemon. What runs where is kept in state.json. Whenever something reads it, such as ls, status, the TUI or a start that waits, pando brings it up to date by scanning each process group: with ps and lsof on macOS, and /proc and ss on Linux.
Several processes
A worktree can run several processes, such as [processes.api] and [processes.web]. Each has its own command, directory, environment, ports, readiness and log.
--only web starts, stops or restarts one of them, and the others keep running on the ports they have.
Ready means listening
On a terminal, start waits until each process's own process group is listening on its port. The default limit is 30 seconds, and ready.timeout_s changes it. A process with no port has nothing to check, so it must stay up instead: five seconds, or its own ready.timeout_s up to ten.
This is a socket check, not an HTTP health check, and pando never binds the port itself to test it. When a process does not come up, you get the last lines of its log and the reason:
$ pando start feat/login pando: starting api pando: starting web pando: waiting for api, web to be ready pando: api is ready (1.9s) pando: the last lines of the web log: Error: Cannot find module 'next' pando: web failed: process exited with status 1 — `pando logs feat/login --source web` has the rest $ echo $? 1
From a script or an agent, start and restart return as soon as everything is spawned. --wait makes them wait there too, and --no-wait makes them return at once on a terminal.
Stopping
stop sends SIGTERM to the whole process group, meaning the server and everything it forked. It waits up to five seconds, then sends SIGKILL. A backgrounded server whose parent already died is found and stopped too.
A stop also takes down the worktree's private services and public URL. Its ports, logs and data are kept.
What survives a closed terminal, or a reboot
Closing the terminal, killing the tmux pane or quitting the TUI leaves everything running: each process has its own session and no terminal.
A reboot stops them, as it stops anything. pando notices the new boot and forgets the old process ids, but it keeps each worktree's ports and mode, so the next start comes back on the same URLs. Nothing restarts by itself: there is no daemon and no supervisor.
Ports
Ports are chosen at start, and never at random. pando hashes the project id and the worktree's name into one of 1,971 windows of eight ports between 17000 and 32767. That range sits below the ephemeral ports that macOS (49152 and up) and Linux (32768 and up) hand out.
Each role takes the next port in its window. A role is a name like web, api or a private postgres. Processes come first, then services, so switching a worktree to isolated keeps its web port whenever the ports after it are free.
The ports are recorded, so a bookmarked URL keeps working across stops, restarts and reboots. They move when something else took one, and pando says so: the ports feat/login had were taken; it moved to new ones. Adding or removing a process, or switching to or from isolated, fits them again, usually on the same numbers.
Work one out
This runs the same hash pando uses, in your browser. Change the repository path, the branch or the roles:
id = the directory name and the first 8 hex of md5(the checkout's path) · base = md5(id ␟ worktree)[0..4] mod 1971 × 8 + 17000
Environment
pando never edits a .env, a framework config or a package.json to set a port. Ports and service addresses reach your app as environment variables, or as placeholders in its command. One process can learn another's port the same way.
Placeholders
These work in a process's command and in its environment values. An unknown placeholder is a config error, never an empty string.
| Placeholder | Becomes |
|---|---|
{port} | this process's own port |
{port:api} | the port of the role api, whichever process or service owns it |
{name} | the worktree's name, such as feat+login |
{branch} | its branch, such as feat/login |
{worktree} | its absolute path |
{root} | the main checkout's path |
{project} | the project id |
{log} | the log file, inside a process or hook command |
Variables every process gets
Every process gets PANDO_NAME, PANDO_BRANCH, PANDO_WORKTREE, PANDO_ROOT and PANDO_PROJECT. What pando check runs also gets PANDO_CHECK=1, and a namespaced worktree's processes get PANDO_NAMESPACE:
| Variable | What it holds |
|---|---|
PANDO_NAME | the worktree's name |
PANDO_BRANCH | its branch |
PANDO_WORKTREE | its path |
PANDO_ROOT | the main checkout's path |
PANDO_PROJECT | the project id |
PANDO_CHECK=1 | only in what pando check runs, so a process that reaches outside its worktree can leave that out of a test |
PANDO_NAMESPACE | only in a namespaced worktree: a name of its own, the branch's slug and a short hash such as feat_x_1f3c4a, for an app that puts one in front of what it names by itself |
The same environment in your shell
To run the project's own commands by hand with a worktree's ports and addresses, load its environment into your shell:
eval "$(pando status --env feat/login)"An example
Here the web app gets the API's address, whatever port the API was given, and a migration runs only when the worktree has data of its own:
[project] provision = [".env"] # gitignored; linked in install = "pnpm install --frozen-lockfile" [processes.api] cmd = "pnpm --filter api dev" cwd = "apps/api" ports = { PORT = "api" } [processes.web] cmd = "pnpm --filter web dev --port {port:web}" cwd = "apps/web" ports = ["web"] env = { VITE_API_URL = "http://localhost:{port:api}" } ready = { timeout_s = 90 } [[hooks]] name = "migrate" after = "services" on = "isolated" # only on data of its own cmd = "pnpm prisma migrate deploy" fingerprint = ["prisma/migrations/**"]
ports = { PORT = "api" } hands the process its port in the variable PORT. ports = ["web"] only claims the role, for a command that takes it as a flag.
Light on disk
You keep many worktrees, so what one costs is paid many times over. pando keeps that cost down, and measures what is left.
A copy-on-write checkout
Where the filesystem can clone (APFS on macOS; btrfs, XFS or bcachefs on Linux), pando new clones your main checkout's files into the new worktree. The clones share disk blocks until one of them changes, and git writes only the files that differ on the branch.
Say your checkout is 300 MB across 4,000 files, and your branch changes 40 of them. A plain git worktree add writes all 300 MB again. pando writes those 40 files, about 3 MB, and clones the rest.
The result is the tree git's own checkout makes: the same files, modes and git state, made by git's own reset --hard. A file whose checkout converts it (CRLF endings, a filter, ident) is always written by git, and a post-checkout hook runs as usual.
A filesystem that cannot clone, such as ext4, keeps git's own checkout, and so do core.autocrlf, core.eol=crlf, a repository-wide attributes file, a sparse main checkout, and a git too old to read attributes from a commit. copy_on_write = false turns it off.
du still counts each worktree in full. The saving shows up as free space.
Dependencies, cloned
[project] clone lists gitignored paths, such as node_modules, that new clones from the main checkout before the install, so the install only fixes what differs. It is never a full copy: on a disk that cannot clone, they are left to the install.
pando proposes it for the node_modules your main checkout has, the root's and each app's, unless the install deletes them first, as npm ci does. clone = [] records that you want every worktree installed from nothing.
Never cloned, each with a line saying so: a path the install deletes first, a Python virtualenv (its scripts name main's interpreter by path), and a tree with a link out of the worktree. pando check never clones, so a check still proves the install works from nothing.
Rust builds, cloned
clone also takes a Rust crate's target, and pando proposes it beside a Cargo.toml. A new worktree then starts with the main checkout's build. Cargo's fingerprints for dependencies name no path of the checkout, so cargo finds every dependency fresh and builds only the workspace's own crates. A Maven or sbt target is left alone.
What a worktree costs: the check's report
Before it removes its worktree, a passing pando check measures what that worktree cost on disk:
- Each gitignored tree the install and the processes left, a megabyte or more, twelve at most, marked when your main checkout has one
clonecould share. - What was written outside it, such as a build cache keyed by the checkout's path, which fills again for every worktree.
pando: a worktree holds node_modules 480 MB (the main checkout has one: `clone` could share it) — how to judge it: "What a worktree costs on disk" in `pando init --agent --reference brief`pando check --json carries the same numbers as disk:
"disk": { "trees": [ { "path": "node_modules", "bytes": 480000000, "main_has": true, "cloned": false } ], "outside_bytes": 12000000 // null where it was not read }
The outside figure is approximate: anything else that wrote meanwhile counts too, so check twice before acting on a surprise.
pando measures; your project decides
pando knows no ecosystem here. Which trees are safe to share, and which setting makes a cache independent of the checkout's path, is your project's call.
A tree is worth cloning when the tool that wrote it checks what it reuses, as a package manager or cargo does, and not when its files record the main checkout's path. A path-keyed cache usually has a setting of its own, given to the process through its env. Such a setting can change how a program behaves, so weigh it first.
The brief's "What a worktree costs on disk" walks your agent through both, and the setup report says what was shared. Check again after a change, and compare.
Sharing
Its local URL
Each worktree has one local URL, http://localhost:<port>, for its web role, or else for the first role that owns a port and serves a page. pando open opens it in your browser and prints it too, so it works over SSH. o opens it from the TUI, and c copies it.
A public URL
pando share feat/login publishes a running worktree through a cloudflared quick tunnel. It needs no account, and it prints one line: https://<random>.trycloudflare.com. In the TUI, t shares and asks first.
Every share gets a new random host. The link closes on unshare, stop, rm, and a restart of the whole worktree. restart --only keeps it.
Public means public. Anyone with the link reaches the app until you unshare, stop, restart or remove the worktree. The link does not expire.
Apps that need a login
If your app needs a login, [share] auth_cmd runs a command in the worktree, and its output becomes a Cookie header. A small proxy, bound to 127.0.0.1, puts that header on every visitor's request in place of any cookies their browser sent.
The link then opens already logged in, as the same user for everyone. That logs visitors in. It does not keep anyone out.
Pull requests
In the TUI, p lists the repository's open pull requests through the GitHub CLI. Typing narrows them by number, title, branch or author. ⏎ makes a worktree for one, or goes to the worktree it already has.
╭ open pull requests ────────────────────────────╮ │ filter ▏ │ │ │ │ ▸ #131 fix VAT rounding @sam │ │ #128 cart drawer @alex │ │ #124 search filters has a worktree │ │ │ │ ⏎ worktree ↑↓ choose esc cancel │ ╰────────────────────────────────────────────────╯
From a fork
A pull request from a fork has no branch on origin, so pando fetches refs/pull/<n>/head into a branch of its own, pr-<n>/<branch>. A pull request from the same repository whose branch is gone from origin is refused, rather than started as an empty branch with the same name.
On the list
A worktree with an open pull request shows it as ◍ #n: ◌ for a draft, ✓ once merged, ✗ once closed. space p opens that pull request on GitHub.
pando asks GitHub again about once a minute, and when you come back to the pane, so a merge shows without a restart. The header names the account gh uses here.
Pull requests are in the TUI only for now, and need gh signed in.
The git menu
space g on a row reads where its branch stands and offers what can be done to it, with why not where it cannot. Each move shows the exact git commands first. ⏎ runs them, and esc always goes back one step.
A rebase or merge that stops on a conflict is aborted again before it is reported, so the checkout is exactly as it was. When the branch of a checkout that runs has moved, the menu offers to restart it.
The menu never pushes, resets, stashes or switches branches. On a checkout with uncommitted changes it only fetches; pull, rebase and merge wait until it is clean. On the main checkout it only fast-forwards. It moves a branch only when you pick the move and have seen its commands.
Three modes
In every mode, a worktree's code, processes, dependencies, ports and logs are its own. The mode decides one thing: which database and cache it talks to. You choose per worktree, and pando remembers: a plain start keeps the mode a worktree last ran in.
Shared Default
S · --shared
The main checkout's servers, and its data. Nothing starts and nothing waits, which is right for most changes.
Own: code, processes, ports, logs.
Main's: the database, the cache and their data.
Namespaced Experimental
⏎ then choose · --namespaced
A database, a Redis slot or a name prefix of its own, inside the servers your main checkout already runs. The branch's own schema step builds it, and main's data is never touched.
Own: all of the above, plus a database, a slot or a prefix.
Main's: the servers themselves.
Isolated
i · --isolated
Servers of its own, on ports of its own. They are the containers in your compose file, or native servers from a recipe if you would rather not run Docker.
Own: all of the above, plus every server and every byte of data.
Main's: nothing.
Choosing and switching
⏎ in the TUI opens the mode chooser on any worktree; the main checkout has one mode, so there it starts at once, shared. On a stopped worktree, the mode it last ran in sits under the cursor, marked last used, so ⏎ ⏎ is still one quick start. A worktree never started has shared there.
On a running worktree, its mode is marked running, and choosing another switches it: every process restarts on the other services. i and S go straight to isolated and shared. The main checkout always runs shared. From the command line, start and restart take --isolated or --namespaced, and start --shared is the way back.
How the app finds its database
Through its environment, never by writing a file. For each variable the config maps to a service, such as DATABASE_URL = "postgres", pando reads the value your env files already have and changes only what the mode needs.
.env DATABASE_URL=postgres://acme:secret@localhost:5432/acme feat/login DATABASE_URL=postgres://acme:secret@localhost:30010/acme .env REDIS_URL=redis://localhost:6379 feat/login REDIS_URL=redis://localhost:30011
main DATABASE_URL=mysql://app:pw@localhost:3306/shop feat/login DATABASE_URL=mysql://app:pw@localhost:3306/shop__feat_login main REDIS_URL=redis://localhost:6379 feat/login REDIS_URL=redis://localhost:6379/3
In shared mode, the worktree's processes get the main checkout's own values for the database and cache variables, read from its .env or env example.
Isolated
With your compose file
An isolated start runs your compose file under a compose project named for the worktree, so the containers, the network and the named volumes are separate for every worktree. A generated override, kept under ~/.pando, publishes each service on a port pando chose, bound to 127.0.0.1. Your compose file is never edited.
$ docker compose -p pando-shop-0b790793-feat-login-0499 \ -f docker-compose.yml \ -f ~/.pando/projects/shop-0b790793/compose/feat+login.override.yml \ up -d postgres redis
services: postgres: ports: !override ["127.0.0.1:30010:5432"] container_name: !reset redis: ports: !override ["127.0.0.1:30011:6379"] container_name: !reset
pando refuses to isolate a service, and names it, when its data could land in the repository or be shared between worktrees:
- a bind mount;
- an
external:or name-pinned volume, or one withdriver_opts; - a
depends_onoutsideinclude; - a service with no port pando can find.
Without Docker
A native service is a recipe: a TOML file that says which binaries it needs, how to start one server on a given port and data directory, and how to tell when it is ready. Four are built in: postgres, mariadb, redis, and mongodb, which is marked untested.
Each server gets ~/.pando/, is initialised once, and binds 127.0.0.1 only. The built-in servers have no passwords, since nothing off your machine can reach them. pando never installs an engine. If one is missing, it prints the install command.
kind = "service" name = "redis" binaries = ["redis-server", "redis-cli"] install = "brew install redis (or your distribution's redis-server package)" notes = "no password, bound to 127.0.0.1 — nothing off this machine can reach it" [service] port_env = "REDIS_URL" cmd = "exec redis-server --port {port} --bind 127.0.0.1 --dir {datadir} --daemonize no" ready = "redis-cli -h 127.0.0.1 -p {port} ping" # what namespaced mode means on redis [namespace] kind = "slot" slots = 16
Your own recipes
A file with the same name in ~/.pando/recipes/ replaces a built-in outright, for every project on the machine. A new file adds an engine. Which mechanism a machine prefers, compose or native, is [isolation] prefer in ~/.pando/config.toml.
Native Postgres and MariaDB put their socket in $TMPDIR/pando-…, because a socket path longer than 104 bytes does not work on macOS.
Namespaced
Namespaced mode is experimental. A namespaced start writes into a server that belongs to you, which pando's rule about your repository does not cover. So the mode is opt-in, and it has rules of its own.
The login
It logs in the way your app does, with the user and password beside the address in the main checkout's .env: the root's, or the one where a process runs, such as backend/.env.
Where there are none, a server in a container is reached as its own administrator. Anywhere else, pando asks once, keeps the answer in its own config for the project (mode 0600), and hands it to the database client in its environment, never on a command line.
The grant
That login must be allowed to make databases named after the main one. The first start that is not allowed stops with nothing made, and prints the statement to run once as an administrator. On MariaDB and MySQL it covers those names and nothing else:
mariadb on localhost:3306 does not let the login from the URL in DATABASE_URL make or drop shop__feat_login — run this once as an administrator of that server: GRANT ALL ON `shop\_\_%`.* TO 'app'@'localhost'; It lets that login make and drop databases named shop__… and nothing else. Nothing was made.
Postgres cannot grant by name, so there it is ALTER ROLE "app" CREATEDB;, and the role can drop only the databases it owns, which are the ones it made. The official image's POSTGRES_USER needs neither.
The database is made in main's encoding and locale. It starts empty and is built by the branch's own schema step, never copied from main's.
Servers in containers
A server in a container needs neither the grant nor a question. Its environment keeps its administrator, such as POSTGRES_USER or MARIADB_ROOT_PASSWORD, so pando runs the statement itself as that administrator, and the database is made as the app's login, which owns it. Where the app has no login at all, the administrator is the login.
A database in Docker usually leaves the host with no client. Then the commands run through docker exec in the one container that publishes the server's port on this machine's loopback, with the client its image ships and the password passed by name. A server elsewhere, or a native one on the same port, is never taken for it.
Redis slots
A Redis slot is given out only where the app reads a slot setting, such as REDIS_DB or the path of its URL, and only while the slot is empty: keys pando did not put there are someone else's. Slot 0 and main's own slots are never given out.
When all fifteen are held, the start asks which stopped worktree gives its slot up, and only a person may answer.
Prefixes for search, queue and cache engines
Some servers have no namespace pando could make: an Elasticsearch index, a Kafka topic or a Memcached key belongs to the app. There, a worktree is told a prefix of its own in the key its app already reads one from, such as ELASTICSEARCH_INDEX_PREFIX=, with main's own prefix first when it has one. pando makes nothing there, so it records and drops nothing, and rm says what it leaves.
What it drops, and what it never does
Every drop goes through one check. A record must say pando made that database for that worktree, on that server. The name must never be main's, must carry the __ marker, and must not be named by any other record. pando doctor lists a leftover with the command that drops it, and never drops it itself.
When pando cannot tell
What pando cannot tell by itself is written in its own config for the project, under [namespaced.<service>], usually by the setup agent through pando init --answers. None of these keys is a secret, so a committed pando.toml may carry them too. A login, user and password, is read from pando's own file only.
[namespaced.redis] db_env = ["REDIS_DB"] # one REDIS_DB that three Redis roles share [namespaced.search] recipe = "elasticsearch" # an image whose name says nothing prefix_env = ["SEARCH_INDEX_PREFIX"]
pando signals lists what a namespaced start would do with each service, and why one stays shared. pando init names the services it would leave on main's data.
What is supported
| Gets | Engines |
|---|---|
| a database of its own | Postgres, MariaDB and MySQL, in a native server or a container, Postgres images with an extension built in (pgvector, PostGIS, TimescaleDB) included |
| a slot of its own | Redis, Redis Stack and Valkey |
| a prefix, where the app reads one | Elasticsearch, OpenSearch, Kafka, Redpanda, Meilisearch, Typesense, Memcached and Redis |
| nothing: it stays shared | every other service, and the start says so for each, with the setting that would change it |
An engine pando does not ship
What a namespace is on an engine is data: a recipe's [namespace] or [prefix] table, so another engine is a file in ~/.pando/recipes/ rather than a release. A compose image finds it by its own name, or by [namespaced.<service>] recipe. It needs no [service] table when pando never starts the engine.
kind = "service" name = "clickhouse" [namespace] kind = "database" # made and dropped by name; "slot" is a number binaries = ["clickhouse-client"] password_env = "CLICKHOUSE_PASSWORD" ping = "clickhouse-client --host {host} --port {port} --user {user} -q 'SELECT 1'" exists = "clickhouse-client --host {host} --port {port} --user {user} -q \"SELECT name FROM system.databases WHERE name = '{namespace}'\"" create = "clickhouse-client --host {host} --port {port} --user {user} -q 'CREATE DATABASE {namespace}'" drop = "clickhouse-client --host {host} --port {port} --user {user} -q 'DROP DATABASE IF EXISTS {namespace}'" [namespace.address] # where the app names its database url_path = true keys = ["_DATABASE", "_DB"]
Each command keeps a contract: create fails when the name exists, a slot's commands never fall back to slot 0, size prints a bare number, and the password reaches the client only through password_env.
pando derives every name, <main>__<worktree>, and drops only what its records say it made. An engine whose namespaces are the app's own convention needs only a [prefix] table.
What happens to data
| Mode | stop | Switching mode | rm |
|---|---|---|---|
| shared | nothing: the data is main's | nothing | nothing |
| namespaced | kept | kept, for when it comes back | dropped, only if pando's records say pando made it |
| isolated | kept: containers and servers stopped | kept | removed: docker compose down -v, data directory deleted |
A prefix is never made, so nothing is dropped for it. With Docker not running, rm --force goes ahead and leaves the data volumes behind, printing the command that removes them. A removal stopped half way, by Ctrl-C or a crash, is finished by the next pando rm of that worktree.
Setup and detection
You do not write a config file to start. Before it asks anything, pando reads the main checkout. Nothing starts while it reads.
What pando reads
package.jsonscripts, and Makefile and justfile targets- lockfiles and workspace markers
- version files, such as
.nvmrc - the first env example
- framework markers
- compose files
- the gitignored files at the root
A root with no manifest of its own, such as backend/ beside frontend/, is read one directory down and in apps/* and packages/*. Each app's scripts, lockfile, version file and env files are read, and each app is installed and run in its own directory.
What the rules know is data, one row per fact:
| Package managers | pnpm, npm, yarn, bun, uv, poetry, pipenv, bundler, composer, mix, go and cargo: one row each with its lockfile, and a frozen install for the nine that need one |
| Frameworks | Next.js, Nuxt, Astro, Angular, Expo, Vite, Django, Rails, Phoenix and Laravel, plus plain Go, Rust and Node projects: 13 rules |
| Service images | 24 container images a compose file may use: databases, caches, search engines, queues, object stores and mail catchers |
| Languages | Node, Python, Ruby, Rust, Go and Java, and 11 version managers: volta, mise, asdf, nvm, fnm, pyenv, rbenv, rvm, rustup, jenv and sdkman |
The twelve questions
From what it read, pando proposes answers to twelve questions, always in this order, each with the evidence behind it:
| Question | What it decides |
|---|---|
install | the install command, frozen against the lockfile |
version_files | the files that name the runtime's version |
prelude | the shell line that makes this machine find that runtime; kept in the machine's config, since it is about the laptop |
processes | one process, or one per app of a workspace |
dev_cmd | the command that starts the dev server |
port_env | which variables carry the ports |
services | which compose services a worktree runs private copies of; the one question whose answer is a set |
schema_hook | the command that brings a fresh database to the current schema, and the files whose change means it runs again |
provision | the gitignored files each worktree gets, such as .env |
clone | the dependency trees cloned in before the install |
base | the branch new forks from and check tests; open only when origin/HEAD is far behind the main checkout's branch |
namespaced | how each service gets data of its own in a namespaced start, where pando could not tell; answered by a program, never asked of a person |
A namespaced start can ask two more of its own: a login, and which worktree gives up its Redis slot.
Taking the first choice
On a terminal, new, start and the TUI take the rules' first choice for anything they have one for, and print what they took, with the file they wrote it to:
pando: process list: using "npm run dev" (package.json scripts.dev, which starts the workspace's apps itself; API_PORT and WEB_PORT in the env example), pando's first choice, over 1 other option — change it in ~/.pando/projects/<id>/pando.tomlA question pando has no option for at all is still asked. So is the one real choice isolation brings: which services get private copies. From a script or an agent with no --yes, such a question exits with code 3 (see For agents).
Answering in one pass
pando init puts every open question to you in one pass, instead of taking defaults as you go. A second run asks nothing. pando init --yes takes pando's own recommendation for each.
A program answers through pando init --answers -: one JSON object on stdin, keyed by the question's name. --dry-run prints the file it would write and writes nothing, and --replace changes an answer that is already there:
echo '{"clone": ["node_modules"]}' | pando init --answers - --replacepando doctor says what was detected, from where, and what is missing. pando signals prints the evidence as JSON.
pando.toml
The answers go to ~/.pando/, with file mode 0600, never into your repository. You never have to write one. pando writes it, and each line it writes carries its reason.
# pando.toml — pando's own config for this project. # Lines marked "# detected:" or "# answered:" were written by pando. # Everything here is yours to edit; pando only ever adds keys it is missing. [project] install = "pnpm install --frozen-lockfile" # detected: pnpm-lock.yaml provision = [".env"] # detected: gitignored and present in the main checkout [runtime] version_files = [".nvmrc"] # detected: .nvmrc [dev] cmd = "pnpm dev" # detected: package.json scripts.dev ports = { PORT = "web" } # detected: the Next.js convention [[services]] # detected: docker-compose.yml, postgres:16 → DATABASE_URL kind = "compose" file = "docker-compose.yml" include = ["postgres", "redis"] env = { DATABASE_URL = "postgres", REDIS_URL = "redis" }
The file is yours to edit. pando adds keys that are missing, and changes an answer only when asked to, with init --answers - --replace. Delete a line and run pando init, and that question is put to you again.
Layers
Config comes in layers, highest first: pando's own project file, then the machine-wide ~/.pando/config.toml. For now, a pando.toml committed in the repository is read beneath them and never written. Whether to honour one is still an open decision.
Section by section
~/.pando/config.toml.dev: its command, directory, ports, environment and readiness.[dev].on = "isolated" runs one only on data of its own, and fingerprint runs it again only when those files change.auth_cmd for apps that need a login.The full shape
[project] base = "main" # what new branches fork from provision = [".env", ".env.local"] # gitignored files each worktree gets provision_mode = "copy" # default: a symlink to main's provision_from = { ".env" = ".env.example" } # a seed where main has none install = "pnpm install --frozen-lockfile" clone = ["node_modules"] # cloned in before the install copy_on_write = false # default: clone where the disk can # worktrees_dir = "…" # default: ~/.pando/projects/<id>/worktrees [runtime] version_files = [".nvmrc"] # prelude: the machine's, kept in ~/.pando/config.toml [dev] # one process; [processes.<name>] for several cmd = "pnpm dev" cwd = "." ports = { PORT = "web" } env = { NODE_ENV = "development" } ready = { role = "web", timeout_s = 30 } page = true # false: never the URL (Expo's Metro) [[services]] kind = "compose" file = "docker-compose.yml" include = ["redis"] env = { REDIS_URL = "redis" } ready_timeout_s = 60 # seconds each service gets; 60 by default [[services]] kind = "native" name = "postgres" preset = "postgres" # a recipe; the lines below override it port_env = "DATABASE_URL" init = "initdb --pgdata {datadir}" cmd = "exec postgres -D {datadir} -p {port} -k {socket_dir}" ready = "pg_isready -h 127.0.0.1 -p {port}" [isolation] # none = true # this project runs no private services [[hooks]] name = "migrate" after = "services" # create · install · services · dev on = "isolated" # or always · never fingerprint = ["prisma/migrations/**"] # runs again only when these change cmd = "pnpm prisma migrate deploy" cwd = "apps/api" # a directory inside the worktree fallback = "pnpm prisma db push" # runs only when cmd fails [[probes]] # checked right before processes spawn name = "native-abi" cmd = "node -e 'require(\"better-sqlite3\")'" match = "NODE_MODULE_VERSION" hint = "Rebuild native modules under the dev runtime." [branches] rules = [{ match = "*-beta", base = "beta" }] [repos] # a folder of repositories only members = ["backend", "frontend"] base = { backend = "develop" } [share] provider = "cloudflared" auth_cmd = "./scripts/dev-cookie.sh" # its stdout becomes the visitor's Cookie [namespaced.search] # data of its own, in a namespaced start recipe = "elasticsearch" # when the image does not say what it is prefix_env = ["SEARCH_INDEX_PREFIX"] # keys the app reads a prefix from [namespaced.cache] db_env = ["REDIS_DB"] # keys naming a database or slot pando missed [namespaced.db] # its login; read from this file only user = "app" password = "…"
pando check
pando check proves a setup in a throwaway worktree. It makes a detached worktree of the commit a new branch would fork from, so there is no branch. It installs it, starts every process, waits until they are ready, and asks the process that owns the URL for /.
Then it stops and removes the worktree, keeps its logs, and records the result in check.json. In the TUI, v runs it.
$ pando check pando: testing acme-shop's setup at a1b2c3d (origin/main), in a throwaway worktree (no branch) pando: installing pando: starting api, web pando: waiting for api, web to be ready pando: asking web for its first page on :29849 pando: installed 14.2s · api ready :29848 · web ready :29849 (HTTP 200) pando: a worktree holds node_modules 480 MB (the main checkout has one: `clone` could share it) — how to judge it: … pando: removed the test worktree; nothing left behind ✓ acme-shop is ready: `pando` opens it
What passes
A status of 500 or higher, a refused connection or silence is a failure. Any other answer passes: a login redirect is a working app.
The exit code is 0 when it passed, 1 when it failed, and 3 when a question is still open. --json prints the result as one object, and its kind says whose a failure is: the settings', this machine's, or the base commit's.
What it never touches
The check runs on the shared services and skips the hooks that run after the services or after dev, so it never migrates your own data. Everything it runs gets PANDO_CHECK=1.
When the project has a schema step to prove, and a namespaced login already exists or a container's administrator gives one, the check proves that step in a namespace of its own, and drops it with the worktree.
A passing check also measures what the worktree cost on disk before it removes it: see the check's report. --base <branch> tests the commit that branch is at, for this run only.
For agents
An agent reads pando the way a script does. stdout carries only the answer. stderr carries the narration, each message starting with pando: .
ls, status, logs, check and doctor print JSON with --json, and signals always prints JSON. The shapes are versioned and documented in agent/json.md.
Exit codes
| Exit | Means |
|---|---|
| 0 | ok |
| 1 | an error |
| 2 | a usage mistake |
| 3 | pando has a question, printed on stderr. It is not a failure. An agent answers it from the project's own evidence, or puts it to the developer, and never adds --yes to make it go away. |
$ pando status feat/login --json # trimmed { "version": 2, "project": { "id": "acme-shop-2bdf70d7", … }, "worktrees": [{ "name": "feat+login", "main": false, "branch": "feat/login", "ports": { "api": 26624, "web": 26625 }, "url": "http://localhost:26625", "mode": "shared", "share": null, "processes": { "api": { "pid": 51377, "phase": "running", … }, "web": { "pid": 51378, "phase": "running", … } } }] } $ pando start feat/search # no terminal, no --yes pando: Which command starts the local development server? 1) pnpm dev (package.json scripts.dev) 2) pnpm dev:web (package.json scripts.dev:web) $ echo $? 3
The brief, the plugin and the skills
How an agent turns pando's evidence into answers is written once, in agent/brief.md: decide what the rules leave open without asking, write only through pando init --answers, and end by reporting what was set. The binary carries it too: pando init --agent --reference brief, or json for the shapes.
The repository includes a Claude Code plugin and Codex skills, thin wrappers around that brief. An agent that reads the brief needs neither.
# Claude Code $ claude plugin marketplace add mertkaradayi/pando $ claude plugin install pando@pando # Codex, from a clone of pando's repository; again after each upgrade $ agent/codex/install.sh
Remembering the project
pando init --agent --reference memory prints a short block on how to run this project's worktrees with pando. The setup agent offers to save it in its own memory, and does so only when you say yes, so later sessions start and stop worktrees through pando rather than by hand.
pando also keeps the block as CLAUDE.md and AGENTS.md in the project's directory under ~/.pando, above every worktree, never in your repository.
Commands
A worktree is named by its branch (feat/login) or its directory (feat+login), and inside a worktree most commands need no name (see Names). stdout carries only the answer, and the narration goes to stderr.
Several at once
start, stop, restart and rm take several names, as in pando rm feat/a feat/b fix/c. They act on them side by side and say each one as it finishes. One that fails leaves the others to finish, and the exit code is then 1.
A start of several settles every question first, one name after another, and then starts them all. If a question is still open, the whole command exits 3 and nothing is started. Every flag applies to each name.
Every verb
--base <ref> fork from here · --yes take pando's first choice for any question--shared · --isolated · --namespaced (experimental) · --only <process> · --wait / --no-wait · --yes--only <process> · --all every worktree and the main checkout, from anywhere--isolated · --namespaced (experimental) · --only <process> · --wait / --no-wait · --yes-l adds each commit and path · --json--json · --env <name> prints export lines for evaldev's, the only process's, or all of them merged. -s, --source <name> a process, service or hook · -n, --tail N (50) · -f, --follow · --json one object per line$BROWSER, or the desktop's opener), or open its app. --public the shared URL · --app its app, even beside a pagecd "$(pando path feat/login)" .--force even with uncommitted changes, or with Docker not running · --yes a worktree pando did not create--yes · --answers <file|-> · --dry-run · --replace · --agent the job for a coding agent · --reference brief|json|memory--base <branch> test the commit this branch is at, for this run only · --json--json · --adopt <old-id> after you moved the repository; asks first, --yes does not--check whether a newer release is out, and the command that would install itThe TUI
pando with no arguments is the TUI. Every action has a key, and almost everything it does is a command too; the pull request picker and the git menu are in the TUI only, for now. ? lists every key, mouse gesture and mark on screen.
Reading the list
The list is a table with a header row: branch, PR, dir, port, other ports, public and git. A column shows only when some row has something in it, and a narrow pane gives up the least useful first. dir names a directory that is not the branch's own name, or says main checkout, detached or mixed branches. The marks below sit in the branch cell: the glyph before the branch says whether the worktree runs, and the mode mark and a word such as failed follow it. The detail pane beside the list has the full URL and the rest.
| Mark | Means |
|---|---|
| ● | running: the dev server is up |
| ◌ | starting, or something is being done to it |
| ✗ | failed: l shows the log that says why |
| ○ | stopped: s starts it |
| + | marked: s x r d act on every marked row |
| ⌂ | the main checkout, always the first row |
| ▣ | isolated: private copies of the services |
| ◧ | namespaced: a database, a slot or a prefix of its own (experimental) |
| ◈ | public: shared on the internet |
| ◍ #n | its open pull request: ◌ draft, ✓ merged, ✗ closed |
| ↓n ↑n | commits behind and ahead of the base branch |
| ✎ | uncommitted changes |
| :22809 | where it serves: c copies the URL |
| removing | another pando is removing it, so s x r d leave it alone |
| rm interrupted | a removal stopped half way: d finishes it, and nothing starts it meanwhile |
| rebasing | a rebase or merge was left half-done in it: the git menu aborts it, or ! opens a shell to finish it |
| prunable | its directory is missing: git worktree prune removes the entry |
| 1 missing | a set lacks a repository's checkout: pando new <branch> adds it back |
The header shows the GitHub account gh uses here, the project's shared services and whether each answers, and, until a check passes, a line on the project's setup.
Keys
$VISUAL or $EDITOR.pando check.Confirmations
A key that would interrupt a running worktree asks for a second press within three seconds. x x stops it, r r restarts it, and P P restarts one process. i or S twice restarts it in the mode it already runs in. esc takes the first press back. On a worktree with nothing up, stopped or failed, the first press acts.
Sharing, removing and stopping everything always ask in a dialog, and so does moving a running worktree to another mode.
x on a worktree being started cancels the start: it stops at its next safe point, undoes what it brought up, and the worktree ends stopped. q q with a start in flight does the same, then quits.
Marks: several rows at once
+ marks the row under the cursor, or unmarks it, and moves down. esc unmarks every row. A mark stays on its worktree through a refresh, a re-sort or a filter.
While rows are marked, s, x, r and d act on all of them at once, and x x or r r asks once for the set. d opens one dialog that says what each removal takes with it, which only F removes (uncommitted changes), and which stay. Every other key acts on the row under the cursor.
The mouse
- Click a worktree, a dialog's option or a line of the log viewer to select it. Click it again for ⏎.
- Click a key hint, such as
esc cancel, to press its key. - Click a tab of the log viewer, or a process the log preview names, to show that log.
- The wheel scrolls whatever is under the pointer.
While pando has the mouse, hold shift to select text (option in iTerm2). [ui] mouse = false in ~/.pando/config.toml leaves the mouse to the terminal. The setup screen always does, so its prompt can be selected and pasted.
Sorting the list
The main checkout is always the first row, and the worktrees with something up come right after it: a start moves a row up, and a stop puts it back. , changes the order within each group: by pull request, highest first (the default), newest first, last run first, or by name. The choice is saved as [ui] sort.
How it keeps up
The screen keeps up by polling: processes every second, the worktree list and the selected row's git state every five seconds, the other rows' git state every thirty, and GitHub about once a minute. A watcher on the worktrees directory reads the list again as soon as a worktree appears or goes, and coming back to the pane reads the list, git and pull requests again. It fits a tmux split: below 72 columns, the table and the detail pane stack.
The log viewer
l opens a tab per log, led by an all tab that merges every process's log when there are several.
all first when there are several processes, then one per process, hook and service. tab and shift-tab go to the next and previous.With the mouse, a click puts the cursor on a line or shows a tab's source, a second click inspects the line, and the wheel moves the cursor three lines.
Levels are read from keywords in the line, so treat the filter as a guide: a crash line without the word error in it can be filtered out. When the viewer opens, the all tab shows each process's earlier lines one process after another, not interleaved by time. Lines that arrive after that follow in order.
From the command line, pando logs prints the same logs, and --json gives one object per line.
Machine config and themes
~/.pando/config.toml holds what belongs to the machine rather than to a project: the runtime prelude, which isolation to prefer, and how the TUI looks and behaves.
[runtime] prelude = "" # a line run before every command; "" for none [isolation] prefer = "native" # or "compose" [ui] theme = "catppuccin" # appearance = "dark" # "light", or "auto" to follow the system # sort = "run" # the list's order: "pr", "newest", "run" or "name" # mouse = false # leave the mouse to the terminal # theme_from = "~/.config/theme-switcher/current"
Themes
T in the TUI lists the colour themes, each with a swatch of its colours. Moving through them repaints the screen, ⏎ keeps one, and esc puts the old one back.
Fifteen are built in: pando's own, Catppuccin, Flexoki, four GitHub themes (default, dimmed, high contrast and colorblind), Gruvbox, Kanagawa, Monokai Pro, One Dark, Rosé Pine, Tokyo Night, VS Code and Zenwritten. Each has a dark and a light half that follows the system.
theme_from names a file whose first line is a theme's name, such as the state file a terminal theme switcher keeps. pando follows it while it runs, so switching the terminal's theme switches pando's with it. PANDO_THEME and PANDO_APPEARANCE override both for one run.
A theme is a small TOML file: for each half, a background, a foreground and seven accents, and optional keys such as surface or border for a colour you would rather set than derive. Every colour left out is derived from the others. A file in ~/.pando/themes/<name>.toml is listed beside the built-ins, and replaces the built-in of the same name.
pando's home
Everything pando keeps lives under ~/.pando. Set PANDO_HOME to move it elsewhere.
The two promises
These two rules come before every feature.
pando never writes into your repository
Not a config file, not a gitignore line, not a lockfile change. Apart from a socket directory in $TMPDIR for native Postgres and MariaDB, pando's own files go to two places:
- its own home,
~/.pando/; - the worktrees it creates, which live under that home by default.
Inside .git, only git itself writes: its records of the worktrees, branches and fetches pando asks for. pando writes no file in your checkout; only the git menu, when you pick a move, has git move a branch.
Inside a worktree, pando may create or link a file only if the project's own gitignore already ignores that path. .env and .env.local pass. Anything that would show up as untracked in git status is refused.
~/.pando/ ├── config.toml the machine’s: prelude, isolation, the screen ├── recipes/ themes/ your native services and engines, colour themes └── projects/acme-shop-2bdf70d7/ ├── pando.toml one project’s config ├── state.json what runs where, on which ports ├── worktrees/feat+login/ the branch's own checkout ├── logs/feat+login/ every process's log ├── data/feat+login/ its private services' data └── compose/ generated compose overrides ~/code/acme-shop/ untouched
How it is kept
- Every path is computed. Every location pando writes is a function of its home and a project id, and a test checks that none of them is inside the repository. A home or a
worktrees_dirinside the checkout is refused before anything is made. git check-ignoreruns before every write into a worktree. It runs in the main checkout first, then again inside the new worktree right before each file is written, because a branch can carry an older gitignore. A refusal found after the worktree was made undoes it.- Hooks and installs are watched.
git statusis taken before and after them, and pando warns about anything new that appeared. - Every command is checked by a test. After each one, the test suite checks that
git statushas nothing to report, and that every path in the repository outside.githas the same type, size and symlink target as before.
What it does and does not cover
Git itself records worktree admin files in .git/worktrees, and new branches and fetched refs in .git. A worktree gets the gitignored files you listed linked into it, and its own dependencies installed, such as node_modules. The worktree itself lives under ~/.pando. Nothing pando writes shows up in your checkout's git status.
Three things fall outside the rule as written, by design, and each has rules of its own:
- Namespaced mode, when you choose it, makes databases in your own server. Each is named after your main database, so it can never be it, and only
rmdrops it, only when pando's records say pando made it. See Namespaced. - The git menu moves a branch in a checkout, but only the move you picked, after you saw its commands. See The git menu.
- The copy-on-write checkout clones the branch's own tracked files into a new worktree, as
git worktree addwould write them, and git's own reset decides what each one holds. See Light on disk.
No AI at runtime
Discovery may be fuzzy. Starting processes may not. Detection is the only thing that writes pando.toml, whether init runs it, or new, start and the TUI ask it as they go. Spawning, stopping, sharing and removing only ever read it.
So a wrong guess costs one edit to a file you can see. It never costs a mysterious failure at start time.
There is no model SDK and no HTTP library in the binary. pando itself talks only to this machine. What reaches the network are the programs it runs: git, gh, cloudflared, docker, your install and hook commands, in namespaced mode the database clients, and for pando update, curl and brew or cargo. There is no telemetry, and you need no account.
Questions
How is this different from plain git worktree?
git worktree add ../x feat/x gives you a second checkout and nothing else. pando new feat/x makes the same kind of worktree, but under ~/.pando instead of beside your repository, and where the disk can clone, as a copy-on-write clone of your main checkout that git then brings to the branch. It links in the gitignored files the project needs, runs the project's own install inside the checkout, and records it.
pando start then adds what makes it run: ports that do not collide, detached processes, logs and readiness. Optionally it adds private or namespaced services and a public URL, all on one screen. Worktrees you made by hand are managed too.
Does every worktree get its own node_modules? Its own .env?
It gets its own dependencies. pando runs the project's frozen install inside each worktree and never links dependency directories. With clone = ["node_modules"], which pando proposes when your main checkout has them, the main checkout's are cloned in first, copy-on-write: each worktree's own copy, sharing disk blocks until it changes.
A later start runs the install again only when a lockfile, a version file or the prelude changed.
Local config works differently. Gitignored files like .env are symlinked to the main checkout's copy by default, so editing one edits main's. provision_mode = "copy" gives each worktree its own copy.
What survives closing the terminal? A reboot?
Closing the terminal or quitting the TUI leaves everything running. A reboot stops it all, and the next start comes back on the same URLs. Nothing restarts by itself: see Running.
My Node from nvm (or fnm, rvm…) is not found.
pando starts commands with bash -lc, a login bash, which reads ~/.bash_profile and never ~/.zshrc. A version manager set up only in .zshrc does not exist there.
pando doctor shows which binary each language resolved to. The fix is a one-line [runtime] prelude for your machine, kept in ~/.pando/config.toml rather than in the repository.
I moved my repository and pando forgot it.
A project's pando data is keyed by the folder's name and a hash of its path, so after a move pando sees a new project. pando doctor finds the old one, and pando doctor --adopt <old-id> moves its config, state and worktrees over.
Does pando new fetch the newest base first?
No. A new branch forks from the last-fetched origin/<base>, so run git fetch first when you need the newest commit. An existing branch is looked for locally, then on origin.
How many worktrees can run at once?
As many as your machine can run. Every running worktree runs its own dev servers, and in isolated mode its own databases too. The ceilings in the code are 1,971 port windows, and 15 Redis slots per Redis server for namespaced worktrees. The TUI is built for dozens of rows.
Is a share link private?
No. Anyone with the link reaches the app until you unshare, stop, restart or remove the worktree, and with auth_cmd every visitor gets the same session. See Sharing.
Logged in on one worktree, logged in on all of them?
Browsers keep cookies per host, not per port, so every http://localhost:<port> shares them. That is how the web works, and pando does not change it. When two branches' sessions get in each other's way, use a private window for one of them.
Linux? Windows?
macOS is where pando is developed. Linux passes the whole test suite on every change, but nobody has used it there for real work yet. On Windows, run it inside WSL 2, with the repository under ~. See Platforms.
Does pando use AI, or phone home?
No and no. Detection is rules and data tables, and the runtime never calls a model. The agent in the first run is your own coding agent, which pando never launches: the setup screen only copies a prompt for you to paste.
There is no telemetry in the code. pando itself connects only to this machine: pando check asks your app for / on localhost, and the share proxy forwards to it. The network is reached only by the programs it runs (see No AI at runtime).
Where it stands
pando is pre-release. What changed in each version is in the changelog.
What there is
- Every command on this page is implemented and covered by tests.
- The tests read no developer's shell profile and need none of their tools. The databases in the tests are throwaway servers the tests start themselves.
- pando is developed on macOS. For every change, CI checks formatting, runs clippy and the whole test suite on macOS and on Linux, and runs clippy for a native Windows build. All of it must pass.
- Binaries for macOS and Linux, the install script and the Homebrew tap ship with every release.
What there is not, yet
- There is no crate on crates.io yet.
- Nobody has used pando on Linux for real work yet: the suite that passes there runs on fixtures. Under WSL 2 the suite passes too, and fixture worktrees have run there, but no real project yet. On Windows, pando runs inside WSL 2, not natively.
- pando has met only a handful of real projects: the monorepo it was built for, where it is used daily, and the apps of the people who opened its first issues. Each found something no fixture had, and all of it is fixed.
- Namespaced mode is experimental. Its container path is tested with a stand-in Docker in front of real servers, not yet in a real container, and the prefix engines on fixtures alone.
A tool this heavily tested against situations it invented still breaks on first contact with one it did not. If pando breaks on your project, that is the most useful issue you can open. Open an issue.
What is next
Roughly in order: a published crate, a JSON schema for pando.toml, and a recipe directory with its own contribution guide.
Contributing and licence
pando is small enough to read and strict about how it grows. Most of what it knows about the ecosystem is data, so many useful changes are a single row or a single TOML file:
| You know… | Your contribution | Where |
|---|---|---|
| a database or cache pando should run natively | a service recipe | src/recipes/builtin/*.toml |
| an engine namespaced mode should know | a recipe with a [namespace] or [prefix] table and no [service] | src/recipes/builtin/*.toml |
| a framework pando misreads | a detection rule | src/catalog/frameworks.rs |
| a package manager or lockfile | a row | src/catalog/package_managers.rs |
| a language or version manager | a row | src/runtime/languages.rs |
| a colour scheme you love | a theme | src/theme/builtin/*.toml |
| a project shape pando breaks on | a fixture and a failing test | tests/common/mod.rs |
| a clearer way to explain it | a change to this website: plain HTML, no build step | site/ |
Every change passes three gates:
$ cargo test $ cargo clippy --all-targets -- -D warnings $ cargo fmt --check
- The source and its issues, for bugs and ideas.
- CONTRIBUTING.md: the map of the code, the testing rules, and how a pull request goes.
- The changelog.
- Security problems go through SECURITY.md, never a public issue.
- Everyone taking part follows the code of conduct.
Licence
pando is free software under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). You may use, study, change and share it.
If you distribute pando, or a program built from it, or let people use a modified version over a network, you must offer them its complete source under the same licence. Contributions are accepted under the same terms.