Native Teams Interface vs OMC Team CLI Tmux Workers: Key Differences Explained

The native Teams interface leverages Claude Code's built-in agent API for orchestrated messaging and staged pipelines, while OMC team CLI workers spawn external binaries in tmux sessions for isolated, parallel execution without native coordination capabilities.

The oh-my-claudecode repository provides two distinct approaches to multi-agent workflows. Understanding the difference between the native Teams interface and the OMC team CLI tmux workers is essential for selecting the right orchestration strategy for your automation tasks.

Native Teams Interface (/team Skill)

According to skills/team/SKILL.md (lines 56–62), the native Teams interface utilizes Claude Code's internal Team API to create and manage agent workflows.

Orchestration Model The system employs functions such as TeamCreate, TaskCreate, SendMessage, and TaskList to coordinate teammates. A lead agent drives a staged pipeline through team-plan → team-prd → team-exec → team-verify → team-fix, automatically routing messages between Claude Code agents.

Runtime Environment All tasks run in-process within the Claude Code environment. There is no tmux session spawned, no separate CLI binaries launched, and no external process management. This provides filesystem-level isolation through Claude's native sandbox.

State Management Team metadata persists under ~/.claude/teams/… and integrates with OMC state files at .omc/state/team-state.json via state_write calls. The bridge/team.js file translates OMC commands into native Claude Code team API calls.

Ideal Use Case Choose this approach when you require Claude-native coordination, automatic message routing, and full staged-pipeline guarantees with specialized roles (analysts, architects, reviewers) without installing additional CLI tools.

OMC Team CLI Tmux Workers (/omc-teams Skill)

As documented in skills/omc-teams/SKILL.md (lines 38–42), the OMC team CLI provides a legacy compatibility layer for executing external command-line tools.

Orchestration Model This skill launches external CLI workers (claude, codex, gemini) in separate tmux panes rather than using Claude's internal agents. Coordination occurs through manual polling of tmux pane output and a simple REST-like API via commands such as omc team …, omc team status …, and omc team shutdown … (lines 90–115).

Runtime Environment Execution requires a functional tmux binary on the host system. When $TMUX is unset, the system falls back to detached tmux sessions (lines 48–57). Each worker runs autonomously with full filesystem access through bridge/runtime-cli.cjs, completely isolated from Claude's internal state.

State Management The system writes minimal OMC state only (e.g., state_write(mode="team", current_phase="team-exec", …) at lines 84–89). No ~/.claude/teams/ directory is created, and there is no native messaging or task-graph handling.

Ideal Use Case Use this approach when you must run external CLI tools such as @openai/codex or @google/gemini-cli that are not part of Claude's native agent set, or when you need quick, pane-based parallel execution without the full team pipeline complexity.

Architecture Comparison

Worker Type

• Native Teams: Claude Code native agents communicating via internal APIs.
• OMC CLI: External processes spawned from binaries like claude, codex, or gemini.

Communication Mechanism

• Native Teams: Built-in SendMessage and TaskList with automatic message routing between agents.
• OMC CLI: Manual tmux pane monitoring and explicit API calls (omc team status).

Pipeline Complexity

• Native Teams: Full staged pipeline with distinct phases (plan, PRD, exec, verify, fix).
• OMC CLI: Simple launch → monitor → shutdown cycle without stage gates.

Dependencies

• Native Teams: None beyond Claude Code itself.
• OMC CLI: Requires tmux binary plus external CLI installations (@anthropic-ai/claude-code, @openai/codex, @google/gemini-cli).

Practical Code Examples

Native Teams Usage

Spawn a native team of three executor agents to refactor code:

/oh-my-claudecode:team 3:executor "refactor the authentication module"

Under the hood, this executes:

TeamCreate("refactor-auth")
→ lead becomes team-lead@refactor-auth
→ explore/architect decompose task → TaskCreate × 3
→ each sub-task assigned to an executor agent
→ agents communicate via SendMessage / TaskList
→ pipeline advances through team-plan → … → team-verify

OMC Team CLI Usage

Launch two Codex workers in tmux panes for static analysis:

/omc-teams 2:codex "run static analysis on src/ and generate a report"

The execution flow follows these phases:

Phase 0 – verify tmux is installed
Phase 1 – parse N=2, agent=codex, task description
Phase 3 – execute:   omc team 2:codex "run static analysis …"
 → creates (or re-uses) a detached tmux session
 → each pane runs:  codex <task>
Phase 4 – monitor:   tmux list-panes / capture-pane
Phase 5 – shutdown:  omc team shutdown <session>

Managing Tmux Sessions

Control running OMC tmux workers via the CLI:

# Check status of a running tmux team

omc team status refactor-auth

# Force-kill all OMC tmux sessions (if stale)

omc team shutdown refactor-auth --force

Key Implementation Files

• skills/team/SKILL.md: Defines the native /team skill, pipeline stages, and Claude Code team API integration.
• skills/omc-teams/SKILL.md: Documents the legacy tmux-based worker spawning, prerequisites, and monitoring workflow.
• bridge/team.js: Bridge layer that translates OMC commands into Claude Code native team API calls.
• bridge/runtime-cli.cjs: Runtime environment used by tmux-based CLI workers for external process management.
• CLAUDE.md: Lists native Claude Code Teams operations including TeamCreate and SendMessage.

Summary

• Native Teams use Claude Code's internal agent API with automatic messaging through SendMessage and full staged pipelines (team-plan through team-fix).
• OMC team CLI spawns external processes in tmux panes via omc team commands, supporting binaries like codex and gemini but lacking native coordination.
• Native Teams store rich state in ~/.claude/teams/ with complex task graphs; OMC workers maintain minimal JSON state only.
• Select native Teams for rich, Claude-native coordination and OMC CLI when integrating external CLI tools requiring tmux isolation.

Frequently Asked Questions

Can I use both native Teams and OMC CLI workers in the same oh-my-claudecode project?

Yes, but they maintain separate state systems and do not interoperate. Native Teams store metadata in ~/.claude/teams/ while OMC CLI workers only update .omc/state/team-state.json. Use native Teams for complex Claude-only workflows and OMC CLI for specific external tool integration.

What happens if tmux is not installed when using the OMC team CLI?

The /omc-teams skill explicitly requires a functional tmux binary. As noted in skills/omc-teams/SKILL.md (lines 48–57), execution will fail during Phase 0 verification if tmux is unavailable, since the architecture depends on tmux panes for process isolation and output capture.

Do OMC team CLI workers support the same pipeline stages as native Teams?

No. While native Teams progress through structured stages (team-plan → team-prd → team-exec → team-verify → team-fix) with specialized agent roles, OMC CLI workers execute a simple launch-monitor-shutdown cycle. Each tmux pane runs the supplied command once without stage gates or automatic review steps.

Which approach provides better isolation for security-sensitive operations?

Native Teams run inside Claude Code's existing sandbox with no external process spawning, providing tighter integration with Claude's security model. OMC CLI workers spawn independent processes with full filesystem access through tmux, making them suitable for isolated parallel tasks but requiring manual security verification of the external binaries (codex, gemini, etc.).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}