alishahryar1--free-claude-code
Ali Khokhar
3c9d0ced76
## Problem The README mixed customer setup with provider internals and contributor guidance, making installation and everyday usage harder to scan. ## Changes | Before | After | | --- | --- | | Customer setup was spread across a 725-line README. | Customer setup follows a clear install, configure, run, connect, and manage flow. | | Providers used long implementation-oriented sections. | All 24 providers use a compact configuration table with essential notes. | | Secondary clients and integrations filled the main scan path. | Secondary clients and integrations use collapsible usage guides. | | Development and contribution guidance lived in the customer README. | Contributor guidance lives in `CONTRIBUTING.md`, with architecture linked separately. | | Internal capabilities were classified as README claims. | Internal capabilities are classified as public-surface coverage and provider documentation is contract-tested. | | README simplification risked removing project identity and social proof. | Existing badges, screenshot gallery, and Star History remain. | <!-- greptile_comment --> <details open><summary><h3>Greptile Summary</h3></summary> This PR simplifies the customer README and moves contributor guidance into a dedicated file. The main changes are: - Shorter Quick Start, provider, client, integration, and management sections in `README.md`. - New `CONTRIBUTING.md` with setup, checks, standards, and versioning guidance. - Feature coverage reclassified from README claims to public-surface coverage. - A contract test for keeping the README provider table aligned with the provider catalog. </details> <h3>Confidence Score: 5/5</h3> This looks safe to merge. No blocking issues found in the changed code. No files need attention. <details><summary><h3><a href="https://www.greptile.com/trex"><img alt="T-Rex" src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg" height="20" align="absmiddle"></a> T-Rex Logs</h3></summary> **What T-Rex did** - Ran the Pytest-based docs contract checks and captured a log that records the Pytest command, working directory, output, and exit code 0. - Ran the Ruff-based docs contract validation and captured a log that records the Ruff command, working directory, output, and exit code 0. <a href="https://app.greptile.com/trex/runs/13926440/artifacts"><picture><source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=4"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"><img alt="View all artifacts" src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"></picture></a> <sub><a href="https://www.greptile.com/trex"><img alt="T-Rex" src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg" height="14" align="absmiddle"></a> Ran code and verified through T-Rex</sub> </details> <details open><summary><h3>Important Files Changed</h3></summary> | Filename | Overview | |----------|----------| | README.md | Reworked the README into a shorter customer setup and usage guide. | | CONTRIBUTING.md | Added contributor setup, quality checks, project standards, and versioning guidance. | | smoke/features.py | Moved several feature entries from README coverage to public-surface coverage. | | tests/contracts/test_feature_manifest.py | Added a provider table contract test against the provider catalog. | </details> <sub>Reviews (1): Last reviewed commit: ["Simplify README around customer usage"](https://github.com/alishahryar1/free-claude-code/commit/ba0a7a837417b1566f071373d71ae14ecadfe5e7) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43185730)</sub> <!-- /greptile_comment -->
2.5 KiB
2.5 KiB
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
- Open an issue before proposing README changes.
- 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.
- Read ARCHITECTURE.md before changing package boundaries, providers, protocol conversion, launchers, or messaging.
Development Setup
Install uv and Python 3.14, then run directly from the checkout:
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
uv python install 3.14.0
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:
./scripts/ci.sh
.\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:
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.
Versioning
Changes to runtime code, packaging, dependencies, or install/CI scripts require a semantic version bump in pyproject.toml and a matching uv lock update in the same commit. Documentation, tests, smoke coverage, and repository configuration do not require a version bump by themselves.
See ARCHITECTURE.md for extension checklists and the full system design.