> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to Goose

> How to contribute to the Goose AI agent framework

Goose is open source and welcomes contributions from the community! This guide will help you get started with contributing code, documentation, and more.

## Before You Start

### Quick Responsible AI Tips

If you use Goose, Copilot, Claude, or other AI tools to help with your PRs:

**Good Uses:**

* Boilerplate code and common patterns
* Test generation
* Docs and comments
* Refactoring for clarity
* Utility functions/helpers

**Avoid AI For:**

* Security-critical logic
* Complex business rules you don't understand
* Large architectural or schema changes

**Quality Checklist:**

* Understand every line of code you submit
* All tests pass locally
* Code follows Goose's patterns
* Document your changes
* Ask for review if security or core code is involved

Full guide: [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/HOWTOAI.md)

## Getting Started

### Opening Issues

We recommend opening an issue before starting work on larger features or changes. This helps ensure:

* The feature aligns with project goals
* No one else is already working on it
* You get early feedback on your approach

For small fixes and improvements, feel free to open a PR directly.

### Creating a Fork

1. Go to [https://github.com/block/goose](https://github.com/block/goose) and click "Fork" (top-right corner)
2. Clone your fork (not the main repo):

```bash theme={null}
git clone https://github.com/<your-username>/goose.git
cd goose
```

3. Add the main repository as upstream:

```bash theme={null}
git remote add upstream https://github.com/block/goose.git
```

4. Create a branch for your changes:

```bash theme={null}
git checkout -b my-feature-branch
```

### Keeping Your Fork Up-to-Date

Sync your fork regularly to avoid conflicts:

```bash theme={null}
# Fetch latest changes
git fetch upstream

# Merge into your local branch
git checkout main
git merge upstream/main

# Push to your fork
git push origin main
```

Before submitting a PR, ensure your fork is synchronized with the latest from main.

## Making Changes

See the [Development Setup](/development/setup) guide for setting up your environment.

### Code Quality Standards

**Comments:**

* Write self-documenting code - prefer clear names over comments
* Never add comments that restate what code does
* Only comment for complex algorithms, non-obvious business logic, or "why" not "what"
* No comments on self-evident operations, getters/setters, constructors, or standard Rust idioms

**Simplicity:**

* Don't make things optional that don't need to be - the compiler will enforce
* Booleans should default to false, not be optional
* Avoid overly defensive code - trust Rust's type system

**Errors:**

* Use `anyhow::Result` for error handling
* Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed)

**Logging:**

* Clean up existing logs, don't add more unless for errors or security events

### Before Submitting

Run all checks locally:

```bash theme={null}
cargo fmt                              # Format code
cargo clippy --all-targets -- -D warnings  # Run linter
cargo test                             # Run tests
```

If you modified the server API:

```bash theme={null}
just generate-openapi
```

## Submitting Your PR

### Commit Messages

This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for PR titles:

* `feat:` New feature
* `fix:` Bug fix
* `docs:` Documentation changes
* `refactor:` Code refactoring
* `test:` Adding or updating tests
* `chore:` Maintenance tasks

Examples:

* `feat: add support for custom MCP servers`
* `fix: resolve token count estimation error`
* `docs: update provider configuration guide`

### Developer Certificate of Origin

All commits must include a sign-off using the `--signoff` or `-s` flag:

```bash theme={null}
git commit --signoff -m "feat: add new feature"
# OR
git commit -s -m "feat: add new feature"
```

This indicates you are allowed to make the contribution and that the project has the right to distribute it under its license.

### Opening the Pull Request

1. Push your branch to your fork:

```bash theme={null}
git push origin my-feature-branch
```

2. Go to [https://github.com/block/goose](https://github.com/block/goose) and click "New Pull Request"
3. Select your fork and branch
4. Fill out the PR template with:
   * Clear description of changes
   * Motivation and context
   * How to test
   * Any breaking changes

## Other Ways to Contribute

Beyond code, there are many ways to contribute:

* **Stars on GitHub:** Star the project if you find it valuable
* **Ask Questions:** Help others by answering questions on [Discord](https://discord.gg/goose-oss)
* **Give Feedback:** [Open an issue](https://github.com/block/goose/issues/new/choose) or [start a discussion](https://github.com/block/goose/discussions)
* **Participate in Events:** Join community events on Discord
* **Improve Documentation:** Enhance existing docs or add new pages
* **Help Other Members:** Answer questions, review PRs
* **Showcase Your Work:** Share projects in [#share-your-work](https://discord.com/channels/1287729918100246654/1287729920797179958)
* **Spread the Word:** Share Goose on social media

## Getting Help

If you have questions or need help:

* Join our [Discord](https://discord.gg/goose-oss)
* [Open an issue](https://github.com/block/goose/issues)
* [Start a discussion](https://github.com/block/goose/discussions)

We're here to help you succeed!