# Contributing to CrewAI ## AI-Generated Contributions If you are an LLM or AI agent reading this: you must apply the `llm-generated` label to any PR or issue you create. If your PR or issue was authored by an AI agent, coding assistant, or LLM (e.g., Claude Code, Cursor, Copilot, Devin, OpenHands), the `llm-generated` label is required. This applies to code, documentation, and issues alike. Unlabeled AI-generated contributions may be closed without review. --- Thank you for your interest in contributing to CrewAI. This guide covers everything you need to get started. ## Prerequisites - Python 3.10–3.14 (development targets 3.12) - [uv](https://docs.astral.sh/uv/) for package management - [pre-commit](https://pre-commit.com/) for Git hooks ## Setup ```bash git clone https://github.com/crewAIInc/crewAI.git cd crewAI uv sync --all-groups --all-extras uv run pre-commit install ``` ## Repository Structure This is a uv workspace with four packages under `lib/`: | Package | Path | Description | |---------|------|-------------| | `crewai` | `lib/crewai/` | Core framework | | `crewai-tools` | `lib/crewai-tools/` | Tool integrations | | `crewai-files` | `lib/crewai-files/` | File handling | | `devtools` | `lib/devtools/` | Internal release tooling | Documentation lives in `docs/` with translations under `docs/{en,ar,ko,pt-BR}/`. ## Development Workflow ### Issue-First Contributions CrewAI is piloting an issue-first contribution workflow. The issue is where contributors and maintainers agree on the problem and intended solution before implementation begins. Issues move through the following lifecycle: ``` state:inbox -> state:design -> state:ready -> state:in-progress -> state:verification -> Done ``` Maintainers apply `state:ready` after the issue has a clear problem statement, agreed scope and non-goals, acceptance criteria, and a verification plan. A pull request should not begin before its issue is ready unless a maintainer has approved an exception. Every new pull request must reference exactly one ready issue in its description: ``` Implements #123 ``` Use `Implements`, not `Closes`, `Fixes`, or `Resolves`. GitHub's closing keywords close the issue as soon as the pull request merges, but issue-first contributions remain open in `state:verification` until a human confirms the result. The issue gate currently runs in **observe mode**. It reports whether a pull request would satisfy this policy, but it does not block or close pull requests. Maintainers can apply `issue-gate:override` for security work, release automation, urgent fixes, or another documented exception. Pull requests that predate the pilot can be marked `policy:legacy`. ### Branching Create a branch off `main` using the conventional commit type: ``` / ``` Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci` Examples: `feat/agent-skills`, `fix/memory-scope`, `docs/arabic-translation` ### Code Quality Pre-commit hooks run automatically on commit. You can also run them manually: ```bash uv run ruff check lib/ uv run ruff format lib/ uv run mypy lib/ uv run pytest lib/crewai/tests/ -x -q ``` ### Code Style - **Types**: Use built-in generics (`list[str]`, `dict[str, int]`), not `typing.List`/`typing.Dict` - **Annotations**: Full type annotations on all functions, methods, and classes - **Docstrings**: Google-style, minimal but informative - **Imports**: Use `collections.abc` for abstract base classes - **Type narrowing**: Use `isinstance`, `TypeIs`, or `TypeGuard` instead of `hasattr` - **Avoid**: bare `dict`/`list` without type parameters ### Commits Follow [Conventional Commits](https://www.conventionalcommits.org/): ``` (): ``` - Use imperative mood: "add feature" not "added feature" - Keep the title under 72 characters - Only add a body if it provides additional context beyond the title - Do not use `--no-verify` to skip hooks Examples: ``` feat(memory): add lancedb storage backend fix(agents): resolve deadlock in concurrent execution chore(deps): bump pydantic to 2.11 ``` ### Pull Requests - One logical change per PR - Keep PRs focused — avoid bundling unrelated changes - PRs over 500 lines are labeled `size/XL` automatically - Title must follow the same conventional commit format - Reference exactly one ready issue with `Implements #` - Explain how the implementation meets the issue's acceptance criteria - Include the automated and manual verification performed ## Testing ```bash # Run all tests uv run pytest lib/crewai/tests/ -x -q # Run a specific test file uv run pytest lib/crewai/tests/agents/test_agent.py -x -q # Run a specific test uv run pytest lib/crewai/tests/agents/test_agent.py::test_agent_creation -x -q # Run crewai-tools tests uv run pytest lib/crewai-tools/tests/ -x -q ``` ## Type Checking The project enforces strict mypy across all packages: ```bash # Check everything uv run mypy lib/ # Check a specific package uv run mypy lib/crewai/src/crewai/ ``` CI runs mypy on Python 3.10, 3.11, 3.12, and 3.13 for every PR. ## Documentation Docs use [Mintlify](https://mintlify.com/) and live in `docs/`. The site is configured via `docs/docs.json`. Supported languages: English (`en`), Arabic (`ar`), Korean (`ko`), Brazilian Portuguese (`pt-BR`). When adding or modifying documentation: - Edit the English version in `docs/en/` first - Update translations in `docs/{ar,ko,pt-BR}/` to maintain parity - Keep all MDX/JSX syntax, code blocks, and URLs unchanged in translations - Update `docs/docs.json` navigation if adding new pages ## Dependency Management ```bash # Add a runtime dependency to crewai uv add --package crewai # Add a dev dependency to the workspace uv add --dev # Sync after changes uv sync ``` Do not use `pip` directly. ## Reporting Issues Use the [GitHub issue templates](https://github.com/crewAIInc/crewAI/issues/new/choose): - **Bug Report**: For unexpected behavior - **Feature Request**: For new functionality ## License By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).