| name | zentty-cli |
| description | Use when an agent is running inside Zentty or needs to discover panes, split or grid layouts, focus panes, launch nested coding agents, or notify the user through the Zentty CLI. |
Zentty CLI
Zentty injects a pane-aware CLI into sessions running inside the app. Use it to inspect the current terminal layout, control panes and worklanes, launch supported agents with Zentty status hooks, and notify the user when work needs attention.
Detect Zentty
Prefer the injected binary:
ZENTTY="${ZENTTY_CLI_BIN:-zentty}"
You are inside a controllable Zentty pane when these are set:
test -n "${ZENTTY_INSTANCE_SOCKET:-}" &&
test -n "${ZENTTY_WORKLANE_ID:-}" &&
test -n "${ZENTTY_PANE_ID:-}" &&
test -n "${ZENTTY_PANE_TOKEN:-}"
If they are missing, do not assume pane control works. Explain that the command must run from a Zentty pane, or use ordinary shell behavior.
Operating Rules
- Use
$ZENTTY_CLI_BIN when available; it points at the bundled CLI for the running Zentty app.
- Prefer
--json for discovery and parse IDs from JSON instead of scraping table output.
- Default to the current pane/worklane. Only target other panes with explicit selectors.
- Treat
ZENTTY_PANE_TOKEN and --include-control-token output as sensitive routing credentials. Do not print them unless needed for a concrete command.
- Use
zentty --help or zentty <command> --help when available before guessing at a subcommand.
- If a command fails with "Not running inside a Zentty instance" or "Not running inside a Zentty pane", stop and explain the missing Zentty context.
Discovery
"$ZENTTY" version
"$ZENTTY" list --json
"$ZENTTY" list panes --json
"$ZENTTY" list panes --worklane-id "$ZENTTY_WORKLANE_ID" --json
"$ZENTTY" select pane --pane-index 2 --shell
Use --include-control-token only when you need to control a pane from outside its own environment:
"$ZENTTY" list panes --worklane-id "$ZENTTY_WORKLANE_ID" --include-control-token --json
Layout And Pane Control
Common pane actions:
"$ZENTTY" split right
"$ZENTTY" split down --equal
"$ZENTTY" hsplit --ratio 70
"$ZENTTY" vsplit --pane-index 2
"$ZENTTY" pane focus 2
"$ZENTTY" pane focus left
"$ZENTTY" pane resize 60%
"$ZENTTY" pane zoom
"$ZENTTY" layout thirds
"$ZENTTY" layout reset
Create grids carefully; large grids create many live panes:
"$ZENTTY" grid 2x2
"$ZENTTY" grid 2x2 --new-only -- codex
"$ZENTTY" grid 2x3 --worklane-id new -- claude
Launch Agents Through Zentty
When starting a nested coding agent from inside Zentty, prefer the normal wrapped command if it is already on PATH in the Zentty pane. Zentty's wrapper adds status hooks and then execs the real tool.
Use the hidden launch command only when you explicitly need to force Zentty's bootstrap path:
"$ZENTTY" launch codex --model gpt-5
"$ZENTTY" launch claude --dangerously-skip-permissions
Supported launch tool names include amp, claude, codex, copilot, cursor, droid, gemini, kimi, opencode, pi, grok, agy, and hermes.
Notify The User
Use notifications for completion, blocked input, or handoff points that should bring the user back to the pane:
"$ZENTTY" notify --title "Tests finished" --subtitle "Review the result"
"$ZENTTY" notify --title "Approval needed" --body "The deploy command is waiting for confirmation"
Use --silent for low-priority updates and --no-inbox when the notification should not stay in Zentty's inbox.
Manual Hook Installs
Wrapped launches usually install or inject agent hooks automatically. Manual installs are for debugging, recovery, or globally persistent integrations:
"$ZENTTY" install cursor-hooks
"$ZENTTY" uninstall cursor-hooks
Check zentty install --help for the supported targets in the installed Zentty version.
