Claude Code's native team feature and Oh My ClaudeCode (OMC)'s Team/Swarm are not mutually exclusive — they form a layered relationship. OMC Team is a wrapper that fully embraces the native infrastructure and adds orchestration on top.
┌─────────────────────────────────────────┐
│ OMC Team (Orchestration Layer) │
│ - 5-stage pipeline │
│ (plan → PRD → exec → verify → fix) │
│ - Auto fix loop (up to 3 retries) │
│ - MCP Worker bridge (Codex/Gemini) │
│ - State management (.omc/state/) │
├─────────────────────────────────────────┤
│ Claude Code Native Team (Foundation) │
│ - TeamCreate / TeamDelete │
│ - TaskCreate / TaskUpdate / TaskList │
│ - SendMessage (DM, broadcast, shutdown)│
│ - ~/.claude/teams/ + ~/.claude/tasks/ │
└─────────────────────────────────────────┘
OMC Team does not build a separate infrastructure. It uses Claude Code's native tools — TeamCreate, SendMessage, TaskCreate, etc. — directly, adding automated pipelines and state management on top.
The built-in multi-agent collaboration tools provided by Claude Code. These serve as the execution foundation for Multi-Agent systems (Korean).
| Tool | Role | Reads | Writes |
|---|---|---|---|
| TeamCreate | Initialize team | — | config.json, inboxes/, .lock |
| TaskCreate | Create task | .highwatermark |
{taskId}.json |
| TaskList | Query all tasks | {taskId}.json |
— |
| TaskGet | Query single task | {taskId}.json |
— |
| TaskUpdate | Modify/assign task | {taskId}.json |
{taskId}.json |
| SendMessage | Send message | — | inboxes/{agent}.json |
| TeamDelete | Cleanup team | All | Deletes all |
~/.claude/teams/{team-name}/
├── config.json # Team metadata + members array
└── inboxes/
└── {agent-name}.json # Per-agent message queue
~/.claude/tasks/{team-id}/
├── .lock # Concurrency control
├── .highwatermark # Task ID counter
└── {taskId}.json # Individual task files
Each agent receives a unique ID in the format {name}@{team-name}, with a dedicated inbox and tmux pane.
{
"agentId": "backend-dev@my-project",
"name": "backend-dev",
"agentType": "general-purpose",
"model": "claude-sonnet-4-5-20250929",
"tmuxPaneId": "%1",
"isActive": true
}
Tasks express dependencies through blockedBy and blocks arrays.
{
"id": "3",
"subject": "Implement API endpoints",
"status": "pending",
"owner": "backend-dev",
"blockedBy": ["1", "2"],
"blocks": ["4"]
}
Agent-A: SendMessage(type="message", recipient="Agent-B", content="...")
↓
Appended to inboxes/Agent-B.json (read: false)
↓
Auto-delivered at Agent-B's turn boundary
↓
Agent-B receives and processes the message
Key characteristic: Messages are delivered at turn boundaries — this is an asynchronous queue model, not real-time streaming.
OMC Team fully leverages the native team infrastructure while adding the following.
team-plan → explore + planner decompose tasks
↓
team-prd → analyst refines requirements (optional)
↓
team-exec → executor/specialist workers do the actual work
↓
team-verify → verifier + reviewers check quality
↓
team-fix → auto-fix on failure (up to 3 retry loops)
Task assignment: The lead pre-assigns tasks via TaskUpdate(taskId, owner="worker-1") before spawning workers. Workers only process tasks assigned to them.
Lead: TaskCreate(subject="Fix auth.ts")
Lead: TaskUpdate(taskId="1", owner="worker-1")
Lead: Task(team_name="my-team", name="worker-1", prompt="...")
↓
Worker-1: TaskList() → finds assigned task
Worker-1: TaskUpdate(taskId="1", status="in_progress")
Worker-1: (performs work)
Worker-1: TaskUpdate(taskId="1", status="completed")
Worker-1: SendMessage(recipient="team-lead", content="Done", summary="Task #1 complete")
Alongside native team state, OMC maintains its own state file.
// .omc/state/team-state.json
{
"mode": "team",
"active": true,
"current_phase": "team-exec",
"state": {
"team_name": "fix-ts-errors",
"agent_count": 3,
"fix_loop_count": 1,
"max_fix_loops": 3,
"stage_history": "team-plan:T1,team-exec:T2,team-verify:T3"
}
}
OMC Team can integrate external CLI tools as team members beyond Claude agents.
| Aspect | Claude Teammate | MCP Worker (Codex/Gemini) |
|---|---|---|
| Tool access | Full (Read/Write/Edit/Bash) | Filesystem (CLI) |
| Communication | SendMessage (DM, broadcast) | Outbox files (one-way) |
| Team awareness | TaskList/TaskUpdate capable | None (fire-and-forget) |
| Cost | Higher (Claude) | Lower (specialized) |
| Concurrency | Session-based | git worktree isolation |
As of OMC 4.2.2+,
/swarminternally routes to/team. Swarm exists only as a compatibility facade.
Swarm operated an independent task queue based on SQLite (better-sqlite3).
-- Atomic task claiming
BEGIN IMMEDIATE;
SELECT id FROM tasks WHERE status='pending' ORDER BY id LIMIT 1;
UPDATE tasks SET status='claimed', claimed_by=?, claimed_at=? WHERE id=?;
COMMIT;
| Aspect | Swarm (Legacy) | Team (Current) |
|---|---|---|
| Storage | .omc/state/swarm.db (SQLite) |
~/.claude/tasks/ (JSON) |
| Task claiming | Atomic transactions | Lead pre-assignment |
| Inter-agent comms | None (fire-and-forget) | SendMessage |
| External deps | better-sqlite3 npm |
None |
| Fault recovery | 5-min lease timeout | Lead detects via messages |
| Dependency tracking | None | blocks/blockedBy |
Why Swarm was deprecated:
blocks/blockedBy is more powerful| Dimension | Claude Code Native | OMC Team | OMC Swarm (Deprecated) |
|---|---|---|---|
| Infrastructure | Foundation tools | Native wrapper | Independent SQLite |
| Task storage | ~/.claude/tasks/ JSON |
Same (uses Native) | .omc/state/swarm.db |
| Task assignment | Manual (flexible) | Lead pre-assigns | Atomic transactions |
| Agent comms | SendMessage | Same (uses Native) | None |
| Pipeline | None | 5-stage auto | None |
| Verification loop | None | verify → fix (up to 3x) | None |
| External workers | None | Codex/Gemini bridge | None |
| State persistence | In-session | .omc/state/ files |
SQLite DB |
| External deps | None | None | better-sqlite3 |
| Current status | Active | Active (recommended) | Deprecated → routes to Team |
// Direct control example
TeamCreate("my-project")
TaskCreate("Implement backend API")
TaskCreate("Implement frontend UI")
TaskUpdate(taskId="1", owner="backend-dev")
TaskUpdate(taskId="2", owner="frontend-dev")
Task(team_name="my-project", name="backend-dev", prompt="...")
Task(team_name="my-project", name="frontend-dev", prompt="...")
/team) When:Most effective approach: Leverage OMC's orchestration layer by default, but understand native tool mechanics for debugging and customization.
/team — pipeline, verification loops, and state management automated~/.claude/teams/ and ~/.claude/tasks/ files directly for state diagnosis# Check team status
cat ~/.claude/teams/{team-name}/config.json | jq '.members[] | {name, isActive}'
# Check task status
ls ~/.claude/tasks/{team-id}/*.json | xargs -I {} sh -c 'echo "=== {} ===" && cat {} | jq {id, subject, status, owner}'
# Check OMC state
cat .omc/state/team-state.json | jq .
# OMC Team shutdown and cleanup flow
SendMessage(type="shutdown_request", recipient="worker-1")
→ worker-1: SendMessage(type="shutdown_response", approve=true)
→ TeamDelete() # Removes ~/.claude/teams/ + ~/.claude/tasks/
→ state_clear(mode="team") # Removes .omc/state/team-state.json
Race Condition: Native team task files are JSON-based, so concurrent writes can conflict. OMC mitigates this with lead pre-assignment. The
.lockfile exists but does not guarantee full transactional safety.