Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
pando
description
Kickstart usage of the `pando` CLI — inspecting, creating, and navigating Git worktrees. Triggers on "pando", "worktrees", "pando switch", "pando create", "pando commit", "pando get", "pando trust", "pando merge", "pando install", ".pando.yaml", ".pando.local.yaml", "pando config.yaml".
allowed-tools
Bash, Read
effort
medium
pando
pando is a Rust CLI for inspecting, creating, and navigating the Git
worktrees of the repository containing the current directory. Git is the
source of truth — every fact comes from invoking the installed git
executable; there is no libgit2, no cached registry, and no implicit fetch.
Use the CLI, not raw git — this is the point of the skill
In a repository that uses pando, four operations are wrapped by a
pando subcommand instead of being done with plain git. Use the
subcommand, never the raw git equivalent, even though the raw command would
often "work":
Don't
Do
Why the wrapper matters
git worktree add ... / git checkout -b ...
pando switch [--dry-run] [branch], or pando create [--dry-run] <branch> to skip the new-branch confirmation
Applies the branch-resolution order, the configured root, and post-create hooks/trust
git commit -m "<message you wrote>"
pando commit --input-output json (omit a message in the request to let the configured generator write it)
If the user didn't give you a message, do not invent one yourself — let the generator write it. Only supply a literal message when the user gave you that exact text
Resolves the configured target branch, or origin/HEAD, main, then master without fetching, squashes the topic into one generated-message commit by default, runs pre-merge hooks, and is crash-recoverable
git add/git add --patch are still the right tool for staging — only
the four operations above must go through pando, not git.
Local setup
Binaries: pando and its pd symlink on PATH when installed with Homebrew or just install (pinned during generation: v0.1.1).
The installed zsh integration wraps both pando and pd so
switch/create/remove/merge can cd to the destination the selected binary
prints. command pando ... and command pd ... bypass the wrappers.
Config files the CLI reads (see references/config.md):
${XDG_CONFIG_HOME:-$HOME/.config}/pando/config.yaml,
.pando.yaml, .pando.local.yaml.
Global flags
Flag
Values
Purpose
--output <OUTPUT>
human (default), json
Human terminal output or one structured JSON document
--input-output <INPUT_OUTPUT>
json only
Read a versioned JSON request from stdin, emit JSON. human is a hard error
--verbose
—
Disable animated progress and write elapsed phase and Git subprocess diagnostics to stderr
-h, --help
—
Print help (combine with --output json for generated JSON Schemas)
-V, --version
—
Print version
Env var
Purpose
XDG_CONFIG_HOME
Base for pando/config.yaml, trust.json, generated zsh integration. Falls back to $HOME/.config
ZDOTDIR
Where pando install writes/edits .zshrc. Falls back to $HOME
Agents must use --input-output json for every normal operation. Put the
leaf command (and trust subcommand) in argv and the complete command input in
the strict version-1 stdin envelope. Do not parse human tables, messages, or
scalar stdout. Read status, typed result/error, effects, bounded
diagnostics, and executable next_steps instead. Use human commands only
when a returned next step explicitly requires a person's approval.
Requests reject unknown fields, trailing data, unsupported versions, and
mixed command flags. Generated exact-leaf help restricts request and response
schema_version to the literal 1, and response status to "success" or
"error". Dry-run mutating requests use input.dry_run:true.
create requests may include input.description to set the repository-local
Git branch description as part of creation, so do not follow a successful
request with a separate git config branch.<name>.description call.
Force is argv-only authorization for removal. Pass --force only with explicit user approval; never put force in a remove request document. Structured removal evaluates every target's pre-remove hook trust before any hook or destructive work; trust.approval_required identifies the blocked target and includes the shared approval context plus an interactive recovery invocation. JSON cannot grant hook or generator trust or authorize installer
writes. Structured read-only command help derives result schemas and error catalogs from the runtime query contracts. Structured worktree records expose nullable RFC 3339
last_commit_at values and always retain Git discovery order, regardless of
the human worktrees.default-sort preference. pando list --branches --output json emits a distinct result.branches payload (branch, head,
nullable last_commit_at/path/condition, current) in for-each-ref
order, also independent of the personal default sort; path/condition
are null for a branch with no worktree. See the command references
for leaf contracts and approval rules.
To build from source, run just install before pando install instead. Homebrew and just install both provide pando plus its pd symlink. After the deterministic shell changes, pando install detects Pi, Claude Code, Codex, and Gemini CLI, asks which connected agent to use, offers its launch command for editing, saves the choice as global install.command, and launches an interactive full-configuration session. Use --no-guide for only the shell integration or --dry-run for a noninteractive preview. The scaffold remains idempotent and does not enable or overwrite the other user settings.
Source: README.md ("Install")
Configure a root before creating any worktrees
No root is ever created automatically — this is required before the first switch that creates a worktree.
# ${XDG_CONFIG_HOME:-$HOME/.config}/pando/config.yamlworktrees:root:../worktreesdefault-sort:last-commit-at# git, branch, last-commit-at, or pathbase:head# head (default) or fresh
The ignored .pando.local.yaml overlay may override all three values;
committed .pando.yaml cannot set the personal default-sort preference,
though it may set base and target-branch.
Source: README.md ("Global placement")
Switch to / create a branch worktree
pando switch feature/login # exact branch
pando switch # interactive picker
pando switch --branches # interactive picker, starting in branch view
pd switch main --verbose # diagnose elapsed phases on stderr
pando create feature/login # create without confirming; fails if it exists
pando create --fetch topic # refresh the fresh base ref first (base: fresh only)# Agents create and describe a branch in one requestprintf'%s\n''{"schema_version":1,"input":{"branch":"feature/login","description":"Add the login flow"}}' \
| pando create --input-output json
New branches start at the invoking worktree's HEAD unless worktrees.base
is fresh, which cuts them from the target branch's remote-tracking ref
instead. Nothing is fetched implicitly; --fetch refreshes exactly that one
ref. See references/config.md.
The picker shows local HEAD committer timestamps and uses the same anchored
.../ path abbreviation as human pando list output. It starts in the
configured sort mode. Ctrl-S cycles Git order, branch A-Z, last commit newest-first, and
path A-Z without persisting the change or losing the filter/selection. Ctrl-B
toggles between worktree view and branch view (local branches, including
ones with no worktree yet) for the current invocation only — selecting an
unattached branch creates a worktree for it through the same resolver
pando switch <branch> uses.
Source: README.md ("Switching and creating")
Stage deliberately, then commit as an agent — --input-output json
git add README.md src/commit.rs # selected paths, or:
git add --patch # selected hunks# no message given: let the configured generator write itprintf'%s\n''{"schema_version":1,"input":{"selection":"staged","message":{"source":"configured_generator"},"dry_run":false}}' \
| pando commit --input-output json
# user gave you this exact messageprintf'%s\n''{"schema_version":1,"input":{"selection":"staged","message":{"source":"provided","value":"feat: add commit support"},"dry_run":false}}' \
| pando commit --input-output json
Bare pando commit ("selection":"staged") only commits what is
already staged in the index — it never stages for you. If the user asked
you to "commit" without giving an exact message, do not compose one
yourself — send {"source":"configured_generator"} so the configured
generator (or the CLI's own built-in prompt, if none is configured) writes
it. Only send {"source":"provided","value":"..."} when the user gave you
that literal text.
Source: README.md ("Committing"); request schema confirmed against
src/commit.rs's CommitRequest/MessageSource types
Stage everything and commit, with or without a generated message
# generator writes the messageprintf'%s\n''{"schema_version":1,"input":{"selection":"stage_all","message":{"source":"configured_generator"},"dry_run":false}}' \
| pando commit --input-output json
# user gave you this exact messageprintf'%s\n''{"schema_version":1,"input":{"selection":"stage_all","message":{"source":"provided","value":"chore: commit every change"},"dry_run":false}}' \
| pando commit --input-output json
Source: README.md; Selection::StageAll in src/commit.rs
On success, result is {"outcome":"dry_run","ready":true,"selection":"staged"} —
nothing is staged, generated, or committed.
Source: src/commit.rs (run_json's invocation.dry_run branch)
Add a shared post-create hook
# .pando.yaml (committed, read from the invoking worktree)hooks:post-create:-name:Installdependenciescommand:npminstall-command:echo"PORT=$(pando get port)">.env.local
New shared hook commands are untrusted until approved:
Query current-worktree properties (e.g. from a hook script)
branch=$(pando get branch)
path=$(pando get worktree-path)
primary=$(pando get primary-worktree-path)
root=$(pando get worktree-root)
port=$(pando get port)
On "status":"error", read error.code and, when present, next_steps[] —
each entry is a ready-to-run {"action","description","invocation":{"argv","stdin"}}
recovery option (e.g. commit.nothing_staged suggests staging paths, staging
a patch, or retrying with "selection":"stage_all"). Don't guess a recovery
step; use the one the response gives you. Full error-code table in
references/commands/commit.md.
Source: src/commit.rs (recovery_steps, emit_failure_with_context); design
rationale in docs/adr/0002-render-typed-command-outcomes.md
Create a pull request on GitHub, Gitea, or Forgejo
Use pando pr create --remote <name> (or input.remote in JSON) when the
head branch belongs on a personal fork. Remote precedence is explicit remote,
then the branch upstream, then origin, then a sole configured remote. The
resolved target branch must have an upstream forge remote, which supplies the
base repository. Fork heads use owner:branch; preflight and dry-run resolve
both repositories before any push.
pr.provider defaults to auto: github.com uses gh, while another host uses
tea when tea login list --output json has a matching Gitea or Forgejo login.
The setting is legal in global, shared, and local configuration, with local
winning over shared, then global. Set it to github or tea to require one
adapter. Pando represents Tea draft status by adding the default WIP: title
prefix for compatibility across Tea versions.
Merge a topic back into the target (squashes by default)
pando merge --dry-run # preview, including how many commits collapse# agents: squashing is the default in JSON tooprintf'%s\n''{"schema_version":1,"input":{}}' | pando merge --input-output json
pando merge --no-squash # keep the topic's individual commits
merge collapses the topic into one commit after any rebase and before the
fast-forward, generating that commit's message. Human mode prints the message
on the rail before collapsing; JSON callers find it in the captured merge
stderr diagnostic, not in result. A topic that is already one
commit is left alone. This needs merge.generation.command, or
commit.generation.command as a fallback: a multi-commit topic with neither
is refused in preflight (merge.squash_generator_missing) rather than merged
unsquashed. A generator set in committed .pando.yaml is untrusted until
pando trust merge-approve; until then JSON answers
merge.squash_approval_required. Turn it off with --no-squash or
merge.squash: false.
Source: README.md ("Lifecycle commands" / "Squashing")
Inspect the JSON request/response schema and schema version
The generated schemas express the version 1 wire exactly: request and response
schema_version accept only the integer 1, and response status accepts only
"success" or "error".
Source: README.md ("Structured (JSON) usage")
