> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Repository

> Learn how to use GitHub to report issues, request features, and contribute to Swarms

## Swarms on GitHub

The Swarms framework is developed openly on GitHub. This is where you can view the source code, report bugs, request features, and contribute to the project.

<Card title="Visit Repository" icon="github" href="https://github.com/kyegomez/swarms">
  View the Swarms source code and contribute on GitHub
</Card>

## Reporting Issues

Found a bug or problem? Here's how to report it effectively:

### Before Reporting

1. **Search Existing Issues**: Check if someone has already reported the issue
   * [Search open issues](https://github.com/kyegomez/swarms/issues)
   * Check closed issues too - your issue may have been resolved

2. **Verify It's a Bug**: Make sure it's actually a bug and not expected behavior
   * Check the [documentation](https://docs.swarms.world)
   * Look at the [examples](https://github.com/kyegomez/swarms/tree/master/examples)
   * Ask in [Discord](https://discord.gg/EamjgSaEQf) if you're unsure

### Creating a Bug Report

When creating a bug report, include:

1. **Clear Title**: A concise summary of the issue
   * Good: "Agent fails when using tools with streaming enabled"
   * Bad: "Agent broken"

2. **Description**: Detailed information about the bug
   * What you were trying to do
   * What you expected to happen
   * What actually happened

3. **Steps to Reproduce**: Exact steps to reproduce the issue
   ```
   1. Create an agent with model_name="gpt-5.4"
   2. Enable streaming with stream=True
   3. Add a tool to the agent
   4. Run the agent with a task
   5. Observe the error
   ```

4. **Code Sample**: Minimal reproducible example
   ```python theme={null}
   from swarms import Agent

   agent = Agent(
       agent_name="TestAgent",
       model_name="gpt-5.4",
       stream=True
   )

   # This causes the error
   result = agent.run("Test task")
   ```

5. **Error Messages**: Include the full error message and stack trace
   ```
   Traceback (most recent call last):
     File "test.py", line 8, in <module>
       result = agent.run("Test task")
     ...
   AttributeError: 'NoneType' object has no attribute 'run'
   ```

6. **Environment Information**:
   * Operating System (e.g., macOS 14.0, Ubuntu 22.04, Windows 11)
   * Python version (e.g., 3.10.5)
   * Swarms version (e.g., 6.5.0)
   * Relevant dependency versions

7. **Additional Context**: Screenshots, logs, or other helpful information

### Using Issue Templates

Swarms provides issue templates to help you structure your report:

* [**Bug Report Template**](https://github.com/kyegomez/swarms/issues/new?template=bug_report.md)
* [**Feature Request Template**](https://github.com/kyegomez/swarms/issues/new?template=feature_request.md)

## Requesting Features

Have an idea for a new feature? Here's how to request it:

### Before Requesting

1. **Check Existing Requests**: Search for similar feature requests
2. **Review the Roadmap**: Check the [project board](https://github.com/users/kyegomez/projects/1)
3. **Discuss on Discord**: Get community feedback on [Discord](https://discord.gg/EamjgSaEQf)

### Creating a Feature Request

Include the following in your feature request:

1. **Clear Title**: Describe the feature concisely
   * Good: "Add support for async agent execution"
   * Bad: "Make it better"

2. **Problem Statement**: Explain the problem this feature solves
   ```
   Currently, agents can only run synchronously, which limits performance
   when orchestrating multiple agents that could work in parallel.
   ```

3. **Proposed Solution**: Describe how you envision the feature working
   ```python theme={null}
   # Example of desired API
   async def run_agents():
       agent1 = Agent(agent_name="Agent1")
       agent2 = Agent(agent_name="Agent2")
       
       results = await asyncio.gather(
           agent1.run_async("Task 1"),
           agent2.run_async("Task 2")
       )
       return results
   ```

4. **Alternatives Considered**: Other approaches you've thought about

5. **Use Cases**: Real-world scenarios where this would be useful

6. **Benefits**: How this feature would improve Swarms

## Contributing Code

### Getting Started

1. **Fork the Repository**: Create your own copy
   * Click the "Fork" button on [GitHub](https://github.com/kyegomez/swarms)

2. **Clone Your Fork**: Download to your local machine
   ```bash theme={null}
   git clone https://github.com/YOUR_USERNAME/swarms.git
   cd swarms
   ```

3. **Set Up Development Environment**: Follow the [development setup guide](/community/development-setup)

### Making Changes

1. **Create a Branch**: Use a descriptive name
   ```bash theme={null}
   git checkout -b feature/add-async-support
   ```

2. **Make Your Changes**: Follow the [coding standards](/community/contributing#coding-standards)

3. **Write Tests**: Ensure your changes are tested
   ```bash theme={null}
   pytest tests/
   ```

4. **Update Documentation**: Document your changes

### Submitting a Pull Request

1. **Push Your Changes**:
   ```bash theme={null}
   git push origin feature/add-async-support
   ```

2. **Create Pull Request**: On GitHub, click "New Pull Request"

3. **Fill Out PR Template**: Provide:
   * **Description**: What changes you made and why
   * **Related Issues**: Link to related issues (e.g., "Fixes #123")
   * **Type of Change**: Bug fix, new feature, documentation, etc.
   * **Testing**: How you tested your changes
   * **Screenshots**: If applicable

4. **Wait for Review**: Maintainers will review your PR
   * Be responsive to feedback
   * Make requested changes promptly
   * Keep the conversation professional

### PR Best Practices

<AccordionGroup>
  <Accordion title="Keep PRs Small and Focused">
    * One feature or bug fix per PR
    * Easier to review and merge
    * Faster feedback cycle
  </Accordion>

  <Accordion title="Write Clear Commit Messages">
    ```bash theme={null}
    # Good
    git commit -m "Add async support for agent execution"

    # Bad
    git commit -m "updates"
    ```
  </Accordion>

  <Accordion title="Include Tests">
    * All new features need tests
    * Bug fixes should include regression tests
    * Maintain or improve code coverage
  </Accordion>

  <Accordion title="Update Documentation">
    * Update docstrings
    * Add examples if needed
    * Update relevant docs pages
  </Accordion>
</AccordionGroup>

## Finding Issues to Work On

### Good First Issues

New to contributing? Start here:

* [**Good First Issues**](https://github.com/kyegomez/swarms/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
* Specifically selected for newcomers
* Well-documented and scoped
* Mentorship available

### Help Wanted

Looking for more challenging issues?

* [**Help Wanted Issues**](https://github.com/kyegomez/swarms/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
* Issues where maintainers need assistance
* More complex problems
* High impact on the project

### Project Board

View the project roadmap and current priorities:

* [**Contributing Board**](https://github.com/users/kyegomez/projects/1)
* See what's being worked on
* Find areas that need help
* Participate in planning discussions

## GitHub Workflow

### Issue Labels

Understand what labels mean:

* `bug`: Something isn't working
* `enhancement`: New feature or request
* `documentation`: Improvements or additions to documentation
* `good first issue`: Good for newcomers
* `help wanted`: Extra attention is needed
* `question`: Further information is requested
* `wontfix`: This will not be worked on

### Milestones

Issues are organized into milestones representing releases:

* View [active milestones](https://github.com/kyegomez/swarms/milestones)
* See what's planned for upcoming releases
* Track progress toward release goals

## Repository Structure

```
swarms/
├── swarms/              # Main package source code
│   ├── agents/          # Agent implementations
│   ├── structs/         # Swarm structures
│   ├── tools/           # Tool implementations
│   └── utils/           # Utility functions
├── examples/            # Example scripts
├── tests/               # Test suite
├── docs/                # Documentation
├── CONTRIBUTING.md      # Contribution guidelines
├── CODE_OF_CONDUCT.md   # Code of conduct
└── README.md            # Project README
```

## Getting Help with GitHub

Need help with the GitHub workflow?

* Ask in the [#contributors channel on Discord](https://discord.gg/EamjgSaEQf)
* Check the [GitHub documentation](https://docs.github.com)
* Schedule an [onboarding session](https://cal.com/swarms/swarms-onboarding-session)

## Recognition

Your contributions are valued and recognized:

### Contributors Wall

All contributors are featured in the README:

<a href="https://github.com/kyegomez/swarms/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=kyegomez/swarms" />
</a>

### Community Acknowledgment

* Featured in release notes
* Mentioned in community calls
* Recognition on social media

<Card title="Start Contributing Today" icon="code-pull-request">
  Visit the [Contributing Guide](/community/contributing) to learn more about how you can contribute to Swarms!
</Card>