Skip to content
mertkaradayiPublic

About

pando, the worktree tool: one repo, every branch alive. A git worktree per branch, each with its own running dev server, database and shareable URL, in one TUI.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

24 stars

Watchers

0 watching

Forks

pando, the worktree tool

One repo. Every branch alive.

The pando setup screen: the PANDO wordmark in gold over a grove of aspens whose stems share one root system. The leaves quake, and the roots light up green when the setup check passes.

License: AGPL-3.0-only CI Rust 2024 edition Platform: macOS, Linux and WSL 2 Version 0.11.2, pre-release PRs welcome GitHub stars

Website · Get started · First run · Commands · Modes · For agents · Contributing · Status

Pando is a forest that is one tree. Your repo is too. pando checks 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.

Get started

1. Install pando. On macOS or Linux, or Windows inside WSL 2, no Rust needed:

brew install mertkaradayi/tap/pando

No 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 | sh

Install 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:

pando

The 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 browser

Your 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 doctor

It 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.

Why

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.

Sixty seconds

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  clean

Nothing 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.

The story

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.

What it does

  • 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's target too, 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 update upgrades 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.

The promise

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.

Your first run

cd your-project
pando

The 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.

Commands

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.

In the TUI

⏎        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.

Several repositories

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.

Shared, namespaced, isolated

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 as backend/.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's POSTGRES_USER needs neither.

  • A server in a container needs neither the grant nor a question: its environment already keeps its administrator (POSTGRES_USER and POSTGRES_PASSWORD, MARIADB_ROOT_PASSWORD or MYSQL_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_DB beside 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.

  • rm drops 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. doctor lists 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__, or laravel_database_feat_x__ after main's REDIS_PREFIX. pando makes nothing there, so it records and drops nothing; rm says what it leaves. Every process of a namespaced worktree is also told PANDO_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, mariadb or redis-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, through pando init --answers. None of it is a secret, so a committed pando.toml may 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 signals lists 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"].

Themes

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 terminal

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: 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.

For agents

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. 3 means 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 through pando 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.

Install

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 update

The install script, with nothing else installed:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mertkaradayi/pando/releases/latest/download/pando-cli-installer.sh | sh

It 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.

What else pando uses

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 gh

Your 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.

Contributing

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 it

Every 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.

Status

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.

Star history

Star history of mertkaradayi/pando over time

License

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.

About

pando, the worktree tool: one repo, every branch alive. A git worktree per branch, each with its own running dev server, database and shareable URL, in one TUI.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

24 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages