Tmux Smart Wait
🔑 FOR CALLERS: How to Invoke This Skill
When you need to wait for something in a tmux pane, invoke this skill - don't write your own loops.
# Use the tmux-wait skill workflow for:
$tmux-wait prompt 0 60 # Wait for shell prompt
$tmux-wait output 0 "text" # Wait for specific text
$tmux-wait command 0 cmd # Execute and wait
NEVER copy the bash code below into your own scripts. ALWAYS invoke via $tmux-wait.
⚠️ FOR SKILL EXECUTION: Execute Immediately ⚠️
(This section is for when the skill has been invoked and agent is executing it)
You MUST execute the bash code below using the Bash tool NOW. Do not just read these instructions.
Arguments received: $ARGS
Parse the arguments:
- $1 = mode (
command,prompt, oroutput) - $2 = pane number (0, 1, 2, etc.)
- $3+ = additional arguments (depends on mode)
Based on $1, EXECUTE the corresponding bash script below using the Bash tool:
If mode is command: EXECUTE THIS
PANE="<$2>"
COMMAND="<$3 and remaining args>"
SIGNAL="cmdwait-${RANDOM}-$$"
echo "Executing in pane $PANE: $COMMAND"
tmux send-keys -t "$PANE" "$COMMAND; tmux wait-for -S $SIGNAL" Enter
tmux wait-for "$SIGNAL"
echo ""
echo "=== Command completed. Output ==="
tmux capture-pane -t "$PANE" -p -S -50
If mode is prompt: EXECUTE THIS
PANE="<$2>"
TIMEOUT="${3:-30}"
MAX_POLLS=$((TIMEOUT * 5))
echo "Waiting for prompt in pane $PANE (timeout: ${TIMEOUT}s)..."
poll_count=0
while ((poll_count++ < MAX_POLLS)); do
output=$(tmux capture-pane -t "$PANE" -p -S -50)
last_line=$(echo "$output" | sed '/^[[:space:]]*$/d' | tail -1)
# Check for agent permission prompts (all types)
if echo "$output" | grep -qF "Do you want"; then
elapsed=$((poll_count * 2 / 10))
echo "✓ Permission prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check for plan approval prompt and other "Would you like" prompts
if echo "$output" | grep -qF "Would you like"; then
elapsed=$((poll_count * 2 / 10))
echo "✓ Approval prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check for Antigravity workspace trust prompt
if echo "$output" | grep -qF "Do you trust the contents of this project?"; then
elapsed=$((poll_count * 2 / 10))
echo "✓ Antigravity trust prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check for confirmation dialogs (folder trust, Codex permission prompts, etc.)
# Case-insensitive: prompts may say "enter to confirm" or "enter to continue".
if echo "$output" | grep -Eiq "enter to (confirm|continue)"; then
elapsed=$((poll_count * 2 / 10))
echo "✓ Confirmation prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check if agent TUI prompt is present (❯ or ›)
if [[ "$last_line" =~ (❯|›)[[:space:]]*$ ]] || [[ "$last_line" =~ ^[[:space:]]*(❯|›) ]]; then
# agent prompt found - check if still thinking/processing
# Only check last 5 lines to avoid stale indicators from previous operations
# IMPORTANT: Only match ACTIVE states. Do NOT add star chars (✻✽✶✢) or
# completion words (Brewed/Churned/Cooked/thought for) — they persist after
# agent finishes and cause false blocking on idle prompts.
last_5_check=$(echo "$output" | sed '/^[[:space:]]*$/d' | tail -5)
if echo "$last_5_check" | grep -qE "(Symbioting|Recombobulating|Running.*agents|[Ee]sc to interrupt|⏸ plan mode)"; then
# agent is still processing, keep waiting
sleep 0.2
continue
fi
# agent prompt present and no thinking indicators - truly ready
elapsed=$((poll_count * 2 / 10))
echo "✓ agent prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check if shell prompt is present ($, #, %, >, PS).
# Use grep here instead of [[ =~ ]] so zsh does not parse a bare ">" as redirection.
if printf '%s\n' "$last_line" | grep -Eq '(\$|#|%|>)[[:space:]]*$|^[[:space:]]*[\$#%>]|^PS[[:space:]].*>$'; then
# Shell prompt found - return immediately (no thinking check needed)
elapsed=$((poll_count * 2 / 10))
echo "✓ Shell prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check for Antigravity CLI idle prompt (interactive mode)
# Antigravity shows a bare ">" input line and model status such as
# "Gemini 3.5 Flash (Medium)" in the TUI chrome.
last_10_lines=$(echo "$output" | tail -10)
if echo "$output" | grep -qF "Antigravity CLI" || echo "$last_10_lines" | grep -qE "Gemini [0-9.]+ .*\\((Low|Medium|High)\\)"; then
if echo "$last_10_lines" | grep -qiE "(Running|Thinking|Working|esc to cancel|cancel)"; then
sleep 0.2
continue
fi
if echo "$last_10_lines" | grep -qE '^[[:space:]]*>[[:space:]]*$'; then
elapsed=$((poll_count * 2 / 10))
echo "✓ Antigravity TUI prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
fi
# Check for Gemini TUI idle prompt (interactive mode)
# Gemini's idle state shows "Type your message" in its input field area
# and workspace/sandbox info in the bottom status bar.
# IMPORTANT: "Type your message" is ALWAYS visible in BOTH active and idle states.
# When active, Gemini shows a spinner line with "esc to cancel" in the last 10 lines.
# Only return if "Type your message" is present AND no active indicator found.
if echo "$last_10_lines" | grep -qF "Type your message"; then
if echo "$last_10_lines" | grep -qF "esc to cancel"; then
# Gemini is actively processing, keep waiting
sleep 0.2
continue
fi
elapsed=$((poll_count * 2 / 10))
echo "✓ Gemini TUI prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check for Codex TUI idle prompt (interactive mode)
# Codex's idle state shows model info at the bottom, with a › prompt
# somewhere above. Newer builds may show either:
# gpt-5.4 default · 88% left · ~/path
# gpt-5.4 medium · ~/path
# IMPORTANT: The gpt- status line appears in BOTH active and idle states.
# When active, Codex shows "• Working" or "◦ Working" in the last 10 lines.
# Only return if the status line is present AND no Working indicator found.
if echo "$last_10_lines" | grep -qE "gpt-[0-9][^[:space:]]*[[:space:]].*·|gpt-.*default.*left|OpenAI Codex"; then
if echo "$last_10_lines" | grep -qE "[•◦] Working"; then
# Codex is actively processing, keep waiting
sleep 0.2
continue
fi
elapsed=$((poll_count * 2 / 10))
echo "✓ Codex TUI prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Special case: "? for shortcuts" means prompt might be above the last line
if [[ "$last_line" =~ (for shortcuts) ]]; then
last_5_lines=$(echo "$output" | sed '/^[[:space:]]*$/d' | tail -5)
# Check for agent prompts first (❯ or ›)
if echo "$last_5_lines" | grep -qE '^\s*(❯|›)'; then
# Found agent prompt - check if still thinking/processing
# Only check last 5 lines to avoid stale indicators from previous operations
# IMPORTANT: Only match ACTIVE states — see comment above for rationale
if echo "$last_5_lines" | grep -qE "(Symbioting|Recombobulating|Running.*agents|[Ee]sc to interrupt|⏸ plan mode)"; then
# agent is still processing, keep waiting
sleep 0.2
continue
fi
# agent prompt present and no thinking indicators - truly ready
elapsed=$((poll_count * 2 / 10))
echo "✓ agent prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
# Check for shell prompts ($, #, %, >, PS)
if echo "$last_5_lines" | grep -qE '^\s*(\$|#|%|>)' || echo "$last_5_lines" | grep -qE '^PS\s.*>'; then
# Shell prompt found - return immediately (no thinking check needed)
elapsed=$((poll_count * 2 / 10))
echo "✓ Shell prompt detected after ${elapsed}s"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 0
fi
fi
sleep 0.2
done
echo "✗ Timeout after $TIMEOUT seconds"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 1
If mode is output: EXECUTE THIS
PANE="<$2>"
SEARCH_TEXT="<$3>"
TIMEOUT="${4:-30}"
MAX_POLLS=$((TIMEOUT * 5))
echo "Waiting for text in pane $PANE: \"$SEARCH_TEXT\" (timeout: ${TIMEOUT}s)..."
poll_count=0
while ((poll_count++ < MAX_POLLS)); do
output=$(tmux capture-pane -t "$PANE" -p -S -50)
if echo "$output" | grep -qF "$SEARCH_TEXT"; then
elapsed=$((poll_count * 2 / 10))
echo "✓ Found text after ${elapsed}s"
echo ""
echo "=== Pane output ==="
echo "$output"
exit 0
fi
sleep 0.2
done
echo "✗ Timeout after $TIMEOUT seconds - text not found"
echo ""
echo "=== Pane output ==="
tmux capture-pane -t "$PANE" -p -S -50
exit 1
Reference Documentation
Permission Requirements
IMPORTANT: This skill uses complex bash scripts with loops and variables. For it to work without permission prompts, you must add "Bash" to your project-local tool approval settings allow list:
{
"permissions": {
"allow": [
"Bash",
"tmux-wait"
]
}
}
Why is this needed?
AI agent TUI's permission system uses prefix matching for commands. Patterns like "Bash(tmux:*)" only match commands that start with "tmux", but this skill uses multi-line bash scripts with variables, loops, and multiple commands. The general "Bash" permission is required for these compound scripts to execute without prompts.
Note: If you use $init-team-ai skill, this permission will be automatically added to your project's settings.
Usage Modes
The skill supports three modes:
- command - Execute a command and wait for completion using
tmux wait-for(shortcut, skips safety checks) - prompt - Wait for shell/agent prompt to return
- output - Wait for specific text to appear in output
Parameters
Arguments are provided as: <mode> <pane> [additional args...]
- $1 (mode): One of
command,prompt, oroutput - $2 (pane): Pane number (0, 1, 2) or position ({left}, {right}, {top}, {bottom})
- $3+: Mode-specific arguments
Mode Syntax
- command:
$tmux-wait command <pane> <command-to-run> - prompt:
$tmux-wait prompt <pane> [timeout](default timeout: 30s) - output:
$tmux-wait output <pane> <search-text> [timeout](default timeout: 30s)
Usage Examples
Wait for the agent to start:
$tmux-wait prompt 0 60
Wait for permission prompts (all types including tool execution, file edits, and file creation - auto-detected by prompt mode):
$tmux-wait prompt 0 60
Execute command and wait:
$tmux-wait command 1 npm test
Wait for specific output:
$tmux-wait output 0 "Build complete" 60
Proper Workflow: When to Use Each Mode
CRITICAL: Choose the right mode for the right situation.
Use prompt mode (DEFAULT - MOST COMMON)
This is your default choice after executing any command:
$tmux-wait prompt <pane> 60
When to use:
- After executing any command in a pane
- After approving permissions
- After starting applications (like Codex or another agent TUI)
- Any time you need to know "is the command done?"
- Waiting for agent permission prompts (all types: "Do you want to proceed?", "Do you want to make this edit", "Do you want to create X?" - auto-detected!)
- Waiting for agent confirmation dialogs (folder trust prompt with "Enter to confirm")
- NEW: Waiting for AI agent TUI to finish thinking/processing (Symbioting, plan mode, agent execution)
Why it's better:
- Detects when command finishes, regardless of output
- No assumptions about specific success messages
- Works for any command that returns to a prompt
- Automatically detects ALL agent permission prompts (tool execution, file edits, file creation - any prompt starting with "Do you want")
- NEW: Automatically detects agent active processing states and waits until truly complete
- Fast and reliable
Then check what happened:
$see-terminal <pane> # Check with 50 lines (default)
$see-terminal <pane> 100 # Use 100 if you need more context
Use output mode (SPECIFIC CASES ONLY)
Only use this when you need to detect specific text that you KNOW will appear:
$tmux-wait output <pane> "<exact-text>" <timeout>
When to use:
- User input prompts:
$tmux-wait output 0 "Enter password:" 30 - Specific error patterns:
$tmux-wait output 0 "Build failed" 60 - Waiting for very specific text that's not a standard prompt
When NOT to use:
- ❌ Completion messages that may vary or not exist
- ❌ Success messages that are optional
- ❌ Any text you're not 100% certain will appear
Common Mistakes to Avoid
❌ WRONG - Searching for completion text that may not exist:
# These assume specific success messages and waste time if they don't appear
$tmux-wait output 0 "Team AI Initialization Complete" 60
$tmux-wait output 0 "Build succeeded" 60
$tmux-wait output 0 "Installation complete" 60
✅ CORRECT - Wait for prompt, then check what happened:
# Wait for command to finish
$tmux-wait prompt 0 60
# Check what actually happened
$see-terminal 0
Complete Example: Testing a Skill
# 1. Execute the skill
tmux send-keys -t 0 '$init-team-ai' Enter
sleep 1
tmux send-keys -t 0 Enter
# 2. Wait for permission prompt (prompt mode auto-detects it!)
$tmux-wait prompt 0 60
# 3. Approve permission
tmux send-keys -t 0 Enter
# 4. Wait for command to finish
$tmux-wait prompt 0 60
# 5. Check what actually happened
$see-terminal 0
# If you need more context:
$see-terminal 0 100
Note: The prompt mode now automatically detects ALL agent permission prompts by matching "Do you want" (covers "Do you want to proceed?", "Do you want to make this edit", "Do you want to create X?", etc.), so you don't need to use output mode for them. This makes the workflow simpler and faster.
Quick Decision Guide
Ask yourself: "Do I know the EXACT text that will appear?"
- NO → Use
promptmode, then$see-terminalto check results - YES, and it's a prompt requiring action → Use
outputmode
Important Notes
- All variables are properly quoted to handle special characters
- Signal names use $RANDOM and $$ for uniqueness
- grep uses -F flag for literal string matching (no regex issues)
- Elapsed time calculation uses pure bash arithmetic (no external tools)
- The
tailcommand is now in the allowed-tools list
Supported Shell Prompts
The prompt mode detects the following shell prompts:
| Shell / TUI | Prompt Pattern | Example |
|---|---|---|
| Bash | $ |
user@host:~$ |
| Root | # |
root@host:~# |
| Zsh | % |
user@host % |
| Fish/Starship | ❯ or › |
~/projects ❯ |
| PowerShell | > or PS ...> |
PS C:\Users\name> |
| AI agent TUI | ❯ |
❯ |
| Antigravity CLI | Antigravity CLI / Gemini 3.5 Flash |
> |
| Gemini CLI (legacy) | Type your message |
* Type your message or @path/to/file |
| Codex CLI | gpt-* status line |
gpt-5.4 default · 88% left · ~/project or gpt-5.4 medium · ~/project |
PowerShell Support: Works with PowerShell running inside tmux panes in WSL. Both standard prompts (PS C:\>) and verbose UNC paths (PS Microsoft.PowerShell.Core\FileSystem::\\wsl.localhost\...>) are detected.
Antigravity/Gemini/Codex TUI Support: Detects idle state for interactive TUI agents used in team-ai pipelines. Antigravity shows Antigravity CLI plus a bare > prompt and model status like Gemini 3.5 Flash; legacy Gemini shows Type your message; Codex shows a model info line like gpt-5.4 default · 88% left · ~/path or gpt-5.4 medium · ~/path. Active processing is detected by CLI-specific active indicators so tmux-wait continues polling instead of returning early.
Agent TUI Processing Detection
NEW: The prompt mode now intelligently detects when AI agent TUI is actively processing and waits until truly complete, even when the ❯ prompt is visible.
IMPORTANT: This check ONLY applies when a agent TUI prompt (❯ or ›) is detected. Regular shell prompts ($, #, %, >, PS) return immediately without checking for thinking indicators.
Detected Active Processing States (agent prompts only):
Symbioting...- agent is actively thinking/processingRecombobulating...- agent is actively processingRunning.*agents/Explore agents- Parallel agents executingEsc to interrupt- Active task running⏸ plan mode on- Plan mode is active
NOT treated as active (completion indicators):
✻ Brewed for.../✻ Churned for.../✻ Cooked for...- These are COMPLETION messages, not active states. They remain visible after agent finishes and returns to idle prompt.
How it works:
- If a agent prompt (
❯or›) is detected AND any processing indicator is found in the last 5 non-empty lines, tmux-wait continues waiting - If a shell prompt (
$,#,%) is detected, returns immediately (no thinking check) - Only returns when processing is complete AND prompt is ready
- Prevents false positives from detecting the agent prompt symbol while agent is still thinking
Note: The thinking indicator check only scans the last 5 non-empty lines near the prompt, avoiding false positives from stale indicators (e.g. ✻ Cooked for...) left over from previous operations.
Example:
# Wait for agent to finish creating a plan
$tmux-wait prompt 2 300
# This will now properly wait through:
# - "Symbioting... (3m 10s)"
# - "Running 3 Explore agents..."
# - "Plan mode on"
# And only return when agent is truly done
Gemini TUI Processing Detection
The prompt mode detects when Gemini CLI is actively processing and waits until truly complete, even though Type your message is always visible.
Key insight: Type your message appears in BOTH active and idle states — it's part of the permanent TUI chrome, not an idle indicator.
Active state indicator:
- Spinner line with
esc to cancel— e.g.,⠼ Cancel a request with Ctrl+C… (esc to cancel, 1s)or⠏ Automatically accept safe read-only… (esc to cancel, 5s)
Idle state indicator:
? for shortcutsvisible near the bottom status bars- No
esc to cancelline present
How it works:
- If
Type your messageis found in last 10 lines ANDesc to cancelis also found → Gemini is active, keep waiting - If
Type your messageis found but NOesc to cancel→ Gemini is idle, return success