Everything everywhere all at once

Fig. 2The shape of Pando

1. One monorepo per project, shared live

   It is just your folders. The one rule: each code repo lives under projects/. Everything else is yours.

   $ pando clone acme~/acme/AGENTS.mdartifacts/decisions/0007-merge-commits.mddocs/research/wiki/projects/api/projects/web/worktrees/main/worktrees/agent-1/Claude Codeworktrees/agent-2/Codex

   1. Your artifacts, docs, wiki, and decision recordsPlain files, live on every machine. This is the meta layer: whatever you keep outside projects/.
   2. Your codeEach folder in projects/ is its own repo, with a protected main.
   3. Your agentsOne worktree per agent. It appears at once, and files download when opened.

   Pando adapts to any monorepo layout. projects/ is only the default; one line in .pando/pando.toml points it at yours.

2. Many (remote) agents at once

   Everyone works in the same filesystem: the same folders at the same paths on your laptop, a teammate's, and every agent's cloud sandbox.

   ~/acme/AGENTS.mdartifacts/decisions/0008-q4-plan.mdsaveddocs/research/wiki/projects/web/worktrees/

   ~/acme/AGENTS.mdartifacts/decisions/0008-q4-plan.mddocs/research/wiki/projects/web/worktrees/

   ~/acme/AGENTS.mdartifacts/decisions/0008-q4-plan.mddocs/research/wiki/projects/web/worktrees/

   Docs and decisions change everywhere as they are saved. Code reaches others when it is pushed.

3. Review built for agents and people

   A review is the branch diff (the three-dot diff, as on GitHub) and the branch's commits, with their messages and who made them. Agents read it as JSON; people read it in Plannotator.

   $ pando diff decision-chips --json
   { "branch": "decision-chips", "base": "c03d41e", "head": "9f1c2ab",
     "files": [
       { "path": "apps/web/src/DecisionChip.tsx",
         "status": "added", "additions": 84, "deletions": 0 },
       { "path": "apps/web/src/Card.tsx",
         "status": "modified", "additions": 12, "deletions": 3 } ],
     "commits": [
       { "id": "9f1c2ab", "message": "Show the linked decision on each card",
         "trailers": {
           "Pando-Agent": "agent-1",
           "Pando-Worktree": "projects/workspaces/worktrees/decision-chips",
           "Pando-Machine": "sandbox-1" } } ] }
   $ pando review decision-chips   # opens it in Plannotator

4. A person merges

   A person's Merge is the approval, and the branch's review page is the pull request. Agents comment but never merge. Merge commits keep every commit and message on main, and main never takes a direct push.

   # agent-1, in its worktree
   $ git push origin HEAD:main
   refused: main is protected; push a branch
   # you, after the review
   $ pando merge decision-chips
   main is now 3e7a91c: a merge commit by you, with all 4 commits

5. Checks run elsewhere

   Every push sends a signed webhook. Buildkite, or any CI, runs the checks and posts the status back. Merge waits for green; anyone who may merge can force it.

   # each push: a signed POST to your CI
   X-Pando-Event: push
   X-Pando-Signature-256: sha256=<HMAC of the body>
   # the CI posts its status back
   POST /v1/repos/{repo}/commits/4be0c17/statuses
   { "context": "ci", "state": "failure" }
   $ pando merge search-index
   refused: required check "ci" is failing on 4be0c17
   $ pando merge search-index --force

6. Nothing is lost

   Two saves of one file keep both versions. Every save to the meta layer is history. Large files and images go to R2.

   # two machines saved decisions/HISTORY.md at once
   $ ls decisions/
   HISTORY.md  HISTORY.conflict-local-<timestamp>.md
   $ pando resolve decisions/HISTORY.md
   $ pando history decisions/HISTORY.md
   $ pando restore decisions/HISTORY.md --to 10:42

7. Built on Cloudflare

   Every part runs on Cloudflare's developer platform.

   Workers®

   the git door, the API, merges and webhooks

   Artifacts

   every repo, its branches and its history

   Durable Objects™

   the meta layer's live saves, and each monorepo's state

   R2

   large files and images

   The mount engine is ArtifactFS (Cloudflare, Apache 2.0). The Mac mount, Pando.app, starts from Oak's open-source FSKit extension and follows its approach of an extension in front of a daemon (Oakspace Inc., Apache 2.0). People review in Plannotator.