# Contributing Thanks for helping improve Free Claude Code. Keep changes focused, test the behavior you change, and preserve the public Claude Code and Codex workflows. ## Before Opening A Pull Request - Standalone documentation PRs are reserved for the repository owner. - Include relevant README and other documentation updates with production code changes. These accompanying updates do not require a separate issue. - Do not open Docker integration pull requests. - For bugs, include every model mapping, the active model when the failure occurred, the complete error, and reproducible steps. - Add focused tests for behavior changes and relevant edge cases. ## Pull Request Titles Changes to `assets/`, `scripts/`, `src/`, `pyproject.toml`, or `uv.lock` require a title starting with `patch: `, `minor: `, or `major: ` followed by a description. Use exactly one space after the colon. PRs without changes to those paths must not use a release prefix. Do not edit version numbers. Publishing calculates the version after merge, creates its Git tag, and publishes to PyPI and GitHub Releases. ## Development Setup Install [uv](https://docs.astral.sh/uv/), then run directly from the checkout. uv automatically installs the Python version required by the project. ```bash git clone https://github.com/Alishahryar1/free-claude-code.git cd free-claude-code uv run fcc-server ``` Use `uv run` for Python commands. Do not run the project with a global Python interpreter. ## Quality Checks Run the complete local CI sequence before opening a pull request: ```bash ./scripts/ci.sh ``` ```powershell .\scripts\ci.ps1 ``` Useful iteration flags are `--only`, `--skip`, and `--dry-run` on macOS/Linux, or `-Only`, `-Skip`, and `-DryRun` in PowerShell. Individual repair and test commands: ```bash uv run ruff format uv run ruff check --fix uv run ty check uv run pytest -v --tb=short ``` GitHub CI runs Ruff in check-only mode and also bans `# type: ignore`, `# ty: ignore`, and legacy annotation workarounds. Fix underlying typing and import-boundary problems instead of suppressing them. ## Project Standards - Target Python 3.14 and rely on native lazy annotations; do not add `from __future__ import annotations`. - Python 3.14 supports multiple exception types without parentheses, such as `except TypeError, ValueError:`. - Keep shared Anthropic protocol behavior under `src/free_claude_code/core/anthropic/` rather than importing utilities from another provider. - Keep provider-specific configuration in the provider that owns it. - Remove dead compatibility code when completing migrations unless preserving a published interface is explicitly required.