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

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, 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.

# 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

Update Documentation

Review internal READMEs and team documentation to reflect the new syntax. The 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 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:

/swarm 5:executor "refactor authentication module"

Modern team syntax using native Claude Code team management:

/team 5:executor "refactor authentication module"

Using the Ralph Modifier

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

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

Bash Script Migration

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

#!/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:

# 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 – Contains the deprecation notice and syntax mapping from swarm to team as referenced in the mode selection guide.

• skills/team/SKILL.md – Defines the complete team skill architecture, storage layout under ~/.claude/, and usage patterns.

• src/hooks/AGENTS.md – Lists all execution modes including legacy swarm references for historical context.

• src/hooks/setup/README.md – Describes the obsolete SQLite database cleanup process that is no longer required.

• 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 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 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.

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