crewAI/.github/CONTRIBUTING.md

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 for package management
• pre-commit for Git hooks

Setup

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:

<type>/<short-description>

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:

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:

<type>(<optional scope>): <lowercase description>

• 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 #<issue-number>
• Explain how the implementation meets the issue's acceptance criteria
• Include the automated and manual verification performed

Testing

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

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

# Add a runtime dependency to crewai
uv add --package crewai <package>

# Add a dev dependency to the workspace
uv add --dev <package>

# Sync after changes
uv sync

Do not use pip directly.

Reporting Issues

Use the GitHub issue templates:

• 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.