Skip to content
Back to search

swarms

SkillWorks with CodexGitHub

Multi-agent orchestration skills for Claude Code and Codex

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/am-will--swarms/badge.svg)](/listings/am-will--swarms)

HTML

<a href="/listings/am-will--swarms"><img src="/api/listings/am-will--swarms/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

npx skills add am-will/swarms

Codex

npx skills add am-will/swarms

**Required: Enable Subagents**

Swarms uses subagents to execute tasks in parallel. Codex CLI users must enable this experimental feature by adding the following to your `~/.codex/config.toml`:

[features]
multi_agents = true

Without this setting, the parallel-task skill will not be able to spawn subagents.

**Recommended: Context7 MCP**

I recommend pairing Swarms with the Context7 MCP server to ensure you're using the latest libraries, APIs, and documentation during planning and implementation.

For Codex, add this to your `~/.codex/config.toml`:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" }

For other agents, visit https://context7.com/dashboard for setup instructions.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 233 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <img width="1024" height="559" alt="image" src="https://github.com/user-attachments/assets/778c9168-b39a-4b2f-8a4c-1e06ee00d98c" />
  2. # Swarms
  3. Multi-agent orchestration for Claude Code and Codex. Plan with explicit dependencies, execute in parallel waves, with an orchestrator that maintains context and verifies work.
  4. ## The Problem with Simple Loops
  5. A popular pattern for AI coding agents is the bash loop: spawn an agent, have it find the next task, execute it, repeat. It mirrors how humans work, logical and straightforward.
  6. But LLMs aren't humans. Each new agent session starts fresh. It has to:
  7. - Re-read the same prompt as every previous iteration
  8. - Discover the current project state through exploration
  9. - Figure out what comes next by inspecting previous work
  10. - Hope the last agent didn't cut corners
  11. There's no continuity. No one checking work. No context passed between agents. Each iteration burns tokens re-discovering what the orchestrator already knows.
  12. ## A Different Approach
  13. Swarms takes lessons from simple loops and more complex multi-agent systems, packaging them into something effective and beginner-friendly.
  14. The key insight: **an orchestrator that plans the work should also coordinate the execution**. It already has the complete picture: codebase research, documentation, clarified requirements, a reviewed plan. Why throw that away?
  15. ### How It Works
  16. **Phase 1: Planning** (`/swarm-planner`)
  17. <img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/27fc3022-bf7e-41b8-a805-0e3092d99fcf" />
  18. The planner researches your codebase, fetches current library docs via Context7, asks clarifying questions when it detects ambiguity, and produces a dependency-aware plan. Before finishing, it spawns a subagent to review the plan for gaps.
  19. The critical addition: **explicit task dependencies**. Every task declares what it depends on, enabling the orchestrator to know exactly which tasks can run in parallel at any moment.
  20. **Phase 2: Execution** (`/parallel-task`)
  21. The orchestrator (same session that planned) parses unblocked tasks and launches subagents in parallel. Because it planned the work, it can provide each subagent with:
  22. - The plan file and structure
  23. - Exactly which files to work on
  24. - The correct filenames/paths for any dependencies and/or previous tasks
  25. - Relevant context from the plan
  26. - What adjacent tasks are doing
  27. - Current project state with detailed logs
  28. This dramatically reduces the tokens each subagent spends on discovery. Instead of grepping, searching, and exploring, they know exactly where to go and what to build.
  29. When subagents complete, they:
  30. 1. Run validation/tests if feasible
  31. 2. Commit their work (never push: other agents are working in parallel)
  32. 3. Update the plan with status, work log, and files modified
  33. 4. Return a summary to the orchestrator
  34. The orchestrator then **verifies the work** before moving to the next wave. If something went wrong, it catches and fixes it immediately, not three tasks later when everything is tangled.
  35. This continues wave by wave until all tasks are complete.
  36. ## Why Not Just Use Ralph Loops or Gas Town?
  37. **vs. Ralph Loops**: The orchestrator maintains context across the entire project. It checks work, provides upfront context to subagents, and catches issues between waves. Simple loops have no oversight. Each agent checks its own work and hopes for the best.
  38. **vs. Complex Multi-Agent Systems**: Systems like Gas Town use families of specialized agents (context managers, commit handlers, conflict resolvers, etc.) working independently. Powerful, but complex and token-hungry. Swarms trades some parallelism for simplicity. Waves execute sequentially, but within each wave, tasks run in parallel. No scripts, no complex setup, no conflict resolution needed because dependencies are explicit.
  39. **The tradeoff**: Time. Swarms works in phases. A more complex system might have dozens of agents working simultaneously. But you'll spend fewer tokens, encounter fewer conflicts, and can actually understand what's happening.
  40. ## Skills
  41. | Skill | Description |
  42. |-------|-------------|
  43. | [swarm-planner](./skills/swarm-planner/) | Dependency-aware planning with codebase research, doc fetching, and subagent review |
  44. | [parallel-task](./skills/parallel-task/) | Wave-based execution with context handoff and work verification |
  45. ## Installation
  46. ### Claude Code
  47. ```bash
  48. npx skills add am-will/swarms
  49. ```
  50. ### Codex
  51. ```bash
  52. npx skills add am-will/swarms
  53. ```
  54. **Required: Enable Subagents**
  55. Swarms uses subagents to execute tasks in parallel. Codex CLI users must enable this experimental feature by adding the following to your `~/.codex/config.toml`:
  56. ```toml
  57. [features]
  58. multi_agents = true
  59. ```
  60. Without this setting, the parallel-task skill will not be able to spawn subagents.
  61. **Recommended: Context7 MCP**
  62. I recommend pairing Swarms with the Context7 MCP server to ensure you're using the latest libraries, APIs, and documentation during planning and implementation.
  63. For Codex, add this to your `~/.codex/config.toml`:
  64. ```toml
  65. [mcp_servers.context7]
  66. url = "https://mcp.context7.com/mcp"
  67. http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" }
  68. ```
  69. For other agents, visit https://context7.com/dashboard for setup instructions.
  70. ## Usage
  71. ### Planning
  72. **For Codex Users:**
  73. The swarm-planner skill works best when used in PLAN Mode. If you don't have plan mode enabled, it will still work, but this allows you to take advantage of Codex's new Request User Input tool, which is currently only available in Plan Mode.
  74. **Codex instructions:**
  75. ```
  76. 1. Switch to Plan Mode
  77. 2. Provide the prompt of the product/feature you want to build and call the $swarm-planner skill directly in the prompt
  78. 3. Answer any questions it asks during the planning
  79. 4. At the end of the plan, when it asks you if you want to implement this plan, press Esc
  80. 5. Switch out of Plan Mode by pressing SHIFT+TAB
  81. 6. SAVE THE PLAN to your repo. [feature/product]-plan.md
  82. 7. Continue on to Execution phase
  83. ```
  84. **Claude Code instructions:**
  85. ```
  86. 1. You don't need to switch to plan mode. You can just run the skill with your prompt.
  87. 2. /swarm-planner
  88. 3. Answer any questions it asks during planning
  89. 4. Continue on to Execution phase by calling /parallel-task skill
  90. ```
  91. The planner will:
  92. 1. Research your codebase architecture
  93. 2. Fetch current docs for libraries via Context7
  94. 3. Ask clarifying questions (with recommendations) when ambiguity exists
  95. 4. Generate a plan with explicit task dependencies
  96. 5. Spawn a subagent to review for gaps
  97. 6. Save to `<topic>-plan.md`
  98. **NOTE: Codex in Plan Mode cannot save the plan to a file. Esc out, switch to Code Mode, and ask it to save the file to your repo. Proceed to execution**
  99. ### Execution
  100. To run the swarms, simply say implement the @plan.md with the $parallel-task skill.
  101. ```
  102. Prompt: Run the plan with the $parallel-task skill
  103. ```
  104. ## Dependency Format
  105. Tasks declare dependencies explicitly:
  106. ```
  107. T1: [depends_on: []] Create database schema
  108. T2: [depends_on: []] Install packages
  109. T3: [depends_on: [T1]] Create repository layer
  110. T4: [depends_on: [T1]] Create service interfaces
  111. T5: [depends_on: [T3, T4]] Implement business logic
  112. T6: [depends_on: [T2, T5]] Add API endpoints
  113. ```
  114. This produces execution waves:
  115. | Wave | Tasks | Runs When |
  116. |------|-------|-----------|
  117. | 1 | T1, T2 | Immediately |
  118. | 2 | T3, T4 | After T1 |
  119. | 3 | T5 | After T3, T4 |
  120. | 4 | T6 | After T2, T5 |
  121. ## Plan Structure
  122. Each task in the plan includes:
  123. ```markdown
  124. ### T1: Create User Model
  125. - **depends_on**: []
  126. - **location**: src/models/user.ts
  127. - **description**: Define User entity with required fields
  128. - **validation**: Unit tests pass
  129. - **status**: Not Completed
  130. - **log**: [updated by subagent on completion]
  131. - **files edited/created**: [updated by subagent on completion]
  132. ```
  133. The `status`, `log`, and `files` fields are updated by subagents as work completes, giving the orchestrator (and you) visibility into progress.
  134. ## Example Session
  135. ```
  136. > User: Add authentication to my Express app using the swarm-planner skill.
  137. -or-
  138. > /swarm-planner add authentication to my express app.
  139. -or-
  140. > Use swarm planner skill to help me build a b2b website to sell AI agents
  141. [researches codebase, fetches Express/Passport/JWT docs]
  142. [asks: "JWT or session-based? Where should tokens be stored?"]
  143. [generates auth-plan.md with 8 dependency-ordered tasks]
  144. [subagent reviews plan, suggests adding rate limiting task]
  145. [updates plan, saves]
  146. User: looks good, execute it
  147. > /parallel-task auth-plan.md
  148. -or-
  149. > execute the plan using parallel task skill
  150. Wave 1: Launching T1 (user schema), T2 (install packages) in parallel...
  151. T1 complete - committed, plan updated
  152. T2 complete - committed, plan updated
  153. Verifying wave 1... OK
  154. Wave 2: Launching T3 (auth service), T4 (middleware) in parallel...
  155. [continues until all tasks complete]
  156. Summary: 8/8 tasks completed
  157. Files modified: src/models/user.ts, src/middleware/auth.ts, ...
  158. ```
  159. ## License
  160. MIT
skills/parallel-task-tmux/scripts/tmux_run_codex_task.sh · Bundled script · 79 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. set -u -o pipefail
  3. usage() {
  4. cat <<'EOF'
  5. Usage:
  6. tmux_run_codex_task.sh \
  7. --workspace <path> \
  8. --task-id <id> \
  9. --prompt-file <file> \
  10. --log-file <file> \
  11. --status-file <file>
  12. EOF
  13. }
  14. workspace=""
  15. task_id=""
  16. prompt_file=""
  17. log_file=""
  18. status_file=""
  19. while [[ $# -gt 0 ]]; do
  20. case "$1" in
  21. --workspace)
  22. workspace="${2:-}"
  23. shift 2
  24. ;;
  25. --task-id)
  26. task_id="${2:-}"
  27. shift 2
  28. ;;
  29. --prompt-file)
  30. prompt_file="${2:-}"
  31. shift 2
  32. ;;
  33. --log-file)
  34. log_file="${2:-}"
  35. shift 2
  36. ;;
  37. --status-file)
  38. status_file="${2:-}"
  39. shift 2
  40. ;;
  41. -h|--help)
  42. usage
  43. exit 0
  44. ;;
  45. *)
  46. echo "Unknown argument: $1" >&2
  47. usage >&2
  48. exit 1
  49. ;;
  50. esac
  51. done
  52. if [[ -z "$workspace" || -z "$task_id" || -z "$prompt_file" || -z "$log_file" || -z "$status_file" ]]; then
  53. usage >&2
  54. exit 1
  55. fi
  56. if [[ ! -f "$prompt_file" ]]; then
  57. echo "Prompt file not found: $prompt_file" >&2
  58. exit 1
  59. fi
  60. mkdir -p "$(dirname "$log_file")" "$(dirname "$status_file")"
  61. start_ts="$(date -Is)"
  62. rc=0
  63. (
  64. cd "$workspace" || exit 1
  65. codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --cd "$workspace" - < "$prompt_file" 2>&1 | tee "$log_file"
  66. ) || rc=$?
  67. end_ts="$(date -Is)"
  68. printf '%s|%s|%s|%s|%s\n' "$task_id" "$rc" "$start_ts" "$end_ts" "$log_file" >> "$status_file"
  69. exit "$rc"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.