Get started

This page takes you from nothing to a merged branch. You need git.

Install pando

pando is one program. Pando releases it on Pando itself: each release of Pando’s code carries pando for macOS and Linux, on Apple chips or ARM and on Intel or AMD. One command installs the one for this machine:

curl -fsSL https://gitpando.com/install | sh

It downloads pando from the latest release, checks its SHA-256 against the release’s SHA256SUMS file, and puts it at ~/.local/bin/pando. To read the script first, open app.gitpando.com/install.

The same by hand, without the check:

mkdir -p ~/.local/bin && curl -fsSL -o ~/.local/bin/pando "https://app.gitpando.com/v1/monorepos/ramos/pando/repos/projects-pando/releases/latest/files/pando-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')" && chmod +x ~/.local/bin/pando && pando help

Put ~/.local/bin on your PATH if it is not there already. The release’s SHA256SUMS file lists each file’s SHA-256, to check it with shasum -a 256 ~/.local/bin/pando.

Or build it from Pando’s source, with Go 1.26:

cd cli
go build -o ~/.local/bin/pando ./cmd/pando

Sign in

pando login

With no --server, pando login signs in to Pando at https://app.gitpando.com. pando shows a code and a link, and opens your browser. Confirm the code there. The terminal then says Signed in to ... as <your login>. The credential is kept in ~/.pando/, readable only by you. From then on, git and pando on this machine act as you, with no further sign-in.

pando auth status shows who this machine is signed in as.

Clone a repository

A repository has an owner and a name, like ramos/acme. Clone it the way you would with git:

pando clone ramos/acme
cd acme

The folder looks like this:

acme/
  AGENTS.md  decisions/  ...      shared files, the same on every machine
  projects/
    web/
      worktrees/
        main/                     main, read-only, follows every merge
    api/
      worktrees/
        main/

Every project under projects/ gets a read-only worktrees/main/. It moves to the new main after each merge. You never edit it.

Each worktree is a git clone: every file of its branch is on disk, so your editor, search and git work as they do in any clone.

The shared files around the projects (notes, decisions, plans) are the same on every machine. pando sync keeps them live while it runs; see Shared files.

To start a repository of your own, run pando init in a folder that holds your git repos under projects/. To use Pando with one ordinary git repo, see A plain git repository.

Work on a branch

Each branch gets its own folder, a worktree:

pando worktree add projects/web fix-login
cd projects/web/worktrees/fix-login

fix-login is a new branch off main, or the existing branch of that name. Inside the worktree, git works as usual:

git status
git commit -am "Fix the login redirect"
git push

Main is protected. A push to main is refused with main is protected; push a branch and merge it. Push your branch instead.

Give every agent its own worktree. Two agents never share one, so neither can break the other’s work.

See Worktrees for how a Pando worktree differs from git worktree.

Review and merge

From inside the worktree:

pando diff                        # the branch diff against main
pando review -m "Looks right"     # leave a comment
pando merge                       # land it on main with a merge commit

The same branch has a page in the web app: its commits, the diff, reviews, checks and a Merge button.

A commit’s page

Each commit has its own page at /<owner>/<repo>/projects/<project>/commit/<sha> (in a plain repository, /<owner>/<repo>/commit/<sha>). It shows the commit’s message, its author and when it was committed, the branch it came from (or, for a merge commit, the branch it merged), its checks, and the files it changed against its first parent, in the same view as the branch’s Files changed. Copy sha copies the full sha. The short sha in a branch’s commit list, a file’s history, a session’s commits, the Merge box and a check’s line in the activity (on a commit no branch is at) all open it. The address also takes the first 7 characters of a sha or more.

Merge waits for the checks the project requires (see Checks and CI). Pando merges whole files: if the branch and main both changed a file in different ways, the merge stops and lists the files. Merge main into your branch, fix them, push, and merge again.

Clean up

pando worktree remove projects/web/worktrees/fix-login

pando worktree remove refuses while there is work that is not committed or not pushed. The branch stays on the server until it merges.

Next

• CLI reference: every command and flag.
• Projects and references: keep someone else’s repo nearby to read.
• Limits: file and push sizes, and other numbers to know.