omq-teams

name	omq-teams
description	CLI-team runtime for claude, codex, or gemini workers in tmux panes when you need process-based parallel execution
aliases	[]
level	4

OMQ Teams Skill

Spawn N CLI worker processes in tmux panes to execute tasks in parallel. Supports claude, codex, and gemini agent types.

/omq-teams is a legacy compatibility skill for the CLI-first runtime: use omq team ... commands (not deprecated MCP runtime tools).

Usage

/oh-my-qoder:omq-teams N:claude "task description"
/oh-my-qoder:omq-teams N:codex "task description"
/oh-my-qoder:omq-teams N:gemini "task description"

Parameters

• N - Number of CLI workers (1-10)
• agent-type - claude (Claude CLI), codex (OpenAI Codex CLI), or gemini (Google Gemini CLI)
• task - Task description to distribute across all workers

Examples

/omq-teams 2:claude "implement auth module with tests"
/omq-teams 2:codex "review the auth module for security issues"
/omq-teams 3:gemini "redesign UI components for accessibility"

Requirements

• tmux binary must be installed and discoverable (command -v tmux) when running from a plain terminal; classic tmux sessions reuse the current tmux surface.
• cmux surface optional for in-place native splits (CMUX_SURFACE_ID set without $TMUX). Plain terminals still use the detached tmux fallback.
• claude CLI: npm install -g @anthropic-ai/claude-code
• codex CLI: npm install -g @openai/codex
• gemini CLI: npm install -g @google/gemini-cli

Workflow

Phase 0: Verify prerequisites

Check the active multiplexer before claiming tmux is missing. If $TMUX is empty and CMUX_SURFACE_ID is also empty, check tmux explicitly:

command -v tmux >/dev/null 2>&1

• If the plain-terminal tmux check fails, report that tmux is not installed and stop.
• If $TMUX is set, omq team can reuse the current tmux window/panes directly.
• If $TMUX is empty but CMUX_SURFACE_ID is set, report that the user is running inside cmux. Do not say tmux is missing or that they are "not inside tmux"; omq team will create native cmux splits for workers.
• If neither $TMUX nor CMUX_SURFACE_ID is set, report that the user is in a plain terminal. omq team can still launch a detached tmux session, but if they specifically want in-place pane/window topology they should start from a classic tmux session first.
• If you need to confirm the active tmux session, use:

tmux display-message -p '#S'

Phase 1: Parse + validate input

Extract:

• N — worker count (1-10)
• agent-type — claude|codex|gemini
• task — task description

Validate before decomposing or running anything:

• Reject unsupported agent types up front. /omq-teams only supports claude, codex, and gemini.
• If the user asks for an unsupported type such as expert, explain that /omq-teams launches external CLI workers only.
• For native Qoder CLI team agents/roles, direct them to /oh-my-qoder:team instead.

Phase 2: Decompose task

Break work into N independent subtasks (file- or concern-scoped) to avoid write conflicts.

Phase 2.5: Resolve workspace root for multi-repo plans

omq team launches all workers with one shared working directory. For single-repo tasks, the current repo is usually correct. For multi-repo tasks, especially when a plan lives in one repo but the implementation touches sibling repos, resolve the working directory before launch:

• If the task references a plan artifact under one repo (for example tool/.omq/plans/task-1200-gwd-gifs.md) and target paths in sibling repos (for example api/ and admin/), choose the shared workspace root that contains all participating repos (for example the parent inter/ directory).
• Use an absolute plan path in the task text so the workers can still find the plan after --cwd changes the launch directory.
• Include the explicit repo paths or repo names in the task text and subtasks.
• Do not anchor the launch cwd to only the repo containing .omq/plans/... when target repos are siblings; that strands codex, claude, and gemini workers in the plan repo instead of the implementation workspace.
• If no safe shared workspace root can be identified, do not launch /omq-teams. Report the single-cwd constraint and ask for, or derive from evidence, the intended workspace root.

Phase 3: Start CLI team runtime

Activate mode state (recommended):

state_write(mode="team", current_phase="team-exec", active=true)

Start workers via CLI:

omq team <N>:<claude|codex|gemini> "<task>"

For the multi-repo case resolved in Phase 2.5, launch from the shared workspace root with the existing --cwd contract and keep the plan reference absolute:

omq team <N>:<claude|codex|gemini> "<task with absolute plan path and explicit repo paths>" --cwd <workspace-root>

Team name defaults to a slug from the task text (example: review-auth-flow).

After launch, verify the command actually executed instead of assuming Enter fired. Check pane output and confirm the command or worker bootstrap text appears in pane history:

tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_id} #{pane_current_command}'
tmux capture-pane -pt <pane-id> -S -20

Do not claim the team started successfully unless pane output shows the command was submitted.

Phase 4: Monitor + lifecycle API

omq team status <team-name>
omq team api list-tasks --input '{"team_name":"<team-name>"}' --json

Use omq team api ... for task claiming, task transitions, mailbox delivery, and worker state updates.

Phase 5: Shutdown (only when needed)

omq team shutdown <team-name>
omq team shutdown <team-name> --force

Use shutdown for intentional cancellation or stale-state cleanup. Prefer non-force shutdown first.

Phase 6: Report + state close

Report task results with completion/failure summary and any remaining risks.

state_write(mode="team", current_phase="complete", active=false)

Deprecated Runtime Note

Legacy MCP runtime tools are deprecated for execution:

• omq_run_team_start
• omq_run_team_status
• omq_run_team_wait
• omq_run_team_cleanup

If encountered, switch to omq team ... CLI commands.

Error Reference

Error	Cause	Fix
not inside tmux	Requested in-place pane topology from a non-tmux surface	Start tmux and rerun, or let omq team use its detached-session fallback
cmux surface detected	Running inside cmux without $TMUX	Use the normal omq team ... flow; OMQ will create native cmux worker splits
Unsupported agent type	Requested agent is not claude/codex/gemini/grok/cursor	Use claude, codex, gemini, grok, or cursor; for native Qoder CLI agents use /oh-my-qoder:team
codex: command not found	Codex CLI not installed	npm install -g @openai/codex
gemini: command not found	Gemini CLI not installed	npm install -g @google/gemini-cli
Team <name> is not running	stale or missing runtime state	omq team status <team-name> then omq team shutdown <team-name> --force if stale
status: failed	Workers exited with incomplete work	inspect runtime output, narrow scope, rerun

Relationship to /team

Aspect	/team	/omq-teams
Worker type	OMQ file-based team agents (MCP tools)	claude / codex / gemini CLI processes in tmux
Invocation	team_* MCP tools + Agent spawning	omq team [N:agent] + status + shutdown + api
Coordination	File-based task board + atomic claim protocol	tmux worker runtime + CLI API state files
Use when	You want MCP-native team orchestration	You want external CLI worker execution