Getting Started

Download and install PonyMux, create your first durable Terminal, and learn the sidebar, Terminal list, workspace, and Inspector.

PonyMux requires macOS 14 or later and is distributed as a signed and notarized DMG.

Install the app

Download PonyMux for freeRequires macOS 14 or later

Open the DMG, move PonyMux to Applications, and launch it. The build is signed with Developer ID and notarized by Apple.

Create a Terminal

Click + above the Terminal list or choose File → New Terminal (⌘N). On a fresh install, the first Terminal starts with your configured shell in your home folder. Later Terminals use the collection and visible Terminal context you are working in: creating inside a List assigns that List, and PonyMux normally carries forward a relevant working directory.

See Create and Organize Terminals for the exact placement and directory rules.

Connect an agent

Open Agent Integrations from the link button at the bottom of the sidebar, then connect Claude Code and Codex. See Agent Integrations for details.

Start working

Run claude or codex as usual. PonyMux leaves their terminal interfaces unchanged while adding status, session history, notifications, and recovery around them.

Find your way around

The main window has a Finder-like toolbar and up to four working columns:

Polish launch documentationcodex· ponymux-web › tasks

Review release checklistclaude· ponymux › shipping

Refine theme tokenscodex· design-system › components

Triage onboarding feedbackclaude· ponymux-web › tasks

Benchmark startup timecodex· playground › experiments

Archive migration noteszsh· ponymux › etc

OpenAI Codex(v0.132.0)

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)

gpt-5.6-sol low·~/Works/ponymux-web

Sessions

Sep 7

Polish launch documentation

Refresh the product story and make the workspace easier to understand.

Codex · just now

New Quick Terminal

WORKING DIRECTORY

LIST

PET

Appears when a session starts.

AGENT INTEGRATIONS

Claude Code2 active · last event just now

Codex1 active · last event just now

Notifications

Permission requestsAn agent is blocked and waiting for you to allow something.

Finished turnsAn agent stopped and is ready for your input.

Agent errorsAn agent stopped because something went wrong.

Pets

Show a pet for every live sessionA pet walks the window title bar for each running agent. Click one to jump to its Terminal.

Mochi

Sessions

Resume sessions on launchEach Terminal whose agent was still running resumes its session when you open it.

Permission level for resumed sessionsWhat the agent can do when a session resumes or forks.

Ask before quitting with live agentsShow a confirmation before quitting when agents are still running.

THEMES

Follow SystemautoAuto

~/ponymux ❯ claude
● Reading Settings.swift
bold normal dim err warn

Font

FontWhich monospace font the Terminal uses.

Font sizePoint size for Terminal text.

Font for Chinese and Japanese charactersKeep shared characters consistent on the same line.

Cursor

Cursor shapeHow the cursor looks in the Terminal.

Cursor blinkWhether the cursor blinks when idle.

Screen Effect

Effect for new TerminalsCursor animation for new Terminals; change it per Terminal later.

Behavior

Let sessions name TerminalsUse the session topic and update it as the conversation moves.

Copy on selectSelecting Terminal text puts it on the clipboard.

New Terminal inherits working directoryOpen in the same folder as the Terminal you are viewing.

Shell

Default shellWhich shell new Terminals start with.

Shell integrationLet PonyMux track each shell’s working directory.

Window

New Terminal

Quick Terminal

Focus Mode

Navigation

Back

Forward

Terminal

Rename Terminal

Archive Terminal

Show Inspector

Reserved by the terminal

Copy, paste, select all, clear, font size, scrollback, line editingThese shortcuts go to the shell and agent, not PonyMux.

Claude Code

ConnectedAgent status and session history are tracked.

Config file~/.claude/settings.json

Forwarder script~/Library/Application Support/PonyMux/claude-hook

Codex

ConnectedAgent status and session history are tracked.

Config file~/.codex/config.toml

Forwarder script~/Library/Application Support/PonyMux/codex-notify

PonyMux only adds or removes its own entries in the config file, and backs it up first.

This copy of PonyMux

PonyMuxdev.ponymux.app

Session data~/Library/Application Support/PonyMux

Event socket~/Library/Application Support/PonyMux/events.sock

Diagnostics

Debug LogLive view of PonyMux activity, filtered by area.

Log fileInfo and error entries kept on disk, so they survive a restart.

Reset

Reset all settingsYour Terminals, sessions, theme and agent connections stay.

PonyMux Workspace The complete workspace: navigation, one Terminal in focus, Sessions, Quick Terminal, and the Inspector.

The sidebar contains All Terminals, Agents, Archive, Trash, and your Lists and Folders.
The Terminal list shows the current collection and the state of each Terminal.
The workspace shows one full Terminal at a time.
The optional Inspector shows the selected Terminal’s agent, session, directory, and related actions.

The Sessions panel opens over the workspace or stays pinned as another column. It groups the selected Terminal’s current and previous agent conversations and offers Resume and Fork when the underlying transcript is still available.

A Quick Terminal opens a temporary shell beside the current Terminal. It is useful for supporting tasks such as starting the project’s local development server, watching logs, or running a quick Git check without adding another saved Terminal to your workspace. Create a regular Terminal when the work should have its own durable place, List membership, and session history.

See Workspace and Navigation for Focus Mode, the Inspector, Sessions, and browser-style Back and Forward history.

Useful first shortcuts

Action	Shortcut
New Terminal	`⌘N`
New Quick Terminal	`⌥⌘N`
Toggle Quick Terminal	`⌥⌘J`
Toggle sidebar	`⌘B`
Toggle Inspector	`⌥⌘B`
Toggle Sessions	`⌥⌘V`
Focus Mode	`⇧⌘F`
Back / Forward	`⌘[` / `⌘]`
Keyboard Shortcuts	`⌘/`

Shortcuts can be reviewed and customized in Settings → Keyboard.

Updates

PonyMux checks for updates in the background. When a newer private-preview build is available, an update button appears near the bottom of the sidebar. Select it to review the release notes and install the update through Sparkle. See Settings and Accessibility for manual update checks and other app-level controls.