# Migration Path from Swarm Keyword Syntax to /team Syntax in oh-my-claudecode

> Migrate from Swarm keyword syntax to /team syntax in oh-my-claudecode with our guide. Learn to replace SQLite state management with Claude Code's native JSON team API.

- Repository: [Bellman/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- Tags: migration-guide
- Published: 2026-03-27

---

**Starting with version 4.1.7, oh-my-claudecode routes the legacy `/swarm` keyword to the newer `/team` orchestration layer, requiring users to replace SQLite-based state management with Claude Code's native JSON team API.**

The `swarm` keyword was originally designed to run coordinated agents claiming tasks from a shared SQLite pool, but as implemented in `Yeachan-Heo/oh-my-claudecode`, it has been deprecated in favor of the `team` syntax that leverages Claude Code's built-in team messaging without external database dependencies.

## Why Migrate from Swarm to Team Syntax?

The architectural shift eliminates filesystem bottlenecks and native module dependencies while enabling stage-aware routing.

**State Storage:** Legacy `swarm` used SQLite files (`.omc/state/swarm-*.db`) and [`swarm-state.json`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/swarm-state.json), whereas the new `team` runtime stores JSON files under `~/.claude/teams/` and `~/.claude/tasks/` using the native Claude Code team API.

**Concurrency Model:** The old system relied on transactional SQLite locks that could deadlock under heavy load. The `team` implementation uses simple JSON lock files (`.lock`) with optimistic updates, removing the SQLite concurrency ceiling.

**Dependencies:** Legacy setups required the `better-sqlite3` native module. The current `team` syntax has zero external dependencies and scales with Claude Code's built-in agent manager.

**Extensibility:** While `swarm` offered a fixed set of agents with difficult custom routing, `team` provides stage-aware routing (plan, prd, exec, verify, fix) where each stage automatically selects specialist agents.

## Step-by-Step Migration Guide

### Replace Commands

Update every occurrence of the `/swarm` command to use `/team` instead. The argument structure remains identical.

```text

# Before (deprecated)

/swarm 5:executor "fix all TypeScript errors across the project"

# After (recommended)

/team 5:executor "fix all TypeScript errors across the project"

```

### Clean Up Legacy State Files

Remove any custom scripts or monitoring tools that reference the legacy SQLite state files. The new runtime automatically creates and cleans up JSON state under `~/.claude/teams/` and `~/.claude/tasks/`.

Delete these legacy paths if they exist:
- `.omc/state/swarm-*.db`
- [`swarm-state.json`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/swarm-state.json)

### Update Documentation

Review internal READMEs and team documentation to reflect the new syntax. The [`src/hooks/AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/AGENTS.md) file still lists `swarm` for historical context according to the source code; you can retain this as a comment or remove it after confirming migration completion.

Reference [`docs/shared/mode-selection-guide.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/mode-selection-guide.md) for the official deprecation notice and mapping details.

### Validate the Migration

Test migrated commands with a small task set to verify the team lifecycle executes correctly:

1. Verify agents spawn using `/team`
2. Confirm tasks are claimed without SQLite locks
3. Ensure the full lifecycle (`team-plan → team-prd → team-exec → team-verify → team-fix`) runs to completion

## Syntax Comparison and Examples

### Basic Task Execution

Legacy `swarm` syntax routed through the SQLite-backed orchestration layer:

```text
/swarm 5:executor "refactor authentication module"

```

Modern `team` syntax using native Claude Code team management:

```text
/team 5:executor "refactor authentication module"

```

### Using the Ralph Modifier

The `team` syntax supports optional modifiers like `ralph` for complete project generation:

```text
/team ralph "build a complete REST API for user management"

```

### Bash Script Migration

Update shell scripts that construct oh-my-claudecode commands:

```bash
#!/usr/bin/env bash

# Before migration

# omc_cmd="/swarm ${AGENTS} ${TASK}"

# After migration

omc_cmd="/team ${AGENTS} ${TASK}"
eval "$omc_cmd"

```

### Verifying the New Runtime State

After running `/team` commands, verify the JSON state structure:

```bash

# List active team resources

ls ~/.claude/teams/
ls ~/.claude/tasks/

# Check for lock files (optimistic locking)

ls ~/.claude/tasks/*.lock

```

## Key Files and References

The following source files document the migration path and new architecture:

- **[`docs/shared/mode-selection-guide.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/mode-selection-guide.md)** – Contains the deprecation notice and syntax mapping from `swarm` to `team` as referenced in the mode selection guide.

- **[`skills/team/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/team/SKILL.md)** – Defines the complete `team` skill architecture, storage layout under `~/.claude/`, and usage patterns.

- **[`src/hooks/AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/AGENTS.md)** – Lists all execution modes including legacy `swarm` references for historical context.

- **[`src/hooks/setup/README.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/setup/README.md)** – Describes the obsolete SQLite database cleanup process that is no longer required.

- **[`docs/ko/MIGRATION.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/ko/MIGRATION.md)** – Korean language migration guide mentioning the removal of `swarm` support.

## Summary

- **Replace** all `/swarm` commands with `/team` maintaining the same agent and task arguments.
- **Remove** dependencies on `better-sqlite3` and delete legacy `.omc/state/swarm-*.db` files.
- **Update** documentation to reference [`skills/team/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/team/SKILL.md) instead of obsolete swarm configurations.
- **Benefit** from simplified setup, reliable parallel execution via optimistic JSON locking, and access to stage-aware routing features only available through the `team` surface.

## Frequently Asked Questions

### What version of oh-my-claudecode removed swarm support?

Version 4.1.7 introduced the routing change that aliases `swarm` (and `ultrapilot`) to the `team` orchestration layer, and the legacy `swarm` skill was removed in pull request [#1131]. The runtime still accepts the keyword but routes it through the new JSON-based system while printing a deprecation notice.

### Can I continue using `/swarm` temporarily during the transition?

Yes, the keyword still functions as an alias that routes to the `team` layer, but it prints a deprecation warning in the **Mode Selection Guide**. For future-proof behavior and access to all OMC features like cost-mode modifiers, use `/team` directly.

### What happens to my existing SQLite swarm databases?

They are no longer accessed by the runtime. You should manually delete `.omc/state/swarm-*.db` and [`swarm-state.json`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/swarm-state.json) files after migrating active tasks. The new system creates fresh JSON state in `~/.claude/teams/` and `~/.claude/tasks/` automatically.

### Does `/team` support the same agent modifiers as `/swarm`?

The `team` syntax supports the same numeric agent specifications (e.g., `5:executor`) and adds support for modifiers like `ralph` that were not available in the legacy SQLite implementation. All new OMC features are exclusively available through the `team` surface.