Zentty Docs
FAQ
Common Zentty docs questions about install, panes, agents, restore, settings, and tmux compatibility.
Applies to current public Zentty builds. Last updated May 11, 2026.
Install
Does Zentty install agent CLIs?No. Install Claude, Codex, Gemini, OpenCode, Pi, Cursor, Kimi, Droid, or Copilot separately, then launch them from inside a Zentty pane.
Why does
zentty work inside Zentty but not Terminal.app?The bundled CLI path is injected into Zentty panes. Outside the app, create your own alias or symlink.Can I use Homebrew?Not yet. We are waiting for Zentty to reach 75 GitHub stars before submitting a Homebrew cask PR. For now, install the signed DMG. If you like Zentty, star it on GitHub.
Agents
Why does my agent not show status?Start it from a fresh Zentty pane and confirm hook opt-out variables are not set.
Can I use an unsupported CLI?Yes. Wrap it and emit Agent Status Protocol JSON with
zentty ipc agent-event.Are hooks safe?Hooks are local shell commands. Only install hooks you trust and never expose pane tokens in shared logs.
Panes
How are panes different from tabs?A pane is a shell. A worklane is the durable context that groups panes and columns.
Why did a right split become scrollable?Zentty keeps the focused pane readable when the window is too narrow for another visible column.
Do shortcuts pass through to vim or tmux?App-level Cmd shortcuts are handled by Zentty first; rebind them when nested tools need the key.
Restore
What gets restored?Windows, worklanes, panes, columns, working directories, labels, colors, and supported agent resume metadata.
What is skipped?Empty panes, short-lived shells, missing directories, and unsupported agent internal state.
How do I undo a closed pane?Press Shift+Cmd+T when Zentty captured enough close context.
Settings
Where is config?
~/.config/zentty/config.toml.Can I sync settings?Yes, but avoid syncing machine-specific app paths unless they exist on every Mac.
Where are bookmarks?
~/.config/zentty/bookmarks.json.tmux
Does Zentty replace tmux?No. The shim only handles the subset needed by compatible agent workflows.
Can I still run real tmux?Yes. Run it inside a pane or make sure your real tmux appears earlier on PATH.
How do I debug the shim?Set
ZENTTY_TMUX_COMPAT_TRACE_PATH to a writable JSONL file.