Skip to content

Contributing to Consoul

Thank you for your interest in contributing! We're excited to have you join our community. Everyone is welcome to contribute, whether you're fixing bugs, adding features, or improving documentation.

Architecture Overview

Consoul uses a three-layer architecture to separate concerns and enable headless SDK usage:

  • SDK Layer (src/consoul/sdk/, src/consoul/ai/) - Headless services with no UI dependencies
  • TUI Layer (src/consoul/tui/) - Textual-based terminal interface
  • CLI Layer (src/consoul/cli/) - Command-line argument parsing

Key principle: Business logic belongs in the SDK layer. UI code should only handle presentation.

For detailed architecture documentation, see development/architecture.md.

Getting Started

Start with a Fork

Feel free to fork this repository if you want to make substantial changes. This lets you tweak the project as much as you like in your own version while still allowing you to contribute back to the main project.

Making Contributions

  1. Agree to Our Contributor License Agreement (CLA): Before your contributions can be accepted, please sign our CLA. This ensures there are no legal hitches with your submissions.

  2. Make Your Changes: Work on your forked version of the repository and make your changes. Try to keep your updates clear and stick to the project's existing style as much as you can.

  3. Submit a Pull Request: Once you're ready, send us a pull request. Describe what you've done and how it affects the project. We're eager to see your ideas!

Pull Request Checklist

Before submitting, ensure your PR meets these requirements:

  • Layer Separation: No TUI/CLI imports in SDK layer (src/consoul/sdk/, src/consoul/ai/)
  • Tests: Unit tests for services, integration tests for UI components
  • Type Hints: All public APIs have proper type annotations
  • Documentation: Docstrings for new public functions/classes
  • Pre-commit: All pre-commit hooks pass (make pre-commit)
  • Quality Checks: Code passes linting and formatting (make quality)

What Happens Next?

We'll review your pull request as soon as we can. We appreciate every contribution, but sometimes changes might not align perfectly with our project's direction. We'll discuss potential adjustments with you, so your hard work can still be part of the project.

Keep Your Fork Updated

Even if your changes don't make it into the project, keep your fork active! Your unique tweaks could inspire others, and you might find ways to integrate your changes over time.

Got Questions or Suggestions?

If you have questions or suggestions, please open an issue in the repository. We're always looking to improve and love hearing from the community.

Thank you for helping us make this project better. We can't wait to see what you bring to the table!