Create and Organize Terminals
Create durable Terminals in the right List and working directory, then use collections, reactions, Archive, and Trash to keep them easy to find.
If you have used a notes app such as Bear or Evernote, PonyMux’s organization should feel familiar. A Terminal behaves more like a durable note than a disposable tab: you can name it, place it in a List and Folder, mark it with a reaction, archive it, and restore it later. Commands, running tools, and agent sessions are the working content kept inside that organized place.
PonyMux keeps this system intentionally small. Lists and Folders organize active work, reactions add lightweight personal markers, and Archive and Trash handle work that is no longer active.
- model:
- gpt-5.6-sol low /model to change
- directory:
- ~/Works/ponymux-web
›Polish the product documentation and verify the visual examples.
I’ll update the workspace examples, check both themes, and run the site validation.
Read components/demo/AppShellDemo.astro
Edited components/demo/TerminalListDemo.astro(+6 −5)
Ran bun run check→ passed
•Working(4s • esc to interrupt)
Regular Terminals
Create a Terminal with + in the toolbar, File → New Terminal, or ⌘N.
It receives its own row, shell process, working-directory record, appearance, and
place for agent session history. New Terminals appear at the top of the current
Terminal order.
A regular Terminal is different from a Quick Terminal, which is a temporary supporting shell attached to another Terminal. Use a regular Terminal when work should be named, organized, revisited, or resumed later.
Collections
All Terminals
All Terminals is the complete ordered view of active Terminals. Its manual order is the shared order used when another collection projects the same Terminal rows.
Lists and Folders
A Terminal can belong to at most one List. Lists can sit at the top level or inside a Folder; Folders contain Lists rather than Terminals directly.
Create Lists with File → New List (⇧⌘N) and Folders with File → New Folder.
Both can use an SF Symbol, and the icon picker can search the complete symbol catalog
available on your version of macOS.
Drag Terminals to reorder them or move them between Lists. Hovering over a collapsed Folder during a drag opens it temporarily so you can reach a nested List.
Agents
Agents shows every active Terminal whose live process is Claude Code or Codex. It is a live projection of the global Terminal order, not a separate place that owns or reorders Terminals. When an agent exits, a selected row remains briefly so the selection does not jump unexpectedly.
The Agents collection is not a drop target.
Archive and Trash
Archive is for work you want out of the active workspace but may return to. Trash is the staging area before permanent deletion. See Terminal Lifecycle for restore and deletion behavior.
Create in context
Where you create a Terminal determines its initial List membership. Collections that do not own active Terminals send new work back to All Terminals.
| Where you are | Where the new Terminal goes |
|---|---|
| All Terminals | All Terminals, with no List assigned. |
| A List | The current List is assigned automatically. |
| A Folder | Folders contain Lists rather than Terminals; select one of its Lists first. |
| Agents | All Terminals, with no List assigned. PonyMux switches there to show it. |
| Archive or Trash | All Terminals as a new active Terminal. PonyMux switches there to show it. |
List assignment and starting directory are separate decisions. A List does not have a hidden project directory: creating in a List assigns the List, while the Terminals visible in that collection provide the directory context.
Choose the starting directory
With New Terminal inherits working directory enabled, PonyMux looks only at the collection currently on screen and uses the first available source in this order:
- The selected visible Terminal.
- The anchor Terminal when several rows are selected.
- The first visible Terminal, following the collection’s displayed order, whose saved directory still exists.
- Your home folder when the collection is empty or no visible row has a usable directory.
This keeps creation tied to what you can see rather than to whichever agent was most recently active in the background. Directories that no longer exist—for example, a removed Git worktree—are skipped instead of being reused.
Because a new row is inserted at the top, the everyday shorthand is simple: when nothing is selected, it usually starts in the directory of the first row that was already there.
Turn this behavior off in Settings → Terminal to start every new Terminal in
your home folder. Shell Integration lets PonyMux track directory changes made with
commands such as cd; without it, PonyMux may only have the last directory it was
able to record. See Settings and Accessibility.
Reactions
A reaction is a one-character marker on a Terminal row. Use the fixed symbols
✓, ✗, and ⏸ for lightweight workflow state, or use emoji to mark a
meaningful moment—a finished task, a hard-won fix, or something worth celebrating.
Adding a reaction plays a brief burst around the marker. Reactions do not run
automations or change Terminal lifecycle.
Customize the emoji choices from a Terminal’s Customize Presets… action or in Settings → General → Reactions. PonyMux keeps the three fixed symbols at the top and supports up to ten custom emoji presets.
Moving several Terminals
Use multi-selection in the Terminal list, then drag the selected rows together to a List, Archive, or Trash. From Archive or Trash, dragging to All Terminals or a List restores the selection.