gemini-tmux-orchestration

Use when delegating coding tasks to Gemini CLI agent, when you need parallel AI execution, or when tasks benefit from Gemini's 1M+ context window - orchestrates Gemini via tmux since headless mode cannot write files

⭐31stars🔀1forks📁View on GitHub🕐Updated Jan 1, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill enables advanced orchestration of the Gemini CLI through tmux, overcoming the limitations of headless mode to allow for file writing and shell command execution. It is specifically designed for complex coding tasks that benefit from Gemini's 1M+ context window and parallel AI execution, providing a robust framework for monitoring agent states, handling interactive inputs, and managing long-running terminal sessions.

Use Cases

  • 1. Large-Scale Codebase Refactoring: Utilize Gemini's massive 1M+ context window to analyze entire repositories and perform complex, cross-file modifications while Claude manages the orchestration via tmux.
  • 2. Parallel AI Development: Execute multiple coding tasks simultaneously by spinning up several Gemini instances in separate tmux panes, significantly accelerating the development lifecycle.
  • 3. Automated Build and Fix Loops: Implement a self-correcting workflow where Gemini writes code and Claude monitors the tmux output for build errors or 'potential loops' to trigger immediate interventions.
  • 4. Interactive CLI Tool Integration: Manage developer tools that require interactive terminal sessions or persistent environments, which are typically inaccessible to standard headless AI agents.
namegemini-tmux-orchestration
descriptionUse when delegating coding tasks to Gemini CLI agent, when you need parallel AI execution, or when tasks benefit from Gemini's 1M+ context window - orchestrates Gemini via tmux since headless mode cannot write files

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