Gemini CLI Orchestration via tmux Skill

Gemini CLI Orchestration via tmux

Overview

Gemini CLI in headless mode (-p) cannot execute shell commands or write files. Use tmux send-keys to control Gemini interactively while monitoring via capture-pane.

Quick Reference

| Action | Command | |--------|---------| | Start (split pane) | tmux split-window -h -d "cd PROJECT && gemini --yolo" | | Start (session) | tmux new-session -d -s gemini -x 200 -y 50 | | Send text | tmux send-keys -t {right} 'task text' | | Send Enter | tmux send-keys -t {right} Enter | | Check output | tmux capture-pane -t {right} -p -S -100 | | Clear input | tmux send-keys -t {right} Escape Escape | | Kill pane | tmux kill-pane -t {right} | | Kill session | tmux kill-session -t gemini |

Target: {right} for split pane, gemini for named session.

Status Markers

Detect Gemini state by grepping capture-pane output:

| Marker | State | |--------|-------| | Type your message | Idle, ready for input | | esc to cancel | Working on task | | ✓ built / ✓ Shell | Action completed | | Found \d+ errors | Build failed | | error TS | TypeScript error | | potential loop | Needs intervention (send 2 + Enter) | | Waiting for auth | OAuth expired |

Workflow

# 1. Start Gemini
tmux split-window -h -d "cd ~/project && gemini --yolo"
sleep 5

# 2. Send task (TWO separate calls - critical!)
tmux send-keys -t {right} 'Build the app per PLAN.md'
tmux send-keys -t {right} Enter

# 3. Poll for completion
while true; do
  output=$(tmux capture-pane -t {right} -p -S -50)

  # Check if idle (task done)
  if echo "$output" | grep -q "Type your message"; then
    break
  fi

  # Handle loop detection
  if echo "$output" | grep -q "potential loop"; then
    tmux send-keys -t {right} '2'
    tmux send-keys -t {right} Enter
  fi

  sleep 10
done

# 4. Check result
tmux capture-pane -t {right} -p -S -200 | tail -100

Common Mistakes

| Mistake | Fix | |---------|-----| | send-keys 'text' Enter in one call | Enter не регистрируется — отправлять отдельно | | Chaining: send-keys && sleep && capture | Команды утекают в ввод Gemini — separate bash calls | | Fixed sleep 60 | Используй polling с маркерами | | Ignoring loop detection | Gemini зависает — детектить и отправлять 2 | | Long prompts | Создай .gemini/commands/task.toml |

Custom Commands

Для повторяющихся задач создай .gemini/commands/:

# .gemini/commands/improve-design.toml
[command]
description = "Improve app design"

[[steps]]
prompt = "Improve design: gradients, shadows, animations. Run build when done."

Вызов: tmux send-keys -t {right} '/improve-design' + Enter

When NOT to Use

Read-only analysis → gemini -p "analyze" --output-format json
Simple questions → direct API call
Need deterministic output → headless with JSON schema

Agent Skills: Gemini CLI Orchestration via tmux

Skill Files