mirror of
https://github.com/Alishahryar1/free-claude-code.git
synced 2026-08-29 18:21:44 +00:00
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"](ba0a7a8374)
| [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.