Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Settings and Accessibility

Find PonyMux preferences, keep long-running work awake, manage updates, customize shortcuts, and understand the current accessibility support.

Open Settings with ⌘, or the gear button at the bottom of the sidebar. Settings are grouped by the kind of decision they affect rather than by individual Terminal.

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

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.
Settings App-wide preferences live together; per-Terminal choices stay with the Terminal they customize.

Settings at a glance

Pane What it controls
General Notifications, pets, reaction presets, and session behavior.
Appearance App-wide themes and Follow System mode.
Terminal Fonts, cursor, default screen effect, shell, and Terminal behavior.
Keyboard Review and customize PonyMux commands and shortcuts.
Integrations Connect or disconnect Claude Code and Codex.
Advanced Instance details, diagnostics, backups, and reset controls.

Settings that act as defaults—such as the default pet or screen effect—apply to new Terminals. Per-Terminal choices already made remain attached to those Terminals.

Terminal creation and directory tracking

In Settings → Terminal, New Terminal inherits working directory controls whether a new Terminal starts from the visible Terminal context or from your home folder. Default shell chooses the shell used for new regular and Quick Terminals.

Shell Integration lets PonyMux track the directory after commands such as cd, so the Terminal list, Inspector, and future Terminal creation use current information. See Create in context for the complete List assignment and starting-directory rules.

Keep long-running work awake

Select the coffee-cup Keep Awake button at the bottom of the sidebar when an agent, development server, or other long task should continue while the Mac is idle. While highlighted, PonyMux prevents App Nap and idle system sleep.

Keep Awake does not override closing the lid or choosing Sleep yourself. Turn it off when the long-running work is done so normal energy-saving behavior can resume.

Updates

PonyMux uses Sparkle to deliver signed private-preview updates. When automatic checks are enabled, it checks quietly while running and after the Mac wakes or PonyMux becomes active. A highlighted update button appears near the bottom of the sidebar when a newer version is available; select it to review and install.

To check manually, choose PonyMux → Check for Updates… from the menu bar.

Keyboard and VoiceOver

Common actions have keyboard shortcuts, and Settings → Keyboard lets you review or customize them. Interactive controls expose names and state to VoiceOver; Terminal rows announce their title, provider and status, collection, reaction, and lifecycle details when relevant.

Column dividers and the Quick Terminal height handle are adjustable with VoiceOver and the keyboard as well as by dragging. In Focus Mode, the normally auto-hiding toolbar stays visible while VoiceOver is running so its controls remain reachable.

The Terminal content area is exposed as a text area, but its current accessibility bridge exposes selected terminal text rather than the complete scrollback. The surrounding PonyMux interface remains navigable while terminal applications retain their own accessibility behavior and limitations.

Last updated on Sep 12, 2026