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

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 and click “Fork” (top-right corner)
2. Clone your fork (not the main repo):

git clone https://github.com/<your-username>/goose.git
cd goose

3. Add the main repository as upstream:

git remote add upstream https://github.com/block/goose.git

4. Create a branch for your changes:

git checkout -b my-feature-branch

Keeping Your Fork Up-to-Date

Sync your fork regularly to avoid conflicts:

# 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 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:

cargo fmt                              # Format code
cargo clippy --all-targets -- -D warnings  # Run linter
cargo test                             # Run tests

If you modified the server API:

just generate-openapi

Submitting Your PR

Commit Messages

This project follows Conventional Commits 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:

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:

git push origin my-feature-branch

2. Go to 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
• Give Feedback: Open an issue or start a discussion
• 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
• Spread the Word: Share Goose on social media

Getting Help

If you have questions or need help:

• Join our Discord
• Open an issue
• Start a discussion

We’re here to help you succeed!