Oh-my-claudecode omc-teams

CLI-team runtime for claude, codex, or gemini workers in tmux panes when you need process-based parallel execution

install

source · Clone the upstream repo

git clone https://github.com/Yeachan-Heo/oh-my-claudecode

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Yeachan-Heo/oh-my-claudecode "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/omc-teams" ~/.claude/skills/yeachan-heo-oh-my-claudecode-omc-teams && rm -rf "$T"

manifest: skills/omc-teams/SKILL.md

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