One repo. Every branch alive.
Website · Get started · First run · Commands · Modes · For agents · Contributing · Status
Pando is a forest that is one tree. Your repo is too.
pandochecks out every branch you are working on side by side, gives each one a running dev server, its own database, and a shareable URL, and never writes a byte into your repo.
1. Install pando. On macOS or Linux, or Windows inside WSL 2, no Rust needed:
brew install mertkaradayi/tap/pandoNo Homebrew? This one line does the same:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mertkaradayi/pando/releases/latest/download/pando-cli-installer.sh | shInstall has the details and building from source.
2. Open a terminal in a project you work on. pando works on the git repository you run it in: the one with the dev server you wish you could run on two branches at once. Nothing else needs to be set up first.
3. Run it:
pandoThe first time, pando opens its setup screen. Press a to copy a
one-line prompt, and paste it into Claude Code or Codex, opened in the same
project: your agent reads the project, answers pando's questions, and
proves the setup in a throwaway worktree. The screen turns green when it
passes. No agent? Press enter, and pando tries its own guess. Esc skips
the setup altogether. Your first run walks through it.
4. 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 browserYour main checkout is untouched and still runs as before. In the TUI, the
same steps are n, then enter. pando rm feat/checkout stops it and
removes the checkout and its data.
5. See what else your project needs:
pando doctorIt lists every tool this project will have pando run, which ones are
installed, and the command that installs each one that is missing. Only
git is required; the rest is needed only for the feature that uses it:
What else pando uses.
mertkaradayi.github.io/pando tells the story in pictures and has a copy of the TUI you can drive with your keyboard, in the browser, before installing anything.
Created by Mert Karadayi.
You are halfway through feat/checkout. A review lands on fix/login-loop.
Someone asks for a link to feat/search, and an agent in another terminal
wants a branch of its own to break things in.
Without pando, that is a stash, a checkout, a reinstall, a restart, a reseeded database, and a port that is already taken, three times over. With pando, every branch is its own checkout, already running:
your repository
one object store, one history, one root system
┃
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┻━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ ┃ ┃ ┃
⌂ main ● feat/checkout ● fix/login-loop ○ feat/search
your checkout, web :22809 web :22815 stopped, one
your servers api :22808 api :22814 keypress from
shared database its own postgres running
◈ public URL in a container
Each stem is a git worktree with its own processes, ports, dependencies and logs. What it runs on is your choice per branch: your main checkout's database, a database of its own inside your server, or private copies of every service. All of it on one terminal screen, for people and for the coding agents working beside them.
pando with no arguments is the TUI. Everything it does is a command too;
this is a real run, trimmed a little, on one of the fixture repositories
pando's tests are built on — a workspace with a web app, an API and a
Postgres in its compose file:
$ 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 cleanNothing was configured by hand: pando read the lockfile, the dev scripts, the
env example and the compose file, and chose. pando doctor says what it
detected and from where.
Pando is a single quaking aspen in Fishlake National Forest, Utah. It looks like a forest. It is one organism.
- About 47,000 stems, all genetically identical, sharing one root system
- About 43 hectares, roughly 106 acres
- About 6,000 metric tons, the heaviest known living thing
- A root system between 9,000 and 16,000 years old
- Each stem lives 100 to 130 years and is replaced from the roots
- Named in 1993; the Latin means "I spread"
Your repository works the same way.
| Pando | Your repo |
|---|---|
| The root system | The repo. One object store, one history, never touched. |
| Each stem | A worktree. A complete tree above ground, with its own running app and its own database. |
| Stems come and go | Branches come and go. The root persists. |
| "I spread" | Spread your branches out and let every one of them live. |
- Lists, creates, and removes git worktrees for the repo you are in — or, for a product split across sibling repositories in one folder, a set of worktrees, one of each, on one branch and one row
- Keeps them light on disk: where the filesystem can clone (APFS on macOS;
btrfs, XFS on Linux), a new worktree's files are copy-on-write clones of
your main checkout's, and git writes only what the branch changed;
clone = ["node_modules"], which pando proposes for the dependency trees your main checkout has (a Rust crate'stargettoo, so a branch builds only its own crates), does the same for them before the install - Starts each worktree's dev server on its own ports, detached, with logs
- Optionally gives each worktree private copies of its services: Postgres, Redis, MariaDB, whatever your compose file declares — or, on a machine that would rather not run Docker, the same databases natively from a recipe you can override
- Or, experimentally, a database, a Redis slot or a name prefix of its own inside the servers your main checkout already runs: no server to start, nothing to wait for, and main's data untouched
- Shares any running worktree through a public tunnel URL
- Turns an open pull request into a running worktree: pick it from the list, press enter — a fork's too
- Shows all of it on one terminal screen, with a real log viewer
- Keeps itself current:
pando updateupgrades it the way it was installed — Homebrew, cargo, or the install script
Built for people, and for agents, who work on several branches at once.
pando never writes into your repository. Not a config file, not a gitignore
line, not a lockfile change. Everything it learns and everything it runs lives
under ~/.pando:
~/.pando/
├── config.toml your choices: theme, appearance
├── recipes/ themes/ your own service and engine recipes, colour themes
└── projects/<project>-<id>/
├── pando.toml the whole configuration for one project
├── worktrees/feat+checkout/ a stem: the branch's own checkout
├── logs/feat+checkout/ every process's log, for the log viewer
├── data/feat+checkout/ its private services' data, when isolated
└── state.json what runs where, on which ports
One mode writes somewhere that is yours all the same: a namespaced
worktree gets a database of its own in your own database server. That is
opt-in, named after your main database so it can never be it, made by a
login that may create databases (granted once, by you, or for a server
in a container by its own administrator), and dropped only by rm, only
when pando's own records say pando made it. See
Shared, namespaced, isolated.
cd your-project
pandoThe first time, pando opens its setup screen instead of the list, on a grove of its own: Pando, the aspen that is one tree with 47,000 stems, drawn in dithered blocks, its leaves quaking. Each project gets its own grove, grown from its name:
██████████ ██████ ██ ██ ████████ ██████
██░▒░▒░▒██░ ██ ▒░▒░▒██ ████ ██░ ██░▒░▒░▒██ ██ ▒░▒░▒██
██████████▒ ██████████▒ ██▒░██ ██▒ ██▒ ██▒ ██▒ ██▒
██░▒░▒░▒░▒░ ██░▒░▒░▒██░ ██░ ▒████░ ██░ ██░ ██░ ██░
██▒ ██▒ ██▒ ██▒ ░██▒ ████████ ░▒ ░██████ ░▒
▒░ ▒░ ▒░ ▒░ ▒░ ▒░▒░▒░▒░ ▒░▒░▒░
░ ▓▒▓▒▒ ░░░ ▒▓▒
░▓███▒ ▒▒▒ ▒████▓░ ░▓█▓ ░ ███ ▓▒▒ ▒▒▓▒░ ▒█▒░
░▒░ ░▒▓█▓▓ ░▓██▓░████▓░ ▒███░▒▓█▓▒ ▒███▒ ▒███▒ ░ ▓███▓ ▒███▒
░███░ █ ░▓██▒ ░█░ ░▒█▓░▓███▒ ▒▓▒ ░███░ ░███▒▓████ ▓███▓
░▓█▓░ ▓ ░█░ ▓ █ ▓██▓▒ █ ░█▒ ▒███▓ ▒█▒░ ▒██▒
▓ ▓ █ █ █ █ ▓ █ █ ▓ █
█ █ █ █ █ ▓ █ ▓ █ █ █
░░░░█░░░░░█░░░░░█░░░░░█░░░░░░█░░░░█░░░░░█░░░░░█░░░░░█░░░░█░░░░░█░░░░░░░░
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃
╺━━━┻━━━━━┻━━━━━┻━━━━━┻━━━━━━┻━━━━┻━━━━━┻━━━━━┻━━━━━┻━━━━┻━━━━━┻━━━━━━━╸
main feat/checkout fix/login-loop feat/search
The roots stay dark until the setup passes; then they light up. Every
project is a little different, so the surest start is to let your own
coding agent look at it. Press a to copy this one line, and paste it
into Claude Code or Codex, opened in the project:
Set up pando here: run `pando init --agent` and follow what it says.
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. The agent answers through pando init --answers -
on stdin, never a file in your repository, and proves the answers with
pando check: a throwaway worktree of the commit a new branch would fork
from, installed, started, its page asked for, and removed again, with no
branch and nothing left behind. It asks you nothing along the way: where
pando's rules leave a question open, the agent decides it. When the check
passes, the agent says so, lists what it set and how to change it, and
the setup screen turns green by itself: you're ready. It can also
remember how to run this project's worktrees with pando, in its own
memory and never in your repository, and saves that only if you tell it
to, so a later session starts, stops and reads them through pando rather
than by hand. From then on,
pando opens the list.
No agent? Press enter on the setup screen and pando tries its own guess,
tested by the same pando check. Esc skips the setup altogether and goes
straight to the list; nothing is ever gated on it.
pando new and pando start work on a project that was never set up
too. Nothing is asked where pando can tell: it reads the repository —
the lockfile, the dev script, the env example, the version file — and
takes its own first choice for anything it has one for, printing each as
it goes with the file it 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.toml
That file is the whole configuration; edit any line, or delete one and
run pando init, which puts every open question to you instead of taking
a default. pando doctor says what was detected and from where, and
pando check tests the setup again at any time, and says what each
worktree costs on disk: the gitignored trees it builds from nothing, the
ones clone could share instead, and what the project's tools wrote
outside it, such as a build cache that fills again for every worktree.
Which of those to share, and how, is the project's own to decide, so
pando measures and your agent, or you, chooses. A question pando has no
option for at all is still asked, and so is the one real choice
isolation brings — which services to run private copies of.
pando open the TUI for the repo you are in
pando new <branch> create a worktree and branch from the default base
pando start <name> start its dev server; --isolated for private services,
--namespaced (experimental) for its own database in yours
pando stop [name] stop one worktree, or the main checkout; --all for every one
pando restart <name> stop and start again, keeping the ports
pando ls list the main checkout and the worktrees: status, URL,
ports, git; -l for paths
pando rm <name> stop everything, remove the worktree, wipe its data
pando share <name> expose it at a public URL
pando unshare <name> take the public URL down
pando open <name> open its URL in the browser; --public for the shared one,
--app for its app on a simulator or device
pando logs <name> tail its logs; --json for machines
pando status what runs where, per process; --json
pando path <name> print the worktree's path
pando init answer every setup question now instead of as you go
pando check test the setup in a throwaway worktree, then remove it
pando doctor explain what was detected, why, and what is missing
pando signals dump detection signals as JSON, for humans or agents
pando completions print a completion script for bash, zsh, fish…
pando update update pando to the latest release, the way it was installed
A worktree is named by its branch (feat/login) or by its directory
(feat+login). Inside a worktree, start, stop, restart, logs,
open, share and unshare need no name. start, stop, restart and
rm take several — pando start feat/a feat/b — and act on them side by
side, each said as it finishes; one that fails leaves the others, and the
exit code is then 1.
The main checkout runs too, first in every list, named the same way —
pando start main — or with no name from inside it (but for stop,
which there stops everything). It is yours and set up by you, so pando
runs only its processes, on ports it allocates, and nothing else: no
install, no hooks, and always on the project's own services.
On a terminal, start and restart wait until every process answers,
and when one does not they print the last lines of its log and why.
From a script they return once everything is spawned; --wait and
--no-wait choose either way.
⏎ pick its mode — shared, namespaced (experimental), isolated —
and start it, or switch it when it runs
s i S start it: as last time, isolated, or on the shared services
l open the log viewer
x X stop it (or cancel its start), or stop everything
r P restart it, or only the selected process
o O open its URL (or its app, where it serves no page), or the public one
c C y copy its local URL, its public URL, its path
t share it publicly, or stop sharing
! e a shell in it, or open it in your editor
n d new worktree, remove one (never the main checkout, ⌂)
+ esc mark rows, or unmark them all: s x r d then act on every
marked one at once, d in one dialog
p open pull requests: ⏎ makes a worktree for one
space p open its own pull request on GitHub (the row's #n)
a v copy the setup prompt, or test the setup (pando check)
T colour themes, previewed live
m ? what pando said in full, and every key
The mouse works as well: click a worktree, a dialog's option or a line
of the log viewer, and click it again for ⏎; click a key hint such as
esc cancel to press it; the wheel scrolls whatever is under it. While
pando has the mouse, hold shift to select text (option in iTerm2), or
set [ui] mouse = false to leave the mouse to the terminal.
More on the TUI: the chooser, confirmations, the list, pull requests, the log viewer
Enter opens the mode chooser on every worktree. On a stopped one the
mode it last ran in is under the cursor and marked last used, so
enter, enter is still one quick start; one never started has shared
there. On a running one the mode it runs in is marked running, and
choosing another switches it — every process restarts on the other
services, and the chooser was the asking. The logs are l.
A key that would interrupt a running worktree asks for a second press:
r r restarts it, x x stops it, P P restarts one process, and i
or S twice restarts it in the mode it already runs in. Esc takes the
first press back. x on a worktree being started or restarted cancels
that at once: the start stops at its next safe point, undoes what it
had brought up, and the worktree ends stopped. q q with a start in
flight cancels it the same way and quits once it is undone. Moving a running worktree between modes with i or
S, sharing it, and removing it ask in a dialog instead. On a worktree
with nothing up, stopped or failed, the keys that ask twice act on the
first press; sharing and removing still open their dialog.
+ marks the row under the cursor and moves down, and a + before
the cursor's column shows it; + again unmarks it, and esc unmarks
every row. While rows are marked, s, x, r and d act on all of
them at once, each on its own worker: x x and r r ask once for the
whole set, and d opens one dialog that says what each removal stops
or takes with it, which only F removes (uncommitted changes), and
which stay (locked, the main checkout). Every other key still acts on
the row under the cursor. A mark stays on its worktree through a
refresh, a re-sort or a filter, and goes with it.
The list is a table with a header row: branch, then PR (its pull
request, ◍ #482), dir (the directory, when it is not the branch's
own name, or main checkout, detached or mixed branches), port
(the port of its URL while something runs), other ports (the rest, for a worktree that runs more than one process),
public (◈ while it is shared) and git (behind, ahead and ✎ for
uncommitted changes; or prunable or locked). A column shows only when
some row has something in it, and a narrow pane gives up the least
useful first. The branch cell carries the rest: the glyph before the
branch says whether it runs — ● running, ◌ starting, ✗ failed,
○ stopped — and a mode mark (▣ when it runs private copies of the
services, ◧ when it runs on a database, a slot or a prefix of its own
in the main checkout's servers, each in its own colour; ⌂ marks the
main checkout) and a word such as failed follow it. The full URL and
the rest are in the detail pane beside it.
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, which the list's title
names: by pull request, the highest number first (the default); newest
first; last run first; or by name.
The choice is saved as [ui] sort in ~/.pando/config.toml, as pr,
newest, run or name.
p lists the repository's open pull requests through the GitHub CLI
(gh, signed in); typing narrows them by number, title, branch or
author. Enter checks out the pull request's branch in a new worktree, or
goes to the worktree it already has. A pull request from a fork has no
branch on origin, so pando fetches it from pull/<number>/head into a
branch of its own, pr-<number>/<branch>. One whose branch cannot be
found on origin is refused rather than started as an empty branch of
the same name.
The log viewer has a tab per log, led by an all tab that merges every
process's when there are several. 1–9 switch tabs, / searches, f
filters by level, and e/E jump between errors.
A product split across repositories cloned side by side is one project:
run pando in the 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 repository on
feat/x — the branch where a repository already has it, here or on
origin, and a new one from that repository's own base where it does not.
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};
stop, rm, status, open, share and check act on the set, and the
TUI shows it as one row, with each repository's branch and changes in its
detail. A path in config names its repository first: provision = ["backend/.env"].
Every repository directly under the folder is in the project. In
~/.pando/projects/<id>/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" }pando init --agent from the folder hands that setup to your coding
agent the way it does for one repository, and 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 from pando new on its branch; pando status lists each repository of a set, and
pando logs --source backend reads the processes that run in it.
From inside a set, or one of its checkouts, pando finds the folder's
project. From a repository's own main checkout it is that repository, as
before. The git menu moves one checkout at a time: on a set it opens on
the first repository's, measured against that repository's base, and
tab goes to the next.
A worktree's code, processes, dependencies, ports and logs are its own whatever it runs on. Its mode decides what happens to its data:
| Mode | Its data lives in | Start it with |
|---|---|---|
| shared | the main checkout's database and cache, data and all. The default, and the way back from the other two | start --shared, or S |
| namespaced (experimental) | the main checkout's servers, with a database, a Redis slot or a name prefix of the worktree's own in them: shop__feat_x beside shop in Postgres or MariaDB, slot 3 beside slot 0, indexes under feat_x__ in Elasticsearch |
start --namespaced, or the chooser on enter |
| isolated | servers of its own on ports of its own: containers from your compose file, or native engines from a recipe | start --isolated, or i |
A namespaced database is built by the branch's own schema step, never
copied from main's, and both it and the slot are kept through a switch to
another mode until rm drops them.
How a namespaced start stays careful in a server you own
-
It logs in as your app does, with the user and password beside the address in the main checkout's
.env— the root's, or the one in the directory a process runs in, such asbackend/.env. Where there are none, a server in a container is reached as its own administrator, and anywhere else pando asks once, keeps the answer in pando's own config for the project (mode 0600), and hands it to the database client in its environment, never on a command line. -
That login has to 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:
GRANT ALL ON `shop\_\_%`.* TO 'app'@'localhost';
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'sPOSTGRES_USERneeds neither. -
A server in a container needs neither the grant nor a question: its environment already keeps its administrator (
POSTGRES_USERandPOSTGRES_PASSWORD,MARIADB_ROOT_PASSWORDorMYSQL_ROOT_PASSWORD), so pando runs that same statement itself, as the administrator, and the database is made as the app's login, which owns it. Where the app's env files carry no login at all, the administrator is the login. Only a server with no administrator pando can find gets the statement printed. -
The database is made in main's character set or encoding and locale, so a schema written for main runs into it the same way.
-
A Redis slot is given out only where the app reads a slot setting (
REDIS_DBbeside its address, or the path of its URL), and only while the slot is empty: keys pando did not put there are somebody else's. When all fifteen are held, the start asks which stopped worktree gives its slot up. -
rmdrops only what pando's records say it made, on the server it made it on, and never the main checkout's database or slot whatever a record says.doctorlists a database named for a worktree that no record holds, with the command that drops it, and never drops it itself. -
Where a server has no namespace pando could make — an Elasticsearch index, a Kafka topic, a Memcached key is the app's own — a worktree is told a prefix instead, in the key its app already reads one from beside the address:
ELASTICSEARCH_INDEX_PREFIX=feat_x__, orlaravel_database_feat_x__after main'sREDIS_PREFIX. pando makes nothing there, so it records and drops nothing;rmsays what it leaves. Every process of a namespaced worktree is also toldPANDO_NAMESPACE=feat_x, for an app that puts it in front of its names by itself. -
A database in Docker usually leaves the host with no
psql,mariadborredis-cli. Then the commands run in the one container that publishes the server's port on this machine's loopback, with the client its image ships (docker exec, the password passed by name). A server elsewhere, or a native one listening on the same port, is never taken for it. -
What pando cannot tell by itself is written in its own config for the project, under
[namespaced.<service>]— usually by the setup agent, throughpando init --answers. None of it is a secret, so a committedpando.tomlmay carry it too:[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 signalslists what a namespaced start would do with each service, and why one stays shared.
Postgres, MariaDB and MySQL databases and Redis slots are made, in a native server or in a container, Postgres images with an extension built in (pgvector, PostGIS, TimescaleDB) included; Elasticsearch, OpenSearch, Kafka, Redpanda, Meilisearch, Typesense, Memcached and Redis get a prefix where the app reads one. Every other service stays shared, and a namespaced start says so for each.
A namespace for an engine pando does not ship
What a namespace is on an engine is data, not code: a recipe's
[namespace] or [prefix] table. A file in ~/.pando/recipes/ adds an
engine, or replaces a built-in of the same name, for every project on
the machine; 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 itself. A sketch, not a shipped recipe —
check the client's own flags before you trust it:
# ~/.pando/recipes/clickhouse.toml
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 is already
there, so pando never takes a database it did not make; a slot's
commands never fall back to slot 0; size prints a bare number; the
password reaches the client only in password_env. pando derives every
name — <main>__<worktree> — and only ever drops one its records say it
made, whatever the recipe says. An engine whose namespaces are the app's
own convention needs only [prefix] keys = ["_INDEX_PREFIX"].
T in the TUI lists the colour themes, each with a swatch of its
colours; moving through them repaints the screen, enter keeps one and
esc puts the old one back. The built-ins are pando's own, Catppuccin,
Flexoki, GitHub (default, dimmed, high contrast, colorblind), Gruvbox,
Kanagawa, Monokai Pro, One Dark, Rosé Pine, Tokyo Night, VS Code and
Zenwritten, each with a dark and a light half that follows the system.
Configuring and writing themes
A choice is saved in ~/.pando/config.toml:
[ui]
theme = "catppuccin"
# appearance = "dark" # or "light"; "auto" follows the system
# theme_from = "~/.config/theme-switcher/current"
# sort = "run" # the list's order: "pr", "newest", "run" or "name"
# mouse = false # leave the mouse to the terminaltheme_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: a background, a foreground and seven
accents for each half, and every other colour is derived from them. One
in ~/.pando/themes/<name>.toml is listed beside the built-ins, and
replaces the built-in of the same name.
pando publishes what it knows as JSON so a program can read it instead of parsing English, and answers come back through one validated write path.
agent/json.md— every machine-readable shape, versioned, with the exit codes.3means pando has a question and the question is on stderr.agent/brief.md— the procedure for turning that evidence into answers: decide what the rules leave open without asking the developer, write only throughpando init --answers, never a byte in the repository, and end by reporting what was set.agent/— a Claude Code plugin and Codex skills, both thin over that one brief.
The binary carries the brief and the shapes too: pando init --agent
prints the setup job for the project you are in, and
pando init --agent --reference brief or --reference json prints either
document whole.
pando runs on macOS (Apple silicon and Intel) and Linux (x86_64 and arm64). Each release ships a ready-made binary for all four, so none of these needs Rust.
On Windows, pando runs inside WSL 2 as the Linux binary: install it in
your distro any of the ways below. Keep the repository in WSL's own
filesystem, under ~, rather than on /mnt/c. git is several times
slower on a Windows drive, and an edit there sends no file event, so dev
servers do not reload. A worktree's localhost URL works from Windows,
and pando open opens it in Windows' browser. Install the tools a
project runs, Node and Docker among them, inside WSL too (for Docker,
turn on Docker Desktop's WSL integration); pando doctor says when the
shell finds Windows' copy instead. A native Windows build runs nothing
yet, and says to use WSL 2.
Homebrew, on macOS or Linux:
brew install mertkaradayi/tap/pando # later: pando updateThe install script, with nothing else installed:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mertkaradayi/pando/releases/latest/download/pando-cli-installer.sh | shIt puts pando in ~/.local/bin and adds that directory to your PATH in
your shell's startup files; to leave those alone, run the script with
PANDO_CLI_NO_MODIFY_PATH=1. Every download has a checksum and a GitHub
attestation, so gh attestation verify <file> -R mertkaradayi/pando
proves it was built here. To update, run pando update: it replaces
pando where it is and leaves your shell's files alone. Rerunning the
line works too.
From source, with Rust 1.88 or newer. With no Rust on the machine,
rustup installs the current stable toolchain, 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. pando update
installs it again at the latest release's tag. On a new Mac, git
comes with the Xcode Command Line Tools (xcode-select --install).
pando --version says which version you have, pando update --check
whether a newer release is out, and pando completions zsh
(or bash, fish…) prints a completion script.
pando itself is one binary. The tools below are needed only for the
feature beside them, and only when your project uses that feature.
pando doctor checks each one and prints the 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 |
brew install cloudflared |
Cloudflare's package |
gh |
the TUI's pull request picker (p) |
brew install gh |
the GitHub CLI's package |
| Docker with Compose | start --isolated, 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, unless the server runs in a container whose image ships it |
brew install redis |
redis-server, redis-tools |
mariadbd, mariadb |
a private MariaDB without Docker; the mariadb client alone for --namespaced, unless the server runs in a container whose image ships it |
brew install mariadb |
mariadb-server, mariadb-client |
postgres, psql |
a private Postgres without Docker; the psql client alone for --namespaced, unless the server runs in a container whose image ships it |
brew install postgresql@16, or brew install libpq for psql alone (keg-only: put $(brew --prefix libpq)/bin on PATH) |
postgresql, postgresql-client |
mongod, mongosh |
a private MongoDB without Docker | brew install mongodb/brew/mongodb-community |
MongoDB's package |
The usual pair on a Mac, for sharing and pull requests:
brew install cloudflared ghYour project's own toolchain (Node and its package manager, Python,
Go…) is whatever you already run it with. pando finds it through your
login shell and never replaces it; pando doctor names any it cannot
find, with how to get it.
pando is small enough to read and strict about how it grows, which makes it a good project to contribute to. 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 is | Where |
|---|---|---|
| a database or cache pando should run natively | a service recipe | src/recipes/builtin/*.toml |
| an engine namespaced mode should give a worktree its own corner of | a recipe with [namespace] or [prefix] 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 the website: plain HTML, no build step | site/ |
Try pando without pointing it at anything real:
scripts/fixture-repo.sh --list # the fixture shapes the tests use
scripts/fixture-repo.sh mono-web-api --listener # build one, and print how to run pando in itEvery change passes cargo test, cargo clippy --all-targets -- -D warnings
and cargo fmt --check. CONTRIBUTING.md has the map of
the code, the testing rules, and how a pull request goes. Bugs and ideas go
in issues; security problems
go through SECURITY.md, never a public issue. Everyone
taking part follows the code of conduct.
Version 0.11.2, released as binaries for macOS and Linux. Every command above is
implemented and covered by tests, in this order: worktrees and their
lifecycle; detached dev servers with their own ports, logs and readiness;
several processes per worktree; the log viewer; private per-worktree
services from the project's own compose file; public tunnel URLs; init,
doctor and signals; native service recipes for machines without
Docker; the JSON contract an agent reads; a worktree from any open
pull request in the TUI; and, experimentally, namespaced worktrees — a
database and a Redis slot of their own in the main checkout's servers,
tested against throwaway Postgres, MariaDB and Redis servers the tests
start themselves. 0.4.0 adds no command: it is all of that after a review of
the whole project and the fixes it found, with a test suite that reads
no developer's shell profile and needs none of their tools. 0.5.0 adds
the guided first run: the first pando in a project with nothing to run
hands its setup to the developer's own coding agent, pando init --agent
prints that job, and pando check proves the result in a throwaway
worktree it removes again. 0.5.1 is the first with binaries: Homebrew
or one install script, no Rust needed. 0.6.0 reads a repository whose
apps sit in directories of their own below a root with no manifest,
recognises Expo apps, and lets an agent describe several processes, so
the first run on a polyglot monorepo ends with every app running.
0.6.1 fixes what the first real Expo project found: Metro keeps its
reloads, is never taken for a web page, and opens in the app's own
development build. 0.6.2 opens that app from pando open and the TUI's
o, on the simulator or an Android device, gives the build commands
Expo accepts, and says when the build installed on the simulator is for
another SDK. 0.6.3 lets b sort the TUI's list and keeps what runs at
its top. 0.7.0 adds the TUI's git menu, space g: fetch, pull, rebase
or merge a row, the commands shown first and a conflict aborted; space
is the list's leader, so sorting moved to ,. 0.8.0 checks a new worktree
out by copy-on-write where the disk can clone, so it costs only the files
its branch changed, and clone does the same for dependencies before
the install. 0.8.1 gives namespaced mode Postgres: a database of the
worktree's own in the main checkout's server, found through the env
files where the app keeps them. 0.8.2 adds pando update, which updates
pando the way it was installed. 0.8.3 proposes clone for the
node_modules the main checkout has, so a new worktree shares its
dependencies too, and the setup agent asks nothing: it decides what the
rules leave open and reports what it set. 0.9.0 makes namespaced mode
agnostic of the engine: a search, queue or cache engine whose app reads
a prefix gets one of the worktree's own, a database in a container is
reached through the client its image ships and granted by its own
administrator, and the setup agent writes what pando cannot tell into
[namespaced.<service>] — so a first setup leaves namespaced mode ready
with nobody asked. Its container path is tested with a stand-in docker
in front of real servers, not in a real container yet, and the prefix
engines on fixtures alone. 0.10.0 runs on Windows inside WSL 2:
pando open opens Windows' browser, and doctor says when the shell
finds Windows' copy of a tool, or the repository sits on a Windows
drive. Under it, everything pando asks of the operating system moved
behind one layer, which changes nothing you would notice on macOS or
Linux. 0.10.1 is the fixes from a review of everything added since
0.4.0. Among them: the git menu never deletes an ignored .env and
moves a branch onto the base it was made from; the share proxy logs in
only visitors through the tunnel; and namespaced mode drops nothing it
cannot prove is the worktree's, gives each database the main checkout
uses one of its own, and tells a Redis slot from the same number on
another server. In 0.10.2, space p in the TUI opens the selected
worktree's pull request in the browser. 0.10.3 lets the TUI start,
stop and restart several worktrees at once, shows a pull request merged
on GitHub without reopening it, and stops a worktree's processes
together rather than one after another. 0.11.0 runs a product split
across sibling repositories as one project: from the folder that holds
them, a worktree is a set of one checkout of each, on one branch, in
one port window and one row. 0.11.1 makes the first-run setup and the
TUI understand that shape. 0.11.2 removes, starts and stops several
worktrees at once, and pando check says what a worktree costs on disk.
What changed in each version is in the
changelog.
macOS is what it is developed on. CI runs the whole test suite on macOS and on Linux for every change, and both pass — but the suite runs on fixtures, and nobody has yet used pando on Linux for real work. Under WSL 2 on Windows the suite passes too, and pando has started, stopped and opened fixture worktrees there, but not yet a real project. CI also builds pando natively on Windows, so its Windows half keeps compiling; that build runs nothing yet and says to use WSL 2.
What that does not mean: there is no crate on crates.io yet, and pando has met only a handful of real projects — the monorepo it was built for, where it is now used daily, and the apps of the people who opened its first issues. The first of them found three bugs in an afternoon — a Makefile target read down to its first line, a failure that left an empty log and no explanation, and a backgrounded server reported as dead — and each one since has found something no fixture had. All of it is fixed, and that is the point: a tool this heavily tested against situations it invented still breaks on first contact with one it did not. If pando breaks on yours, that is the most useful issue you can open.
Next, roughly in order: a published crate, a JSON schema for
pando.toml, and a recipe directory with its own contribution guide.
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.
One root system. Forty-seven thousand stems. Every branch alive.