Agent Workflows

Supported Tools

Zentty wraps supported tool launches so agent hooks and environment variables point back to the current pane. When a tool is active, the sidebar can show starting, running, needs-input, idle, task progress, and unresolved-stop states.

Choose Your Agent

Pick the CLI that already fits the work. Zentty does not rank model quality; it makes lifecycle state visible. Use Claude or OpenCode when you want richer task progress, Codex or Gemini for focused coding turns with approval visibility, and Cursor or Kimi when explicit hook installation is part of your workflow.

Capability Matrix

What The Sidebar Shows

• Running or idle state for the active agent session in a pane.
• Questions, approval prompts, auth requests, and generic input needs.
• Task progress when the agent exposes top-level task counts.
• Attention badges and macOS notifications when you are looking elsewhere.
• Crash-like unresolved stops when a tracked agent process dies mid-turn.

Integration Details

Claude Code, Codex, Copilot, Gemini, OpenCode, Pi, Cursor, Droid, and Kimi each expose different lifecycle hooks. Zentty normalizes those hook payloads into the Agent Status Protocol and forwards them through the bundled CLI.

Worked Hook Example

A tool-specific hook enters Zentty through an adapter, then becomes a common status event. This example shows a Claude-style notification being normalized into a sidebar attention state.

# Tool hook payload
{ "hook": "Notification", "message": "Approve file edit?" }

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

# Sidebar result
Pane badge: needs input · approval

Status Protocol

Adapters reduce tool-specific payloads to a small event vocabulary. That is what lets the sidebar treat a Claude permission prompt, a Codex approval, and a Gemini ToolPermission notification as the same kind of human-attention state.

$ZENTTY_CLI_BIN ipc agent-event --adapter=claude
"$ZENTTY_CLI_BIN" ipc agent-event --adapter=codex SessionStart
"$ZENTTY_CLI_BIN" gemini-hook

Troubleshooting

Manual Integrations

Tools can integrate without app changes by writing Agent Status Protocol JSON to zentty ipc agent-event. Zentty injects pane routing variables into every pane, so custom wrappers do not need to discover the active window or worklane.

"$ZENTTY_CLI_BIN" ipc agent-event <<'JSON'
{
  "version": 1,
  "event": "agent.needs-input",
  "agent": { "name": "my-agent" },
  "state": {
    "text": "Approve deployment?",
    "interaction": { "kind": "approval", "text": "Approve deployment?" }
  }
}
JSON

Agent Teams

Agent Teams is an opt-in mode for tools that expect tmux-style pane control. When enabled, Zentty places a tmux shim on PATH for the session and translates supported tmux commands into native Zentty pane operations.

The first subagent gets a golden-ratio column next to the leader pane. Later subagents stack in that team column. When the last subagent exits, Zentty dissolves the team anchor and restores the leader column width when it has a pre-team snapshot.

• Enable with [agent_teams].enabled = true.
• Use it when a supported orchestrator shells out to tmux for subagent panes.
• Leave it off when you already run real tmux intentionally or need full tmux session semantics.
• Debug routing with ZENTTY_TMUX_COMPAT_TRACE_PATH; see tmux tracing.

Security & Trust

Agent hooks are local shell commands, so treat them like any other automation installed into your shell environment. Pane tokens authorize local IPC for a specific pane; do not paste them into untrusted shells, shared logs, or remote sessions. Revoke a leaked token by closing the pane or restarting the session that exported it.

Bring Your Own CLI

Unsupported agents can still report status by wrapping the command and emitting Agent Status Protocol events before, during, and after work.

#!/usr/bin/env bash
set -euo pipefail
"$ZENTTY_CLI_BIN" ipc agent-event <<JSON
{"version":1,"event":"session.start","agent":{"name":"my-agent"}}
JSON
my-agent "$@"
"$ZENTTY_CLI_BIN" ipc agent-event <<JSON
{"version":1,"event":"agent.idle","agent":{"name":"my-agent"}}
JSON