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-claudecode:omc-teams N:claude "task description"
/oh-my-claudecode:omc-teams N:codex "task description"
/oh-my-claudecode: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|gemini
task — 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-claudecode: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/.omc/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 .omc/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_start
omc_run_team_status
omc_run_team_wait
omc_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-claudecode: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

omc-teams