Contributing to Swarms

September 10, 2026 · View on GitHub

The Enterprise-Grade Production-Ready Multi-Agent Orchestration Framework

Swarms makes it simple to orchestrate agents to automate real-world work. Contributions of every size are welcome — the fastest way in is a good first issue.

Where to help	What it looks like
Tests	Cover existing code in `swarms/`, add edge cases and integration tests
Docs	Fix docstrings, add examples to `examples/`, expand `docs/`
Swarm architectures	New multi-agent orchestration methods in `swarms/structs/`
Agents	New or improved specialized agents (finance, medical, code, research)
Cleanup	Delete dead code, remove duplicate implementations, simplify functions
Performance	Faster, cheaper swarm execution

Good First Issues · Contributing Board

Setup

git clone https://github.com/kyegomez/swarms.git
cd swarms
pip install -e .          # or: uv pip install -e .

Create a .env in the project root:

OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
WORKSPACE_DIR="agent_workspace"

Environment setup docs →

Layout: swarms/agents/ (agents) · swarms/structs/ (swarms + workflows) · swarms/tools/ · swarms/prompts/ · swarms/utils/ · examples/ · tests/ (mirrors swarms/) · docs/

Reporting Issues

Search existing issues first. If it's new, open a Bug Report or Feature Request with a concise title, steps to reproduce, expected vs. actual behavior, and logs. Label it appropriately.

WARP Git Messages

Every commit message, PR title and issue title in this repository must use the WARP (Warp Speed Protocol) shorthand. This applies to people and to AI agents alike.

[TYPE][Function/FileName][Short Description]

TYPE: what kind of change it is, in capitals, for example FEAT, FIX, DOCS, REFACTOR, TEST, CHORE.
Function/FileName: the function, class, module or file the change is about.
Short Description: one line, imperative, saying what changed.

[FIX][Agent._run][Raise AgentLLMError after retry exhaustion]
[FEAT][MCPDeployer][Serve several agents as separate tools]
[DOCS][README][Add the MCPDeployer section]

The full specification, with the type list, validation rules and examples, is the WARP Git Message Skill on the Swarms marketplace. Agents can load it directly; humans can read it.

Issues and PRs that do not follow WARP are triaged after the ones that do, so expect a delay on review and merge if it is not used.

Pull Requests

git checkout -b fix/short-description
# make the change, add a test
pytest tests/
git commit -am "[FIX][Y][Fix X]"
git push origin fix/short-description

Then open the PR against master with a WARP title, describe the problem it solves, and link the issue (Fixes #1234).

Keep PRs short and simple

Review capacity is the bottleneck. PR size is the biggest factor in how fast your work merges — a small, obvious PR merges in hours; a large one can sit for weeks.

Scope

One PR, one change: one bug fix, one feature, or one refactor. Find a second problem? Open a second PR.
Fewer files is better. Multi-file PRs take significantly longer to review — the reviewer has to hold the whole change at once.
Split large work into a sequence of small PRs that each stand alone and each leave the codebase working.
No drive-by changes: don't mix reformatting, renames, dependency bumps, or unrelated cleanups into a functional PR.
Don't reformat files you're editing. Change only the lines you need to; whitespace churn hides the real fix.

Size

Diff	Expectation
< ~100 lines	Ideal — reviewed quickly
100–300 lines	Fine if it's one coherent change
> ~300 lines	Slow review, or a request to split
Many unrelated files	Likely asked to split before review

Code

Smallest change that fixes the problem. Don't rewrite code you happen to be near.
Reuse what exists instead of adding a parallel implementation.
No speculative abstraction — no options or hooks for cases nobody asked for.
No new dependencies unless unavoidable; justify them in the description.
Delete dead code rather than deprecating it, in its own PR.

Before opening

Diff contains only changes related to the stated purpose
No large comment blocks or commented-out code
Test added; pytest tests/ passes
black / flake8 clean, no unrelated reformatting
Description explains the problem and links the issue

A small, focused PR merges faster than a large one — even when the large one is better work.

Coding Standards

Type annotations on every function and method.
Docstrings on every public class, function, and method (Google style or NumPy): description, Args, Returns, Raises.
Tests for every feature and bug fix, in tests/ mirroring swarms/. Run with pytest tests/.
Style: PEP 8, enforced with black and flake8. Match the surrounding code.
Docs: update docs/ when you change the public API.

Comments

Write code that explains itself; comment only what it can't.

No multi-line comment blocks — no banners, section dividers, ASCII art, or multi-paragraph explanations. Explanation belongs in the docstring.
One short line for a non-obvious decision is the right size.
No commented-out code — git history keeps it.
Don't restate the code (# loop over agents above a for loop).

# Bad — a block that restates the code and goes stale
# ------------------------------------------------------------
# This function takes a list of agents and runs each of them
# against the provided task, collecting the results into a
# list which is then returned to the caller.
# ------------------------------------------------------------
def run_all(agents: List[Agent], task: str) -> List[str]:
    return [agent.run(task) for agent in agents]

# Good — docstring for the contract, a comment only for the surprise
def run_all(agents: List[Agent], task: str) -> List[str]:
    """Run ``task`` on each agent and return their outputs in order."""
    # Sequential on purpose: agents share a rate-limited client.
    return [agent.run(task) for agent in agents]

Resources


Docs	docs.swarms.world · Quickstart · Agent API
Examples	examples/ — single_agent, multi_agent, tools
Architectures	SequentialWorkflow · AgentRearrange · MixtureOfAgents · GraphWorkflow · GroupChat · SwarmRouter
Community	Discord · Twitter · LinkedIn · YouTube · Events · Blog
Onboarding	Book a session with the maintainer

Be respectful, give and take feedback openly, and collaborate. See CODE_OF_CONDUCT.md.

Contributions are licensed under the Apache License. If you use Swarms in research, cite it via CITATION.cff.

Happy contributing! 🚀