| name | omc-teams |
| description | CLI-team runtime for claude, codex, or gemini workers in tmux panes when you need process-based parallel execution |
| aliases | [] |
| level | 4 |
OMC Teams Skill
Spawn N CLI worker processes in tmux panes to execute tasks in parallel. Supports claude, codex, and gemini agent types.
/omc-teams is a legacy compatibility skill for the CLI-first runtime: use omc team ... commands (not deprecated MCP runtime tools).
Usage
/oh-my-copilot:omc-teams N:claude "task description"
/oh-my-copilot:omc-teams N:codex "task description"
/oh-my-copilot:omc-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
/omc-teams 2:claude "implement auth module with tests"
/omc-teams 2:codex "review the auth module for security issues"
/omc-teams 3:gemini "redesign UI components for accessibility"
Requirements
- tmux binary must be installed and discoverable (
command -v tmux)
- Classic tmux session optional for in-place pane splitting (
$TMUX set). Inside cmux or a plain terminal, omc team falls back to a detached tmux session instead of splitting the current surface.
- 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 tmux explicitly before claiming it is missing:
command -v tmux >/dev/null 2>&1
- If this fails, report that tmux is not installed and stop.
- If
$TMUX is set, omc 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"; omc team will launch a detached tmux session for workers instead of splitting the cmux surface.
- If neither
$TMUX nor CMUX_SURFACE_ID is set, report that the user is in a plain terminal. omc 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|geminitask — task description
Validate before decomposing or running anything:
- Reject unsupported agent types up front.
/omc-teams only supports claude, codex, and gemini.
- If the user asks for an unsupported type such as
expert, explain that /omc-teams launches external CLI workers only.
- For native Claude Code team agents/roles, direct them to
/oh-my-copilot: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
omc 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/.omcp/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
.omcp/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
/omc-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:
omc 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:
omc 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
omc team status <team-name>
omc team api list-tasks --input '{"team_name":"<team-name>"}' --json
Use omc team api ... for task claiming, task transitions, mailbox delivery, and worker state updates.
Phase 5: Shutdown (only when needed)
omc team shutdown <team-name>
omc 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:
omc_run_team_startomc_run_team_statusomc_run_team_waitomc_run_team_cleanup
If encountered, switch to omc 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 omc team use its detached-session fallback |
cmux surface detected | Running inside cmux without $TMUX | Use the normal omc team ... flow; OMC will launch a detached tmux session |
Unsupported agent type | Requested agent is not claude/codex/gemini | Use claude, codex, or gemini; for native Claude Code agents use /oh-my-copilot: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 | omc team status <team-name> then omc 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 | /omc-teams |
|---|
| Worker type | Claude Code native team agents | claude / codex / gemini CLI processes in tmux |
| Invocation | TeamCreate / Task / SendMessage | omc team [N:agent] + status + shutdown + api |
| Coordination | Native team messaging and staged pipeline | tmux worker runtime + CLI API state files |
| Use when | You want Claude-native team orchestration | You want external CLI worker execution |
