# Using pando The user guide. Settings: [06-config.md](06-config.md); keys: [09-keys.md](09-keys.md). - [Projects, worktrees, sessions](#projects-worktrees-sessions) - [The screen](#the-screen) - [Sessions](#sessions) - [Resume](#resume) - [Review and commit](#review-and-commit) - [GitHub](#github) - [Databases](#databases) - [Customizations](#customizations) - [Usage](#usage) - [Editor](#editor) - [Settings, keys, updates](#settings-keys-updates) - [CLI](#cli) - [Instances](#instances) - [Files](#files) ## Projects, worktrees, sessions Sessions (`3`) is a tree: projects you added, their worktrees, and the sessions in each worktree. ```text app project: pando ~/code/app, or `a` in Sessions ├─ ⌂ main its own checkout │ ├─ ○ shell session: idle │ └─ ◐ claude session: working └─ ⑂ feat-login linked worktree, `w` └─ × claude session: waits for you ``` A project whose only worktree is its own checkout shows it on its line, `app ⌂ main`, its sessions right under it; a click on the branch switches to it. An idle session says how long it has been idle (`3h`). On top are only the projects where something is awake, and the one on screen. The rest wait at the bottom, the three used last under a dim _recent_ caption, the others A–Z under _other projects_: folded, all asleep (`◌` and a count; the chevron opens one in place), or with no session (a dimmed name: a click switches to it, `n` starts a session in it). A project goes back on top, at its place, once a session in it wakes. Scrolled down, the project of the top row stays on the first line. A worktree with two sessions or more has a split button on hover: its sessions open side by side, a group each. | Key | In Sessions | | -------- | ------------------------------------------------------------------------- | | `a` | add a project from the folder picker: places, folders, a path | | `w` | add a worktree to the selected project | | `n` | start an agent or a terminal in the worktree, or a row's `+` | | `x` | kill a session, delete a worktree or close a project; a row's `✕` too | | `/` | find a project or session by words, accents optional; `⏎` opens it | | `o` | filter, sort and group the list | | `alt+↑↓` | reorder sessions and worktrees | A session runs an agent: the picker lists the installed `[agents]` presets (claude, codex, gemini, agy, grok, opencode, …), then _terminal_, a plain shell. An agent with profiles asks which one next: _default_, the `[profiles]` in `config.toml`, then every config pando saw it run in or found: a directory with a sign-in of another account, up to three deep under the home directory (gemini's two) outside dependencies, caches and your own folders (`Documents`, `Downloads`, `go`, …), or one a running program has in the agent's variable (on Linux, and not under the temporary directory). An agent is looked for while it is installed and has a preset in `[agents]`, which copilot has only once you add it: | Agent | Variable | Account file | | ------- | ------------------- | ------------------------------ | | claude | `CLAUDE_CONFIG_DIR` | `.claude.json` | | codex | `CODEX_HOME` | `auth.json` | | grok | `GROK_HOME` | `auth.json` | | copilot | `COPILOT_HOME` | `config.json` | | gemini | `GEMINI_CLI_HOME` | `.gemini/google_accounts.json` | Each says how much of its plan is used ([Usage](#usage)). ```toml [profiles.claude] work = ["CLAUDE_CONFIG_DIR=~/.claude-work"] [profiles.codex] client = ["CODEX_HOME=~/codex-client"] ``` A project's `+` asks for one of its worktrees, or a new one, first. The agent exiting closes its session; a failure stays listed as `exit N`. Deleting a worktree keeps its branch; closing a project never removes its checkout. ## The screen ```text ┌────────┬────────────────┬──────────────────────┬──────────────────┐ │ SPACES │ Files Git ⌕ │ main.go │ notes.md │ claude │ │ ▾ app │ ▾ src │ │ │ │ ⌂ main│ main.go M │ editor or diff │ session │ │ ◐ fix│ │ │ (its own PTY) │ │ ⑂ feat│ ├──────────────────────┴──────────────────┤ │ × ui │ │ Terminal panel │ ├────────┴────────────────┴─────────────────────────────────────────┤ │ status bar: branch, sync, agents waiting, updates │ └───────────────────────────────────────────────────────────────────┘ ``` - `ctrl+]` cycles focus, through each editor group too; inside a session every other key goes to its program. - `1`–`4` and `6` open Explorer, Source Control, Sessions, Search and GitHub. - ``ctrl+` ``, `ctrl+j` or `5` toggles the bottom panel; `ctrl+shift+↑` maximizes it. Its tabs: Terminal (`+` a new shell, the select beside it picks one or kills it), Problems (`ctrl+shift+m`) and Output (`ctrl+shift+u`: the language servers' logs and every error in full). - Editor groups, as VS Code's: drag a file's or a session's tab to a group's edge to split it there, onto its middle or tab strip to move the tab in. With two groups or more side by side, the very bottom of the editor area's middle puts it in a new row under them all. A file dragged from Explorer, or a session of the worktree in view from Sessions, goes the same way. `ctrl+\` moves the active tab into a new group on the right; the palette moves it into the group left, right, above or below. `ctrl+1`…`ctrl+9` focus group N, the button at the right end of a group's tab strip maximizes it. Adding or closing a group shares the room out evenly again; a double click on a divider evens the two groups beside it. In a split the focused group's frame is drawn in the accent's shade; a group whose session waits for you or failed is framed red, one that finished in the attention color, pulsing until you focus it. A group left empty closes; one showing nothing closes with `ctrl+w` or `ctrl+d`. Each worktree keeps its groups, a restart too. - Drag a view's tab to move it, a divider to resize. A second click on the open view's icon hides its sidebar; `ctrl+b` hides both. - Drag any tab of the bottom panel to a sidebar's tabs and the whole panel moves there, or to the sidebar's outer half for a column of its own; its tab dragged to the bottom of the editor brings it back. Nothing else goes there. Closed in a sidebar it keeps its tab, which opens it. - Rest the pointer on an icon button for its name and key, or on a session whose name is cut for the whole of it (Settings' _Tooltips_ turns that off). A view's header buttons show for a few seconds after the pointer moves over the view. ## Sessions - A session opens as a tab in the focused editor group, beside your files' tabs, or shows the group that has it already. Drag its tab to a group's edge to put it beside a file, or along the strip to put it between files' tabs (`ctrl+shift+pgup`/`pgdn` too). Its ✕ hides it; it keeps running. A session on screen keeps its tab when you switch to another or open a file, also one a worktree switch or a restart brought back. - The `+` after a group's last tab, or `alt+n`, opens a file (as `ctrl+p`), one of the space's sessions, a new session, or a resumed one; `alt+s` goes straight to a new session. The empty editor area has the `+` too, and lists which keys work from anywhere and which need it focused; a double click on the strip past the tabs brings it up with tabs open. - A session re-roots Explorer and Source Control to its worktree; Explorer selects the file its editor shows and comes to the front of its column (`auto_reveal`), as for any file or change opened, or tab picked. A file opened from Search or Source Control sharing Explorer's column leaves that view in front. - Each session is one tab; the sessions of a worktree share its Terminal panel's shells, which outlive them. `alt+t` picks a session (quick open's Sessions tab, the Sessions tree with every project open), `alt+a` goes to the next one waiting on you. An agent started in a shell, claude typed at its prompt, shows its state on the tab. - Drag over a terminal to select and copy; `ctrl+f` finds in its scrollback. - Ctrl+click a link in a terminal, as in VS Code's: a URL or an OSC 8 hyperlink opens in the browser, a path (`app.go:12:5`, `app.ts(12,5)`, Python's `"x.py", line 12`) in the editor at that line. A relative path starts from the directory of the program in front (on Linux), else from the worktree; one found in neither (`go test`'s `x_test.go:42`, `rg -l`'s `ui/app.go`) opens the one file whose path ends in it, else quick open lists them. The pointer over a link underlines it. - The subagents a claude, codex, agy or grok session runs list under its row in Sessions while they work: their kind (codex: the name it gave the agent) and what they do. They live inside the session; a click on one opens the session. The pointer over one, or over its session, shows the model and effort it runs on: a claude, codex, grok, copilot, agy or gemini session, and the subagents of the first three. - `alt+i` picks a saved prompt, a file in `~/.config/pando/prompts/`, by words of its name or text (a name match first): `⏎` types it into the session in view, or the panel's shell when it has the keyboard, as one paste and leaves Enter to you, `alt+⏎` submits it too. The one used last comes first; `+ New Prompt…` names a new one and opens it in the editor, `ctrl+e` edits, `shift+del` deletes. - `p` in Sessions, the `⊙` left of a session's row or its right-click menu pins it: Sessions lists it in the Pinned pane on top, and in its tree as before. `p` or the menu on a project pins it whole: its worktrees and every session in them, new ones too, asleep or not. | Mark | State | Means | | ---- | --------- | --------------------------------------------------------- | | `×` | `blocked` | waits for you: a permission or a question | | `◐` | `running` | works; it turns while it does | | `◐` | `shell` | at its prompt, a shell command running under it (blue) | | `✓` | `done` | finished, not looked at yet | | `○` | `idle` | at its prompt | | `◌` | `asleep` | stopped to free memory; opening it brings it back | | `✕` | `exited` | failed (`exit N`); a clean exit closes the session | One needing you pulses until clicked (`session_highlight`) and can play a sound (`sounds`). ![three claude sessions, each in a worktree of its own, come to life; one finishes (✓), one waits for a yes (×, pulsing), and the finished one's diff is reviewed and committed without leaving pando](demo/tui.gif) ## Resume After a daemon restart pando types into each session's shell what resumes its agent: `claude --resume` with its conversation id (`claude --continue` without one), `codex resume --last`, `opencode --continue`. Others take one line: ```toml [resume] aider = ["aider", "--restore-chat-history"] ``` - A conversation still open elsewhere is not opened twice. - A custom config dir (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`) comes back with it. - Scrollback is not kept, and what ran in the terminal stops, subagents included. `pando claude` starts claude as a Claude Code background session, which outlives the restart; with `claude_background` (the default) every resumed claude comes back that way. - By hand: _Resume_ in Sessions (a worktree's row under the pointer, its menu, or `↺` in the header) lists that worktree's claude conversations (`claude --resume`); an agent without such a list continues its last. Esc in the list closes the session. ![a claude conversation, pando closed and its daemon stopped; the next pando brings the session back and claude continues the same conversation](demo/resume.gif) ## Sleep An unused session can stop to free its memory: a claude takes 300–600 MB, its background job and its `claude attach` together. - `z` in Sessions, or _Sleep Session_ in a session's menu, puts it to sleep; working, it asks first. `pando session sleep ID` too. - After an hour it happens on its own to an agent's session idle and unused that long: nobody typed into it, looked at it or saw it change. Blocked, working, a background command running, finished but not looked at yet (`✓`), or running something pando would not bring back, it stays awake, and so does a plain shell. A timer inside the agent (`/loop`) does not hold it: set `sleep_after` above its interval. `sleep_after` in `config.toml`, or _Settings → Sessions_, sets the minutes; `0` turns it off. - Asleep (`◌`), its screen stays, its process and a claude's background job are stopped. A daemon restart leaves it asleep. A Terminal panel's shell goes with it, idle at its prompt with no job behind it. - Opening it, or a key typed into it, wakes it: the conversation is resumed as after a restart. A shell wakes to a new shell; a server or an editor that ran in it does not come back. - codex (`resume --last`) and opencode (`--continue`) continue the latest conversation in the worktree: two of one in the same worktree can swap. gemini, agy and grok, with nothing in `[resume]`, are not put to sleep. ## Review and commit Source Control (`2`) follows VS Code: Merge / Staged / Changes / Untracked, a message box, and drawers for the graph, commits, file history, branches, worktrees, remotes, stashes and tags. A commit in a drawer shows its whole message when the mouse rests on it; right click copies it. The header's Collapse All button closes the drawers with the tree. The drawers sit under a Tools strip: a click on it folds them into it, and another brings them back as they were. With the mouse over the drawers, ⊟ on the strip closes only the drawers. ⏎ on a commit lists the files it changed in the Compare drawer, read-only, as GitLens does; ⏎ on a file opens its diff. A commit's right-click menu compares it with HEAD, with the working tree, or with a commit picked by _Select for Compare_; _Open Changed Files_ on a pull request in GitHub does the same for the pull request. The empty drawer, or its header's right-click menu, compares the branch with a branch or tag picked from a list, or with any revision typed into it, as GitLens' _Compare with_ does. The ✕ on the drawer's header clears it. Each project keeps its own comparison. A diff shows the changes with three lines around them and the rest as `N hidden lines` rows: ⏎ on one or a click shows those lines in place, and they stay shown while the tab is open; find (`ctrl+f`) looks in them too and unfolds the one with the match. `z` (or the header's fold button) shows a file's whole diff, for every file until toggled back. `]` and `[` (VS Code's `alt+F5`, `shift+alt+F5`, or the header's `↓` `↑`) go to the next and previous change, `}` and `{` to the next and previous file: of a commit, or of Source Control from a file's diff; a file's diff opens on its first change. The scrollbar marks every change: green added, red deleted, yellow changed lines (blue on the light theme); a click on a mark goes there, again to the next one in the same cell. | Key | In Source Control | | --------- | ---------------------------------------------------------- | | `⏎` | stage or unstage the file; `o` opens its diff | | `a` / `u` | stage / unstage all; `U` stages the untracked | | `d` | discard the file, folder or section, after asking | | `c` | focus the message box; `A` has an agent write the message | | `↑` / `↓` | in the message box: older / newer commit messages | | `C` | commit | | `S` | sync, or publish a branch with no upstream | In a diff, `s` switches inline and side by side, and selected lines stage, unstage or revert (`m`). Side by side, a click picks the half the cursor moves on, and a copy holds that half's lines only. The commit button turns into _Continue_ during a merge, rebase or cherry-pick. ![a diff inline and side by side, staging part of it, then a conflicting merge continued with git's message](demo/diff.gif) ## GitHub Shown when `gh` is on the `PATH` (`6`): Pull Requests with their checks, Issues and unread Notifications for the repository `gh` picks. | Key | Does | | --- | ---------------------------------------------------------------- | | `⏎` | renders a pull request or issue; opens a notification, read | | `d` | a pull request's changes, `gh pr diff` | | `w` | a worktree for the pull request, or `issue/-…` for an issue | | `o` | opens github.com; `y` copies the link | | `x` | marks a notification done | Merge is in the `m` menu and merges only the head the list showed. An opened pull request or issue has its state and buttons in the header row, at the right end where VS Code puts an editor's actions: `● Open` (or Draft, Closed, Merged), `✓ 2/2` checks, then buttons. One is first and has its name and a `▾`, by state: Ready for Review for a draft, Merge while no check is in its way, else Worktree, Reopen for a closed one. The `▾` lists Worktree, Changes, Changed Files, Merge and Convert to Draft. The rest are icons: Worktree, Changes, Comment, Close, `↻` fetches again and `⋯` is the `m` menu. Rest the pointer on one for its name and key. Click one, or press its key while the page has focus: | Key | Does | | -------- | ----------------------------------------------------------------- | | `w` `d` | worktree, changes | | `M` `R` | merge, mark a draft ready for review | | `c` | puts the cursor in the comment box at the end of the page | | `x` | closes an open pull request or issue, reopens a closed one | | `ctrl+r` | fetches the page again; every action does it when gh has answered | Everything that changes the page asks first: merge (which says when its checks are failing or still running), close, reopen, ready for review and back to a draft. The title and the people are prompts, which the ⏎ confirms; a comment is sent by its own button or `ctrl+s`. At the end of the page is the box GitHub's has: Leave a comment, with Comment and Close (or Reopen) under it. `c`, a click in it or Quote Reply puts the cursor in it; ⏎ is a new line, `ctrl+s` sends, `esc` leaves the box with its text, which stays there even when the page is closed and opened again. Close with text in the box sends it as the comment of the close. Reviewers, assignees, labels and the title are in the `m` menu: a prompt with the current values, comma separated, that sends only what changed. Under the header the page is laid out as GitHub's is: the description and each comment in a box with its author and time across the top, the commits, review requests and other events as rows on a vertical rail, a review with what it said and the threads it started on a file under it. Every box has the same frame; one that tags you (`@login`, as `gh` knows you) has a yellow one and says "mentions you" in its header. In a panel 110 cells wide or more (the sidebars hidden with `ctrl+b`, or a wide terminal) the reviewers, assignees, labels and checks stand in a column beside it, each with a gear that edits it; in a narrower one they are rows above. | Click or `⏎` on | Does | | --------------- | -------------------------------------------- | | a commit | shows it, fetching the head first if needed | | a box's header | folds the comment, again unfolds it | | the `⋯` of one | Quote Reply, Fold, Open on GitHub, Copy Link | | a gear | the prompt of its section | What was fetched stays in memory: a page or a diff seen in the last five minutes shows at once without asking GitHub, an older one is fetched again behind it, and so is a list older than five minutes; `ctrl+r` or any action fetches at once. A page shown from memory says how old it is beside Refresh. ![pull requests with their checks, one opened as its rendered description and as a diff, then checked out in a worktree of its own](demo/github.gif) ## Databases Shown when `sqlite3`, `psql` or `mariadb` (or `mysql`) is on the `PATH` (`7`): the SQLite files of the worktree, ignored ones too, the server its `.env`'s `DATABASE_URL` names, and the servers you name in config.toml, each unfolding to its tables and views. Opening a `.db` in Explorer or quick open shows it there. ```toml [databases] local = "postgres://app@localhost:5432/app" shop = "mariadb://root@127.0.0.1:3306/shop" ``` `n` (or `+` in the view's header) adds one in a form, as DataGrip's Data Source: type, host, port, user, password, database and options (`sslmode=require`); `ctrl+t` tests it, `⏎` saves it to `[databases]`. `e` edits one, `D` removes it. Save: Forever keeps the password in the system keyring (GNOME Keyring, KWallet, macOS Keychain), Until restart only while pando runs; the form never writes one into config.toml, and one you wrote into a URL yourself stays there. Without one, a password in `~/.pgpass` or `~/.my.cnf` works too, and pando asks when the server wants one. `t` opens the client itself (`psql`, `mariadb`, `sqlite3`) in the Terminal panel, for any other SQL. A table opens in an editor tab as a grid, 200 rows a page, `[` `]` for the next ones. Type SQL into WHERE (`ctrl+f`) and ORDER BY (`tab`) and press `⏎`; `s` or a click on a column's header sorts by it. A server table of more than 100 000 rows shows the server's estimate, `~N`, until Count Rows counts them; `esc` stops a slow read. The status bar names the cursor's column and type. MariaDB timestamps show in UTC. | Key | Does | | ---------------- | --------------------------------------------------------- | | `⏎` | edits the cell; a long or multi-line one in an editor tab | | `o` `ctrl+d` `d` | adds, duplicates, deletes a row | | `u` | reverts the cell, else a deletion or an added row | | `ctrl+s` | submits every edit in one transaction | | `m` | Set NULL, Revert All, Show Pending SQL, Open Console | `shift+↑` `shift+↓` select rows: `d`, `u`, `y` (as TSV) and Set NULL then take them all. Edits wait, marked `M`, `A` or `D`, until `ctrl+s` writes them all or none. A cell someone changed since the page was read stops the submit (a Postgres table without a primary key: any change to its row), and so does a row gone; `u` reverts the edit and `r` reads the row as it is now. A view, a generated column and a blob are read only. ![a SQLite table sorted, filtered and edited in a grid, the pending SQL submitted in one transaction, then sqlite3 in the terminal and the form that adds a server](demo/databases.gif) ## Customizations A tab beside Sessions, in its header (`8`), when `claude`, `codex`, `grok` or `agy` is installed: what that agent loads in this worktree, its Skills and Instructions, and for `claude` its Agents, Hooks, MCP Servers and Plugins too. A section says `user` or `workspace` when all its entries are in one, and splits under both otherwise. `⏎` opens the file, on its line in a shared one such as `settings.json`. The list follows the session's agent. The top row or `a` picks another, which stands until you switch sessions; a shell session keeps the last one. pando only reads here: change an entry in its file, or ask the agent to. The list comes from the files alone. It does not start the agent, so it shows no live MCP status, no claude.ai connectors and no skills that a plugin or the agent itself brings. A file that does not parse and a skill linking to nothing show a warning. ## Usage A tab beside Sessions (`9`) while `usage` is on and `claude`, `codex`, `agy`, `copilot` or `grok` is installed: each sign-in's plan and a row per limit window, how much of it is used and when it resets. A model's own allowance on the window is a cell of the meter colored as its own share is, named in the row's tip, and at the row's end once it is at 75% (`Fable 93%`). A limit of some models only, with no window of every model's to mark, takes a row named after them: agy's `Gemini 5h` and `Claude + GPT 5h`, copilot's `chat 1mo` on the free plan. An agent has a sign-in per config: _default_, each of its `[profiles]` that sets its config directory (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`), and every config pando found, by its directory without the agent's name: `~/.claude-work` is _work_. A profile that sets anything else runs on the default's sign-in and is not listed. | Key | Does | | --- | ---------------------------------------------------------------- | | `⏎` | new sessions of that agent start with this profile (_active_) | | `a` | `profile_switch`: `auto`, or from it back to `notify` | | `r` | ask again; the daemon asks every 15 minutes on its own | The active profile is the row a new session's profile picker opens on, and what `pando session new` starts an agent with. The picker's rows have a column per window, claude's `5h` and `7d` named in its top edge: each a meter, share and reset, a model's own allowance a cell of it and named at the row's end from 75%; the selected row's footer says what it runs where. The status bar names the active profile with its fullest limit, yellow from 75% and red from 90%. Once the active profile has used `profile_switch_at` percent of a limit (95), pando looks for the one with the most room. `notify` offers it in the status bar, one click to take it; `auto` makes it the active one; `off` does neither. Sessions already running stay on their profile either way. Under `auto` a profile over the limit that you pick by hand stands until the limits are next asked for: opening the Usage tab, `r`, the 15-minute check, or a change of `profile_switch` or `profile_switch_at`. A session running in a profile other than its agent's default says which, in Sessions before its status and in the terminal's title. _Move to Profile…_ in a session's menu moves a running claude session: the agent ends and continues the same conversation under the other profile, whose settings, skills and MCP servers it loads from then on. The transcript stays where it was written, linked into the other profile's `projects/`. A profile that has not seen the worktree asks once whether to trust it. A profile signed in to another organization cannot reuse the conversation's earlier thinking: claude says so, and its next answers are slower and use more tokens. `pando session profile ID NAME [--send TEXT]` does the same from a script, and submits TEXT once the agent is back at its prompt: how an agent moves itself and goes on with its work. The limits come from each agent's own service: claude's from the endpoint Claude Code's `/usage` reads, with the sign-in each profile keeps in `.credentials.json`, codex's from its own app-server, which renews its sign-in as codex does, agy's from Google's Cloud Code API with the sign-in agy keeps in the keyring, grok's from xAI's billing endpoint with `auth.json`'s key in `GROK_HOME`, copilot's from GitHub with `GH_TOKEN` or `gh`'s sign-in (Copilot's own is in the keyring, where pando does not look, so every copilot config shows gh's account). pando never renews a sign-in: one that lapsed shows its last limits as _paused_ until its agent runs again. On macOS Claude Code and agy keep their sign-ins in the Keychain, where pando does not look: they read _signed out_ there. ![the Usage tab with claude's default and work profiles and codex, a meter per limit window; the default near its weekly limit, work made the profile new sessions start with, then the profile picker with each one's room](demo/usage.gif) ## Editor - Undo, find & replace, quick open (`ctrl+p`, recent and changed files first, `:` line, `@` symbol, `>` commands; `tab` goes to Files, Sessions, the files' Text and Actions, `ctrl+t` a file's path, name or tree, `alt+⏎` on to Search), suggestions, merge-conflict _Accept_ actions. - The cursor's line is lit faintly across the editor, as VS Code's. - `ctrl+/` comments the line or the selection out, and a second time back in, in the language under the cursor (a `