/zentty-cli

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.