Contributing

Contributing

We welcome contributions to Kollab CLI! This guide covers how to set up a development environment, run tests, and submit changes.

Getting Started

Clone the Repository

git clone https://github.com/kollaborai/kollab.git
cd kollab

Install Development Dependencies

pip install -e ".[dev]"

This installs Kollab in editable mode with all development dependencies including testing tools, linters, and formatters.

Requirements

  • Python 3.12+ - Required for modern async/await patterns
  • aiohttp 3.10.11+ - Async HTTP client
  • Git - For version control

Project Structure

kollab/
|-- kollabor/           # Core orchestration (application, commands, llm)
|-- packages/           # Extracted packages
|   |-- kollabor-ai/    # LLM services (kollabor_ai)
|   |-- kollabor-tui/   # Terminal UI (kollabor_tui)
|   |-- kollabor-events/# Event system (kollabor_events)
|   |-- kollabor-config/# Configuration (kollabor_config)
|   |-- kollabor-agent/ # Agent runtime (kollabor_agent)
|   |-- kollabor-plugins/ # Plugin framework (kollabor_plugins)
|   |-- kollabor-engine/  # Engine server (kollabor_engine)
|   |-- kollabor-rpc/   # RPC transport (kollabor_rpc)
|   `-- kollabor-webui/ # Web UI (kollabor_webui)
|-- plugins/            # Plugin implementations
|-- bundles/            # Agent bundles (agents + skills)
|-- docs/               # Documentation
|-- tests/              # Test suite
`-- main.py             # Application entry point

Running Tests

Run All Tests

python -m pytest tests/unit/ -x -q

Run Specific Test File

python -m unittest tests.unit.llm.test_llm_plugin

Run Individual Test Case

python -m unittest tests.unit.llm.test_llm_plugin.TestLLMPlugin.test_thinking_tags_removal

Code Quality

We use several tools to maintain code quality:

Format Code (Black)

python -m black kollabor/ plugins/ tests/ main.py

Type Checking (MyPy)

python -m mypy kollabor/ plugins/

Linting (Ruff)

python -m ruff check kollabor/ packages/ plugins/

Clean Up Artifacts

python scripts/clean.py

Submitting Changes

1

Fork the Repository

Create your own fork on GitHub to work on changes.

2

Create a Feature Branch

git checkout -b issue-123-description

3

Make Your Changes

Write code, add tests, and update documentation as needed.

4

Run Quality Checks

Ensure all tests pass and code meets quality standards.

5

Submit a Pull Request

Push your branch and open a PR with a clear description of changes.

Contribution Guidelines

Code Style

  • - Follow PEP 8 with Black formatting (88 char line length)
  • - Ruff linting at 120 char line length must pass
  • - Use type hints for function signatures
  • - Write docstrings for public functions and classes
  • - Use async/await for I/O operations

Commit Messages

  • - Use clear, descriptive commit messages
  • - Start with a verb (Add, Fix, Update, Remove)
  • - Commits touching kollabor/, plugins/, or tests/ must reference a GitHub issue (fixes #123, closes #123, resolves #123)

Testing

  • - Add tests for new functionality
  • - Ensure all existing tests pass
  • - Aim for good test coverage of edge cases

Documentation

  • - Update README if adding features
  • - Add docstrings to new code
  • - Update CHANGELOG for notable changes

Getting Help

Have questions or need help? Here are some resources:

License

Kollab CLI is released under the MIT License. By contributing, you agree that your contributions will be licensed under the same license.

Thank You!

We appreciate your interest in contributing to Kollab CLI. Every contribution, whether it's code, documentation, bug reports, or feature suggestions, helps make the project better for everyone.