Zentty Docs

Reference

A compact reference for Zentty environment variables, config files, status phases, interaction kinds, and local data paths.

Applies to current public Zentty builds. Last updated May 11, 2026.

Look-up tables for environment variables, status events, phases, interaction kinds, files, config keys, and debugging paths.

Pane Environment

Variable	Meaning	Lifecycle
`ZENTTY_CLI_BIN`	Absolute path to the bundled zentty CLI.	Set in every Zentty pane.
`ZENTTY_AGENT_EVENT_COMMAND`	Convenience command for canonical agent lifecycle events.	Set in panes and generated hook environments.
`ZENTTY_INSTANCE_SOCKET`	Socket path for the running Zentty instance.	Set in every pane; required for IPC.
`ZENTTY_INSTANCE_ID`	Instance identifier used to scope notifications and tmux wait-for signals.	Set in every pane.
`ZENTTY_WINDOW_ID`	Opaque window identifier.	Set in panes and by select pane exports.
`ZENTTY_WORKLANE_ID`	Opaque worklane identifier.	Set in panes and by select pane exports.
`ZENTTY_PANE_ID`	Opaque pane identifier.	Set in panes and by select pane exports.
`ZENTTY_PANE_TOKEN`	Pane-scoped auth token for IPC operations.	Set in panes; exported only when requested for out-of-pane control.
`ZENTTY_CURSOR_HOOKS_DISABLED`	Opt out of Cursor hook integration for a launch.	Read before wrapper/hook setup.
`ZENTTY_KIMI_HOOKS_DISABLED`	Opt out of Kimi hook integration for a launch.	Read before wrapper/hook setup.
`ZENTTY_TMUX_COMPAT_TRACE_PATH`	Writable JSONL trace path for tmux compatibility debugging.	Read by the tmux shim and IPC handler.

Agent Status Events

Event	Meaning	Payload	Notes
`session.start`	Attach a tool session to the pane.	version, event, agent, state, task as applicable.	Usually carries tool name, pid, session id, and working directory.
`session.end`	Clear the tracked session for the pane.	version, event, agent, state, task as applicable.
`agent.running`	Mark the agent as actively working.	version, event, agent, state, task as applicable.	Used for prompt submit, before-tool, progress, and shell-running signals.
`agent.idle`	Mark the turn complete while keeping the session visible.	version, event, agent, state, task as applicable.
`agent.needs-input`	Show human attention state.	version, event, agent, state, task as applicable.	Includes approval, question, decision, auth, or generic-input.
`agent.input-resolved`	Clear the outstanding interaction and return to running.	version, event, agent, state, task as applicable.
`task.progress`	Update done/total task counts for sidebar progress.	version, event, agent, state, task as applicable.

{
  "version": 1,
  "event": "agent.needs-input",
  "agent": { "name": "Claude Code", "sessionId": "..." },
  "state": {
    "phase": "needs-input",
    "interaction": { "kind": "approval", "text": "Approve edit?" }
  }
}

Agent Status Phases

Phase	Meaning
`starting`	Session is initializing.
`running`	Agent is actively working.
`needs-input`	Agent is waiting for human action.
`idle`	Turn is complete and the agent is waiting.
`unresolved-stop`	Internal derived state for a process that died while active.

starting -> running
running -> needs-input -> running
running -> idle
running -> unresolved-stop
idle -> running
any phase -> session.end

Interaction Kinds

Kind	Sidebar Meaning
`approval`	Requires a yes/no or allow/deny action for a proposed operation.
`question`	Asks for free-form text or clarification.
`decision`	Asks the user to choose among known options.
`auth`	Needs sign-in.
`generic-input`	Needs input.

Visibility Windows

Status	Window	Reason For Retention
Idle	About 2 minutes	Shows that a turn finished recently.
Unresolved stop	About 10 minutes	Gives the user time to notice a process died mid-turn.
Stale no-process status	About 30 minutes	Removes badges that no longer map to live work.

Config Keys

Key	Meaning	Default	Valid Values
`[sidebar].width`	Sidebar width in points.	280	Positive number.
`[sidebar].visibility`	Initial sidebar state.	pinnedOpen	pinnedOpen, pinnedClosed, overlay.
`[pane_layout].laptop`	Pane layout preset for laptop-sized windows.	compact	compact, balanced, spacious.
`[pane_layout].large_display`	Pane layout preset for large displays.	balanced	compact, balanced, spacious.
`[pane_layout].ultrawide`	Pane layout preset for ultrawide displays.	balanced	compact, balanced, spacious.
`[pane_layout].right_split_behavior`	How right splits are placed when width is tight.	adaptive	adaptive, alwaysVisible, appendScrollable.
`[pane_layout].visible_split_window_width`	Minimum window width used for visible right splits.	1200	Positive number.
`[panes].show_labels`	Show pane labels.	true	true, false.
`[panes].inactive_opacity`	Inactive pane opacity.	0.84	0.6 through 1.0.
`[appearance].local_theme_name`	Ghostty theme name selected for Zentty.	Zentty default	Any resolved Ghostty theme name.
`[appearance].local_background_opacity`	Terminal background opacity override.	1.0	0.0 through 1.0.
`[appearance].sync_opencode_theme_with_terminal`	Keep OpenCode's theme aligned with the terminal theme.	false	true, false.
`[open_with].primary_target_id`	Default Open With target id.	finder	Built-in or custom target id.
`[open_with].enabled_target_ids`	Ordered list of enabled Open With targets.	finder, vscode, cursor, xcode	Array of target ids.
`[[open_with.custom_apps]]`	Custom app id, name, and path entries.	[]	id, name, path.
`[[shortcuts.bindings]]`	Command id plus shortcut storage string; an empty shortcut clears a binding.	Built-in defaults.	Command id plus macOS shortcut string.
`[updates].channel`	Update channel.	stable	stable, beta.
`[restore].restore_workspace_on_launch`	Restore windows, worklanes, panes, and supported agent context on launch.	true	true, false.
`[agent_teams].enabled`	Enable the tmux shim for compatible multi-agent workflows.	false	true, false.
`[agent_caffeination].enabled`	Keep the machine awake while tracked agents are active.	false	true, false.

Local Files

~/.config/zentty/config.toml: app settings.
~/.config/zentty/bookmarks.json: saved bookmarks and workspace templates.
~/.config/ghostty/themes: user Ghostty themes Zentty can resolve.
~/Library/Application Support/zentty: app support data and local runtime state.
~/Library/Logs/zentty: diagnostic logs when logging is enabled by the app build.
~/Library/Logs/DiagnosticReports: macOS crash reports for Zentty.
Cursor and Kimi hook configs: tool-specific user configuration areas touched by zentty install cursor-hooks and zentty install kimi-hooks.
~/Library/Caches/zentty/ghostty-src/zig-out/share/ghostty: Ghostty resources staged by the development bootstrap script.

Debugging And Logs

Capture the exact command, pane id, and time of the issue.
Check ~/Library/Logs/DiagnosticReports for crashes.
For tmux compatibility, set ZENTTY_TMUX_COMPAT_TRACE_PATH to a writable JSONL file and reproduce.
For agent hooks, include the adapter name and sanitized payload shape; never include pane tokens.

Glossary

WorklaneA durable context containing horizontally arranged columns.

ColumnA vertical stack of one or more panes.

PaneA terminal session with working directory, title, scrollback, and optional agent state.

Leader paneThe pane that launches an Agent Teams workflow.

Team columnThe column where tmux-shim subagent panes stack.

AdapterTool-specific bridge that normalizes hook payloads.

HookA local command an agent invokes on lifecycle, prompt, tool, or notification events.

Status protocolThe small JSON vocabulary Zentty uses for session and agent status.

Pane tokenPane-scoped local IPC authorization token.

Sticky stateStatus retained briefly after a process stops so the user can notice it.