am-will/swarms — Summary

Swarms by am-will is a two-skill pack (swarm-planner + parallel-task) for Claude Code and Codex that solves the "bash loop" multi-agent problem: rather than each agent rediscovering state from scratch, the orchestrator that planned the work also coordinates execution. The framework ships 7 SKILL.md files installed via npx skills add am-will/swarms, uses explicit task dependency graphs (T1/T2/T3 notation with depends_on arrays) to produce execution waves, and has the orchestrator independently verify each wave before advancing. With 203 stars, it is the lightest framework in this batch by component count — just 2 core skills plus 5 variants (co-design, spark variants, super-swarm variants). Closest seed comparison: resembles agent-os (minimal file-based) in its lightweight design, but adds dependency-aware parallel execution that agent-os lacks; differs from claude-flow in having no MCP server, no persistent memory, and no hive-mind protocol — it is purely a planning+execution skill layer.

am-will/swarms — Overview

Origin

Created by am-will. Single contributor. 203 stars. Multi-agent orchestration focused on solving the "simple loop" problem in AI coding agents.

Philosophy

"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?"

"Each new agent session starts fresh. It has to: Re-read the same prompt as every previous iteration; Discover the current project state through exploration; Figure out what comes next by inspecting previous work; Hope the last agent didn't cut corners. There's no continuity. No one checking work. No context passed between agents."

Core Thesis

Plain bash loops waste tokens on re-discovery. Swarms keeps the orchestrator's context alive across execution waves, pre-loading each subagent with exactly what it needs to know.

Tradeoff Acknowledgment

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

Comparison with Alternatives

• vs Ralph Loops: Swarms maintains orchestrator context + verifies between waves; loops have no oversight
• vs Gas Town (complex multi-agent): Swarms trades some parallelism for simplicity; waves execute sequentially, tasks within a wave run in parallel; no scripts needed, no conflict resolution

Recommended Pairing

Context7 MCP for library documentation during planning phase.

am-will/swarms — Architecture

Distribution

• Skill pack installed via npx skills add am-will/swarms
• No npm package; no CLI binary; no MCP server

Install

# Claude Code
npx skills add am-will/swarms

# Codex  
npx skills add am-will/swarms
# Then add to ~/.codex/config.toml:
# [features]
# multi_agents = true

Required Runtime

• Claude Code or Codex CLI
• For Codex: multi_agents = true feature flag required

Directory Tree

swarms/
├── skills/
│   ├── swarm-planner/
│   │   └── SKILL.md
│   ├── parallel-task/
│   │   └── SKILL.md
│   ├── parallel-task-spark/
│   │   └── SKILL.md
│   ├── parallel-task-tmux/
│   │   └── SKILL.md
│   ├── super-swarm/
│   │   └── SKILL.md
│   ├── super-swarm-spark/
│   │   └── SKILL.md
│   └── co-design/
│       └── SKILL.md
└── README.md

Target AI Tools

• Claude Code (primary)
• Codex CLI (supported with feature flag)

State Storage

Plan file: <topic>-plan.md in project root (written by swarm-planner)
No persistent state directory; plan file is the only artifact.

am-will/swarms — Components

Skills (7 total)

No CLI, No Hooks, No MCP

This framework has no:

• CLI binary
• Lifecycle hooks
• MCP servers
• Agent persona files
• Scripts

It is purely skill instructions.

Dependency Format (from parallel-task SKILL.md)

T1: [depends_on: []] Create database schema
T2: [depends_on: []] Install packages
T3: [depends_on: [T1]] Create repository layer
T4: [depends_on: [T1]] Create service interfaces
T5: [depends_on: [T3, T4]] Implement business logic
T6: [depends_on: [T2, T5]] Add API endpoints

Wave Execution Example

Plan Structure (per task)

### T1: Create User Model
- **depends_on**: []
- **location**: src/models/user.ts
- **description**: Define User entity
- **validation**: Unit tests pass
- **status**: Not Completed
- **log**: [updated by subagent on completion]
- **files edited/created**: [updated by subagent on completion]

am-will/swarms — Uniqueness

Differs From Seeds

Most similar to agent-os (minimal, file-based, no binary) but adds dependency-aware parallel execution that agent-os lacks. The explicit DAG-based task dependency format (T1/T2/T3 with depends_on arrays) is similar to taskmaster-ai's task decomposition, but Swarms keeps the orchestrator alive across all waves (context persistence) while taskmaster uses stateless MCP tools. Differs from claude-flow in having zero MCP infrastructure, zero persistent memory, and no hive-mind protocol — it is the lightest multi-agent framework in this batch. The critical innovation over all seeds: the orchestrator that planned the work STAYS ALIVE during execution, pre-loading each subagent with precisely the context it needs rather than requiring re-discovery.

Positioning

• Smallest surface area of multi-agent frameworks in batch (2 core skills + 5 variants)
• Explicitly positioned against "bash loop" approaches (Ralph loops, Gas Town)
• Clear articulation of the discovery-waste problem in naive loops
• TDD first enforcement in subagent prompts (tdd_test_writer subagent for RED phase)

Observable Failure Modes

• No worktree isolation: parallel commits to same branch can create merge conflicts if subagents touch same files
• Context limit: orchestrator holds all context from planning through execution — large projects may hit limits
• Codex feature flag dependency: multi_agents = true must be explicitly set for Codex
• Plan file is single point of failure: if corrupted or lost, no other state exists
• No retry logic: if a subagent fails, the plan documents it but orchestrator has no automated recovery

Cross-References

The README explicitly mentions comparing favorably to "Gas Town" (possibly claude-flow) and "Ralph Loops" (a common Codex loop pattern also referenced in oh-my-codex).