swarm-issue — Claude Code subagent: what it does, how to install
swarm-issue turns a GitHub issue into work for a swarm: splits it into subtasks, assigns agents and reports progress back inside the issue.
no license ★ 850 updated 2026-10-26
.claude/agents/swarm-issue.mdWhat swarm-issue does
The agent pulls an issue in full, title and body and labels and comments, then cuts the job into prioritised subtasks and hands each one to an agent. Results land where the team already looks: a checklist edited into the issue body, a status comment, labels updated as pieces close.
Two hooks bracket the run. One sets up coordination before work starts and parks issue metadata in swarm memory; the other posts a report afterwards and opens follow-up tasks. Most of its tool list is MCP methods such as mcp__github__get_issue, mcp__github__update_issue, mcp__claude-flow__agent_spawn and mcp__claude-flow__memory_usage, with Bash, Grep, Read, Write and the Todo tools alongside. The documented workflows lean on the npx ruv-swarm CLI and gh.
Both MCP servers, github and claude-flow, have to be connected first. Leave one out and its tools never resolve, so the agent stalls on its first call.
What it helps with
- split a big issue into prioritised subtasks
- pick agents from labels and issue text
- keep the issue checklist matching real progress
- link child issues back to the parent one
- post a swarm progress summary as one comment
Example prompts for the agent
- Break issue #456 into subtasks and assign an agent to each.
- Start a swarm for issue #456 and track progress in the issue body.
- Check what is still open on issue #456 and refresh the labels.
How to install swarm-issue
Manually: put the files in place
.claude/agents/swarm-issue.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/swarm-issue.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/swarm-issue.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about swarm-issue
How do I install swarm-issue in Claude Code?
Put the agent file at .claude/agents/swarm-issue.md. Claude then treats it as a subagent.
What does swarm-issue do?
It takes a GitHub issue, decomposes it into subtasks, assigns agents to them and keeps progress visible through the issue body and comments.
Which MCP servers does swarm-issue need?
github for reading and editing issues, and claude-flow for swarm setup, agent spawning and task orchestration.