[Skip to content](https://github.com/Alishahryar1/free-claude-code#start-of-content)
You signed in with another tab or window. [Reload](https://github.com/Alishahryar1/free-claude-code) to refresh your session.You signed out in another tab or window. [Reload](https://github.com/Alishahryar1/free-claude-code) to refresh your session.You switched accounts on another tab or window. [Reload](https://github.com/Alishahryar1/free-claude-code) to refresh your session.Dismiss alert
{{ message }}
[Alishahryar1](https://github.com/Alishahryar1)/ **[free-claude-code](https://github.com/Alishahryar1/free-claude-code)** Public
- [Notifications](https://github.com/login?return_to=%2FAlishahryar1%2Ffree-claude-code) You must be signed in to change notification settings
- [Fork\\
6.5k](https://github.com/login?return_to=%2FAlishahryar1%2Ffree-claude-code)
- [Star\\
39.7k](https://github.com/login?return_to=%2FAlishahryar1%2Ffree-claude-code)
main
[**3** Branches](https://github.com/Alishahryar1/free-claude-code/branches) [**0** Tags](https://github.com/Alishahryar1/free-claude-code/tags)
[Go to Branches page](https://github.com/Alishahryar1/free-claude-code/branches)[Go to Tags page](https://github.com/Alishahryar1/free-claude-code/tags)
Go to file
Code
Open more actions menu
## Folders and files
| Name | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| ## Latest commit [](https://github.com/Alishahryar1)[Alishahryar1](https://github.com/Alishahryar1/free-claude-code/commits?author=Alishahryar1) [Give messaging clear exact subtree semantics (](https://github.com/Alishahryar1/free-claude-code/commit/3fba1c6fc3a6ec829770199fbf1172a620f6fcbb) [#1072](https://github.com/Alishahryar1/free-claude-code/pull/1072) [)](https://github.com/Alishahryar1/free-claude-code/commit/3fba1c6fc3a6ec829770199fbf1172a620f6fcbb) Open commit detailssuccess 9 hours agoJul 12, 2026 [3fba1c6](https://github.com/Alishahryar1/free-claude-code/commit/3fba1c6fc3a6ec829770199fbf1172a620f6fcbb) · 9 hours agoJul 12, 2026 ## History [788 Commits](https://github.com/Alishahryar1/free-claude-code/commits/main/) Open commit details [View commit history for this file.](https://github.com/Alishahryar1/free-claude-code/commits/main/) 788 Commits |
| [.github](https://github.com/Alishahryar1/free-claude-code/tree/main/.github ".github") | [.github](https://github.com/Alishahryar1/free-claude-code/tree/main/.github ".github") | [Remove legacy future annotation imports (](https://github.com/Alishahryar1/free-claude-code/commit/85b601884d57aafb082c21e68ab38787adc00d56 "Remove legacy future annotation imports (#982) ## Problem Python 3.14 provides native lazy annotations, but the codebase still relied on legacy future annotation imports. Those imports also made type-only import cycles easier to hide instead of fixing ownership boundaries. ## Changes | Before | After | | --- | --- | | Python files used `from __future__ import annotations`. | Python files rely on Python 3.14 native lazy annotations. | | Some runtime modules used `TYPE_CHECKING` or local imports for required dependencies. | Runtime modules use top-level owner-module imports with explicit boundaries. | | Local and GitHub guardrails only rejected type ignore suppressions. | Local and GitHub guardrails reject type ignore suppressions and legacy future annotation imports. | | Agent docs only documented the no-type-ignore rule. | Agent docs document the Python 3.14 annotation and import-boundary rules. |
Greptile Summary
This PR moves the codebase to Python 3.14 native lazy annotations. The main changes are: - Removed legacy `from __future__ import annotations` imports across Python modules. - Promoted selected runtime dependencies from `TYPE_CHECKING` or local imports to explicit owner-module imports. - Added local, GitHub, and contract-test guardrails to reject legacy future annotation imports. - Updated agent docs with the annotation and import-boundary rules. - Bumped the package patch version for production-file changes.
Confidence Score: 5/5
Safe to merge with low risk. The changes are mostly mechanical annotation cleanup with matching CI and contract-test guardrails. Reviewed import-boundary updates did not show a confirmed runtime cycle or dependency break. No files require special attention.
T-Rex Logs
**What T-Rex did** - Performed an end-to-end validation of the guardrail contract suite: an environment check confirmed uv availability, a guardrail pytest run used CPython 3.14.0 with 5 passing contract tests, 3 focused CI-script tests passed, and the direct CI suppressions guardrail command (including the legacy future-annotations grep) also passed. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | api/runtime.py | Moves messaging, CLI manager, session, limiter, and tree dependencies from local/type-checking imports to explicit top-level owner-module imports. | | messaging/platforms/telegram.py | Removes future annotations and promotes Telegram SDK type imports into the existing availability guard. | | messaging/platforms/telegram_inbound.py | Removes future annotations and imports Telegram SDK types at module scope for inbound normalization. | | tests/contracts/test_import_boundaries.py | Adds an AST contract that rejects legacy future annotation imports across Python files. | | scripts/ci.sh | Extends the local suppression check to reject legacy future annotation imports alongside type-ignore suppressions. | | scripts/ci.ps1 | Mirrors the local PowerShell CI suppression check for legacy future annotations. | | .github/workflows/tests.yml | Renames and broadens the GitHub guardrail job to reject both type suppressions and legacy future annotations. | | pyproject.toml | Bumps the patch version for production-file changes. |
This PR moves the codebase to Python 3.14 native lazy annotations. The main changes are: - Removed legacy `from __future__ import annotations` imports across Python modules. - Promoted selected runtime dependencies from `TYPE_CHECKING` or local imports to explicit owner-module imports. - Added local, GitHub, and contract-test guardrails to reject legacy future annotation imports. - Updated agent docs with the annotation and import-boundary rules. - Bumped the package patch version for production-file changes.
Confidence Score: 5/5
Safe to merge with low risk. The changes are mostly mechanical annotation cleanup with matching CI and contract-test guardrails. Reviewed import-boundary updates did not show a confirmed runtime cycle or dependency break. No files require special attention.
T-Rex Logs
**What T-Rex did** - Performed an end-to-end validation of the guardrail contract suite: an environment check confirmed uv availability, a guardrail pytest run used CPython 3.14.0 with 5 passing contract tests, 3 focused CI-script tests passed, and the direct CI suppressions guardrail command (including the legacy future-annotations grep) also passed. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | api/runtime.py | Moves messaging, CLI manager, session, limiter, and tree dependencies from local/type-checking imports to explicit top-level owner-module imports. | | messaging/platforms/telegram.py | Removes future annotations and promotes Telegram SDK type imports into the existing availability guard. | | messaging/platforms/telegram_inbound.py | Removes future annotations and imports Telegram SDK types at module scope for inbound normalization. | | tests/contracts/test_import_boundaries.py | Adds an AST contract that rejects legacy future annotation imports across Python files. | | scripts/ci.sh | Extends the local suppression check to reject legacy future annotation imports alongside type-ignore suppressions. | | scripts/ci.ps1 | Mirrors the local PowerShell CI suppression check for legacy future annotations. | | .github/workflows/tests.yml | Renames and broadens the GitHub guardrail job to reject both type suppressions and legacy future annotations. | | pyproject.toml | Bumps the patch version for production-file changes. |
This PR moves the codebase to Python 3.14 native lazy annotations. The main changes are: - Removed legacy `from __future__ import annotations` imports across Python modules. - Promoted selected runtime dependencies from `TYPE_CHECKING` or local imports to explicit owner-module imports. - Added local, GitHub, and contract-test guardrails to reject legacy future annotation imports. - Updated agent docs with the annotation and import-boundary rules. - Bumped the package patch version for production-file changes.
Confidence Score: 5/5
Safe to merge with low risk. The changes are mostly mechanical annotation cleanup with matching CI and contract-test guardrails. Reviewed import-boundary updates did not show a confirmed runtime cycle or dependency break. No files require special attention.
T-Rex Logs
**What T-Rex did** - Performed an end-to-end validation of the guardrail contract suite: an environment check confirmed uv availability, a guardrail pytest run used CPython 3.14.0 with 5 passing contract tests, 3 focused CI-script tests passed, and the direct CI suppressions guardrail command (including the legacy future-annotations grep) also passed. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | api/runtime.py | Moves messaging, CLI manager, session, limiter, and tree dependencies from local/type-checking imports to explicit top-level owner-module imports. | | messaging/platforms/telegram.py | Removes future annotations and promotes Telegram SDK type imports into the existing availability guard. | | messaging/platforms/telegram_inbound.py | Removes future annotations and imports Telegram SDK types at module scope for inbound normalization. | | tests/contracts/test_import_boundaries.py | Adds an AST contract that rejects legacy future annotation imports across Python files. | | scripts/ci.sh | Extends the local suppression check to reject legacy future annotation imports alongside type-ignore suppressions. | | scripts/ci.ps1 | Mirrors the local PowerShell CI suppression check for legacy future annotations. | | .github/workflows/tests.yml | Renames and broadens the GitHub guardrail job to reject both type suppressions and legacy future annotations. | | pyproject.toml | Bumps the patch version for production-file changes. |
This PR moves the codebase to Python 3.14 native lazy annotations. The main changes are: - Removed legacy `from __future__ import annotations` imports across Python modules. - Promoted selected runtime dependencies from `TYPE_CHECKING` or local imports to explicit owner-module imports. - Added local, GitHub, and contract-test guardrails to reject legacy future annotation imports. - Updated agent docs with the annotation and import-boundary rules. - Bumped the package patch version for production-file changes.
Confidence Score: 5/5
Safe to merge with low risk. The changes are mostly mechanical annotation cleanup with matching CI and contract-test guardrails. Reviewed import-boundary updates did not show a confirmed runtime cycle or dependency break. No files require special attention.
T-Rex Logs
**What T-Rex did** - Performed an end-to-end validation of the guardrail contract suite: an environment check confirmed uv availability, a guardrail pytest run used CPython 3.14.0 with 5 passing contract tests, 3 focused CI-script tests passed, and the direct CI suppressions guardrail command (including the legacy future-annotations grep) also passed. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | api/runtime.py | Moves messaging, CLI manager, session, limiter, and tree dependencies from local/type-checking imports to explicit top-level owner-module imports. | | messaging/platforms/telegram.py | Removes future annotations and promotes Telegram SDK type imports into the existing availability guard. | | messaging/platforms/telegram_inbound.py | Removes future annotations and imports Telegram SDK types at module scope for inbound normalization. | | tests/contracts/test_import_boundaries.py | Adds an AST contract that rejects legacy future annotation imports across Python files. | | scripts/ci.sh | Extends the local suppression check to reject legacy future annotation imports alongside type-ignore suppressions. | | scripts/ci.ps1 | Mirrors the local PowerShell CI suppression check for legacy future annotations. | | .github/workflows/tests.yml | Renames and broadens the GitHub guardrail job to reject both type suppressions and legacy future annotations. | | pyproject.toml | Bumps the patch version for production-file changes. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR canonicalizes provider failure handling across the API boundary. The main changes are: - Adds protocol-neutral execution failure values and safe diagnostics. - Moves SDK and HTTP failure classification into provider-owned policy. - Lets Messages and Responses choose their own wire error payloads. - Preserves canonical failures across stream cleanup and committed stream failures. - Makes incomplete Responses tool errors provisional until finalization.
Confidence Score: 5/5
This looks safe to merge. No blocking issues found in the changed code. No files need attention.
T-Rex Logs
**What T-Rex did** - Ran the API failure contract suite and related tests (tests/api/test\_execution\_failure\_contract.py, tests/core/test\_failure\_protocol\_mapping.py, tests/providers/test\_execution\_failure\_boundary.py, tests/providers/test\_failure\_policy.py); 48 passed in 3.36s. - Ran the streaming boundaries tests including response streams, stream recovery, and streaming errors; 70 passed in 5.36s. - Ran the OpenAI responses tests; 20 passed in 4.42s. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/providers/transports/http.py | Adds cleanup-safe stream closing that preserves established outcomes. | | src/free_claude_code/core/openai_responses/stream.py | Preserves canonical execution failures when committed Responses streams fail. | | src/free_claude_code/core/openai_responses/streaming/assembler.py | Keeps malformed tool-call errors provisional so later provider failures can win. | | src/free_claude_code/core/failures.py | Defines neutral failure kinds and exception-group lookup for execution failures. | Reviews (2): Last reviewed commit: [\"Preserve canonical outcomes in grouped a...\"](https://github.com/alishahryar1/free-claude-code/commit/f57f21241dbe582985627ed4fb40734b2c656809) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43468297) ") [#1046](https://github.com/Alishahryar1/free-claude-code/pull/1046) [)](https://github.com/Alishahryar1/free-claude-code/commit/e22a38b2c26f85cd9361c14c1b4c51ef4718d6fb "Canonicalize provider failure and retry ownership (#1046) ## Problem Provider SDK classification, retry policy, canonical failures, and downstream wire errors shared exception types across layers. That blurred ownership and let cleanup or provisional Responses tool failures mask the real provider diagnostic. ## Changes | Before | After | | --- | --- | | Provider failures carried Anthropic wire types and core code classified OpenAI/httpx errors. | Protocol-neutral `ExecutionFailure` values cross layers, providers classify SDK errors, and protocol packages map wire types. | | Provider adapters could author terminal wire events. | The HTTP commit boundary selects non-2xx JSON or a protocol terminal event with one ingress request ID. | | Retry policy and diagnostic handling were spread across core and provider modules. | Providers own the unchanged retry budgets while neutral core utilities own bounded credential redaction. | | Stream cleanup could replace an already-mapped provider failure. | Cleanup records safe metadata and preserves the canonical failure, status, and diagnostic. | | An incomplete Responses tool could preempt a later provider failure. | Tool-finalization errors remain provisional so canonical provider failures take precedence. | | Readiness failures reused provider exception types. | Application-owned errors represent deterministic validation and availability phases without terminal retry headers. | | Legacy exception and recovery owners remained importable. | Obsolete modules are deleted without shims, architecture rules enforce the boundaries, and package version is 3.4.21. |
Greptile Summary
This PR canonicalizes provider failure handling across the API boundary. The main changes are: - Adds protocol-neutral execution failure values and safe diagnostics. - Moves SDK and HTTP failure classification into provider-owned policy. - Lets Messages and Responses choose their own wire error payloads. - Preserves canonical failures across stream cleanup and committed stream failures. - Makes incomplete Responses tool errors provisional until finalization.
Confidence Score: 5/5
This looks safe to merge. No blocking issues found in the changed code. No files need attention.
T-Rex Logs
**What T-Rex did** - Ran the API failure contract suite and related tests (tests/api/test\_execution\_failure\_contract.py, tests/core/test\_failure\_protocol\_mapping.py, tests/providers/test\_execution\_failure\_boundary.py, tests/providers/test\_failure\_policy.py); 48 passed in 3.36s. - Ran the streaming boundaries tests including response streams, stream recovery, and streaming errors; 70 passed in 5.36s. - Ran the OpenAI responses tests; 20 passed in 4.42s. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/providers/transports/http.py | Adds cleanup-safe stream closing that preserves established outcomes. | | src/free_claude_code/core/openai_responses/stream.py | Preserves canonical execution failures when committed Responses streams fail. | | src/free_claude_code/core/openai_responses/streaming/assembler.py | Keeps malformed tool-call errors provisional so later provider failures can win. | | src/free_claude_code/core/failures.py | Defines neutral failure kinds and exception-group lookup for execution failures. | Reviews (2): Last reviewed commit: [\"Preserve canonical outcomes in grouped a...\"](https://github.com/alishahryar1/free-claude-code/commit/f57f21241dbe582985627ed4fb40734b2c656809) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43468297) ") | yesterdayJul 11, 2026 |
| [ARCHITECTURE.md](https://github.com/Alishahryar1/free-claude-code/blob/main/ARCHITECTURE.md "ARCHITECTURE.md") | [ARCHITECTURE.md](https://github.com/Alishahryar1/free-claude-code/blob/main/ARCHITECTURE.md "ARCHITECTURE.md") | [Give messaging clear exact subtree semantics (](https://github.com/Alishahryar1/free-claude-code/commit/3fba1c6fc3a6ec829770199fbf1172a620f6fcbb "Give messaging clear exact subtree semantics (#1072) ## Problem Messaging `/clear` did not follow the selected platform message boundary. Reply clears preserved the selected user prompt, while standalone clears preserved user-authored messages and could reset FCC state outside the invoking chat. ## Changes | Before | After | | --- | --- | | Reply `/clear` removed a logical conversation branch but retained the selected message. | Reply `/clear` deletes the selected message and its literal reply subtree, including the clear command. | | Standalone `/clear` retained user prompts and voice notes while resetting global messaging state. | Standalone `/clear` deletes every tracked message and resets FCC state only in the invoking platform and chat. | | Trees recorded only logical execution parentage. | Trees separately persist logical execution ancestry and exact prompt/status reply ownership. | | Clear coordination used one global admission boundary. | Per-chat clear generations coordinate admission, voice cancellation, persistence, and best-effort platform deletion. | | Persistence tracked only FCC-authored clearable output. | Persistence tracks managed inbound and outbound messages and migrates legacy entries. |
Greptile Summary
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR canonicalizes provider failure handling across the API boundary. The main changes are: - Adds protocol-neutral execution failure values and safe diagnostics. - Moves SDK and HTTP failure classification into provider-owned policy. - Lets Messages and Responses choose their own wire error payloads. - Preserves canonical failures across stream cleanup and committed stream failures. - Makes incomplete Responses tool errors provisional until finalization.
Confidence Score: 5/5
This looks safe to merge. No blocking issues found in the changed code. No files need attention.
T-Rex Logs
**What T-Rex did** - Ran the API failure contract suite and related tests (tests/api/test\_execution\_failure\_contract.py, tests/core/test\_failure\_protocol\_mapping.py, tests/providers/test\_execution\_failure\_boundary.py, tests/providers/test\_failure\_policy.py); 48 passed in 3.36s. - Ran the streaming boundaries tests including response streams, stream recovery, and streaming errors; 70 passed in 5.36s. - Ran the OpenAI responses tests; 20 passed in 4.42s. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/providers/transports/http.py | Adds cleanup-safe stream closing that preserves established outcomes. | | src/free_claude_code/core/openai_responses/stream.py | Preserves canonical execution failures when committed Responses streams fail. | | src/free_claude_code/core/openai_responses/streaming/assembler.py | Keeps malformed tool-call errors provisional so later provider failures can win. | | src/free_claude_code/core/failures.py | Defines neutral failure kinds and exception-group lookup for execution failures. | Reviews (2): Last reviewed commit: [\"Preserve canonical outcomes in grouped a...\"](https://github.com/alishahryar1/free-claude-code/commit/f57f21241dbe582985627ed4fb40734b2c656809) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43468297) ") [#1046](https://github.com/Alishahryar1/free-claude-code/pull/1046) [)](https://github.com/Alishahryar1/free-claude-code/commit/e22a38b2c26f85cd9361c14c1b4c51ef4718d6fb "Canonicalize provider failure and retry ownership (#1046) ## Problem Provider SDK classification, retry policy, canonical failures, and downstream wire errors shared exception types across layers. That blurred ownership and let cleanup or provisional Responses tool failures mask the real provider diagnostic. ## Changes | Before | After | | --- | --- | | Provider failures carried Anthropic wire types and core code classified OpenAI/httpx errors. | Protocol-neutral `ExecutionFailure` values cross layers, providers classify SDK errors, and protocol packages map wire types. | | Provider adapters could author terminal wire events. | The HTTP commit boundary selects non-2xx JSON or a protocol terminal event with one ingress request ID. | | Retry policy and diagnostic handling were spread across core and provider modules. | Providers own the unchanged retry budgets while neutral core utilities own bounded credential redaction. | | Stream cleanup could replace an already-mapped provider failure. | Cleanup records safe metadata and preserves the canonical failure, status, and diagnostic. | | An incomplete Responses tool could preempt a later provider failure. | Tool-finalization errors remain provisional so canonical provider failures take precedence. | | Readiness failures reused provider exception types. | Application-owned errors represent deterministic validation and availability phases without terminal retry headers. | | Legacy exception and recovery owners remained importable. | Obsolete modules are deleted without shims, architecture rules enforce the boundaries, and package version is 3.4.21. |
Greptile Summary
This PR canonicalizes provider failure handling across the API boundary. The main changes are: - Adds protocol-neutral execution failure values and safe diagnostics. - Moves SDK and HTTP failure classification into provider-owned policy. - Lets Messages and Responses choose their own wire error payloads. - Preserves canonical failures across stream cleanup and committed stream failures. - Makes incomplete Responses tool errors provisional until finalization.
Confidence Score: 5/5
This looks safe to merge. No blocking issues found in the changed code. No files need attention.
T-Rex Logs
**What T-Rex did** - Ran the API failure contract suite and related tests (tests/api/test\_execution\_failure\_contract.py, tests/core/test\_failure\_protocol\_mapping.py, tests/providers/test\_execution\_failure\_boundary.py, tests/providers/test\_failure\_policy.py); 48 passed in 3.36s. - Ran the streaming boundaries tests including response streams, stream recovery, and streaming errors; 70 passed in 5.36s. - Ran the OpenAI responses tests; 20 passed in 4.42s. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/providers/transports/http.py | Adds cleanup-safe stream closing that preserves established outcomes. | | src/free_claude_code/core/openai_responses/stream.py | Preserves canonical execution failures when committed Responses streams fail. | | src/free_claude_code/core/openai_responses/streaming/assembler.py | Keeps malformed tool-call errors provisional so later provider failures can win. | | src/free_claude_code/core/failures.py | Defines neutral failure kinds and exception-group lookup for execution failures. | Reviews (2): Last reviewed commit: [\"Preserve canonical outcomes in grouped a...\"](https://github.com/alishahryar1/free-claude-code/commit/f57f21241dbe582985627ed4fb40734b2c656809) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43468297) ") | yesterdayJul 11, 2026 |
| [CONTRIBUTING.md](https://github.com/Alishahryar1/free-claude-code/blob/main/CONTRIBUTING.md "CONTRIBUTING.md") | [CONTRIBUTING.md](https://github.com/Alishahryar1/free-claude-code/blob/main/CONTRIBUTING.md "CONTRIBUTING.md") | [Simplify README around customer usage (](https://github.com/Alishahryar1/free-claude-code/commit/3c9d0ced7671c42b0de15b9575f56805e0031fef "Simplify README around customer usage (#1032) ## 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 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.
Confidence Score: 5/5
This looks safe to merge. No blocking issues found in the changed code. No files need attention.
T-Rex Logs
**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. Ran code and verified through T-Rex
Important Files Changed
| 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. | 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) ") [#1032](https://github.com/Alishahryar1/free-claude-code/pull/1032) [)](https://github.com/Alishahryar1/free-claude-code/commit/3c9d0ced7671c42b0de15b9575f56805e0031fef "Simplify README around customer usage (#1032) ## 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 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.
Confidence Score: 5/5
This looks safe to merge. No blocking issues found in the changed code. No files need attention.
T-Rex Logs
**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. Ran code and verified through T-Rex
Important Files Changed
| 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. | 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) ") | 3 days agoJul 9, 2026 |
| [LICENSE](https://github.com/Alishahryar1/free-claude-code/blob/main/LICENSE "LICENSE") | [LICENSE](https://github.com/Alishahryar1/free-claude-code/blob/main/LICENSE "LICENSE") | [added license](https://github.com/Alishahryar1/free-claude-code/commit/f7eb0000c1062566e024d95f0d35b33f882a9b7c "added license") | 6 months agoJan 28, 2026 |
| [README.md](https://github.com/Alishahryar1/free-claude-code/blob/main/README.md "README.md") | [README.md](https://github.com/Alishahryar1/free-claude-code/blob/main/README.md "README.md") | [Give messaging clear exact subtree semantics (](https://github.com/Alishahryar1/free-claude-code/commit/3fba1c6fc3a6ec829770199fbf1172a620f6fcbb "Give messaging clear exact subtree semantics (#1072) ## Problem Messaging `/clear` did not follow the selected platform message boundary. Reply clears preserved the selected user prompt, while standalone clears preserved user-authored messages and could reset FCC state outside the invoking chat. ## Changes | Before | After | | --- | --- | | Reply `/clear` removed a logical conversation branch but retained the selected message. | Reply `/clear` deletes the selected message and its literal reply subtree, including the clear command. | | Standalone `/clear` retained user prompts and voice notes while resetting global messaging state. | Standalone `/clear` deletes every tracked message and resets FCC state only in the invoking platform and chat. | | Trees recorded only logical execution parentage. | Trees separately persist logical execution ancestry and exact prompt/status reply ownership. | | Clear coordination used one global admission boundary. | Per-chat clear generations coordinate admission, voice cancellation, persistence, and best-effort platform deletion. | | Persistence tracked only FCC-authored clearable output. | Persistence tracks managed inbound and outbound messages and migrates legacy entries. |
Greptile Summary
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
This PR gives messaging `/clear` exact per-chat and reply-subtree behavior. The main changes are: - Per-chat clear generations for admission and startup-notice cleanup. - Managed inbound and outbound message tracking for deletion. - Exact prompt/status reply ownership in message trees. - Scoped voice cancellation and clear persistence updates. - Updated docs, smoke coverage, and messaging tests.
Confidence Score: 4/5
The clear flow is mostly well-contained, with one upgrade-path issue in legacy tree restoration. Newly created prompt/status subtrees use the new exact reference fields consistently, and legacy snapshots can map old status replies to prompt references. However, reply `/clear` on an upgraded status can miss descendants and leave stale state/messages. src/free_claude_code/messaging/trees/snapshot.py
T-Rex Logs
**What T-Rex did** - T-Rex attempted to prepare and run a focused legacy snapshot reproduction harness for legacy status replies detach, but tool access was blocked before execution. - A messaging clear smoke test harness was executed and reported a passing result: 20 items collected and 20 passed in 1.69 seconds, with traces for test\_reply\_clear\_uses\_literal and related paths shown in the log. Ran code and verified through T-Rex
Important Files Changed
| Filename | Overview | |----------|----------| | src/free_claude_code/messaging/workflow.py | Adds per-chat clear generations, managed inbound recording, scoped clears, and startup-notice invalidation. | | src/free_claude_code/messaging/trees/graph.py | Adds exact prompt/status reference resolution and literal reply-subtree traversal. | | src/free_claude_code/messaging/trees/runtime.py | Adds exact message-subtree removal and status-only clearing behavior. | | src/free_claude_code/messaging/trees/snapshot.py | Adds parent_reference_id persistence and legacy fallback; the fallback can miss legacy status-reply descendants. | | src/free_claude_code/messaging/session/managed_message_log.py | Replaces the clearable output log with managed inbound and outbound message tracking. | | src/free_claude_code/messaging/commands.py | Routes reply and standalone `/clear` through the new exact deletion ID flows. |
Flowchart
```mermaid %%{init: {'theme': 'neutral'}}%% flowchart TD A[Incoming message] --> B{Standalone /clear?} B -- yes --> C[Clear invoking chat] C --> D[Cancel scoped voice work] C --> E[Collect managed and tree message IDs] C --> F[Advance chat clear generation] F --> G[Detach scoped trees] G --> H[Clear scoped session store] H --> I[Best-effort platform deletes] B -- no --> J[Record managed inbound message] J --> K[Admit with stop and clear token] K --> L{Reply /clear?} L -- yes --> M[Resolve exact prompt or status reference] M --> N[Remove literal reference subtree] N --> I L -- no --> O[Queue or run tree node] ``` ```mermaid %%{init: {'theme': 'base', 'themeVariables': {\"darkMode\": true, \"background\": \"#0d1117\", \"primaryColor\": \"#21262d\", \"primaryTextColor\": \"#e6edf3\", \"primaryBorderColor\": \"#8b949e\", \"lineColor\": \"#8b949e\", \"textColor\": \"#e6edf3\", \"edgeLabelBackground\": \"#161b22\", \"actorBkg\": \"#21262d\", \"actorBorder\": \"#8b949e\", \"actorTextColor\": \"#e6edf3\", \"actorLineColor\": \"#8b949e\", \"signalColor\": \"#8b949e\", \"signalTextColor\": \"#e6edf3\", \"noteBkgColor\": \"#373320\", \"noteBorderColor\": \"#d4a72c\", \"noteTextColor\": \"#f0e6c0\", \"labelBoxBkgColor\": \"#21262d\", \"labelBoxBorderColor\": \"#8b949e\", \"labelTextColor\": \"#e6edf3\", \"loopTextColor\": \"#e6edf3\", \"activationBkgColor\": \"#30363d\", \"activationBorderColor\": \"#8b949e\"}}}%% flowchart TD A[Incoming message] --> B{Standalone /clear?} B -- yes --> C[Clear invoking chat] C --> D[Cancel scoped voice work] C --> E[Collect managed and tree message IDs] C --> F[Advance chat clear generation] F --> G[Detach scoped trees] G --> H[Clear scoped session store] H --> I[Best-effort platform deletes] B -- no --> J[Record managed inbound message] J --> K[Admit with stop and clear token] K --> L{Reply /clear?} L -- yes --> M[Resolve exact prompt or status reference] M --> N[Remove literal reference subtree] N --> I L -- no --> O[Queue or run tree node] ``` Reviews (1): Last reviewed commit: [\"Give messaging clear exact subtree seman...\"](https://github.com/alishahryar1/free-claude-code/commit/0a3baecf9470da4bb866c864c1d1f01abd517085) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43593126) > Greptile also left **1 inline comment** on this PR. ") | 9 hours agoJul 12, 2026 |
| View all files |
## Repository files navigation
# 🤖 Free Claude Code
[Permalink: 🤖 Free Claude Code](https://github.com/Alishahryar1/free-claude-code#-free-claude-code)
Use Claude Code CLI, Codex CLI, their VS Code extensions, JetBrains ACP, or chat bots through your own provider-backed proxy.
[](https://opensource.org/licenses/MIT)[](https://www.python.org/downloads/)[](https://github.com/astral-sh/uv)[](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)[](https://pypi.org/project/ty/)[](https://github.com/astral-sh/ruff)[](https://github.com/Delgan/loguru)
Run Claude Code or Codex with free, paid, or local models. Choose and validate providers from one local Admin UI.
[Quick Start](https://github.com/Alishahryar1/free-claude-code#quick-start) · [Providers](https://github.com/Alishahryar1/free-claude-code#choose-a-provider) · [Clients](https://github.com/Alishahryar1/free-claude-code#connect-your-client) · [Integrations](https://github.com/Alishahryar1/free-claude-code#optional-integrations) · [Manage](https://github.com/Alishahryar1/free-claude-code#manage-your-installation)
[](https://github.com/Alishahryar1/free-claude-code/blob/main/assets/pic.png)
_Claude Code running through the Free Claude Code proxy._
[](https://github.com/Alishahryar1/free-claude-code/blob/main/assets/codex.png)
_Codex CLI using the local FCC Responses provider._
[](https://github.com/Alishahryar1/free-claude-code/blob/main/assets/cc-model-picker.png)
_Claude Code native `/model` picker with FCC gateway models._
[](https://github.com/Alishahryar1/free-claude-code/blob/main/assets/codex-model-picker.png)
_Codex native `/model` picker with the generated FCC catalog._
## Star History
[Permalink: Star History](https://github.com/Alishahryar1/free-claude-code#star-history)
[](https://star-history.com/#Alishahryar1/free-claude-code&Date)
## What You Get
[Permalink: What You Get](https://github.com/Alishahryar1/free-claude-code#what-you-get)
- Launch Claude Code with `fcc-claude` or Codex with `fcc-codex`.
- Switch among 24 cloud and local providers from the Admin UI.
- Use the native Claude Code and Codex `/model` pickers.
- Route Opus, Sonnet, Haiku, and fallback traffic to different models.
- Keep streaming, tool use, and reasoning support across compatible models.
- Connect Claude Code and Codex in VS Code or Claude Code through JetBrains ACP.
- Optionally run Claude Code sessions through Discord or Telegram with voice-note transcription.
- Protect the local proxy with optional token authentication.
## Quick Start
[Permalink: Quick Start](https://github.com/Alishahryar1/free-claude-code#quick-start)
### 1\. Install Or Update
[Permalink: 1. Install Or Update](https://github.com/Alishahryar1/free-claude-code#1-install-or-update)
The installer provisions Free Claude Code, uv, and Python 3.14. It also installs Claude Code and Codex when they are missing; install [Node.js](https://nodejs.org/) first so `npm` is available for those agents.
macOS/Linux:
```
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh
```
Windows PowerShell:
```
irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" | iex
```
Re-run the same command whenever you want to update. You can review the installers before running them: [install.sh](https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh) and [install.ps1](https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1).
### 2\. Start The Server
[Permalink: 2. Start The Server](https://github.com/Alishahryar1/free-claude-code#2-start-the-server)
```
fcc-server
```
To print the installed Free Claude Code version without starting the server,
run `fcc-server --version`.
Keep this process running. The startup log shows the Admin UI address:
```
INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
```
Use the port shown in your terminal if it differs from `8082`.
### 3\. Configure NVIDIA NIM
[Permalink: 3. Configure NVIDIA NIM](https://github.com/Alishahryar1/free-claude-code#3-configure-nvidia-nim)
1. Create an API key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys).
2. Open the Admin UI URL from the server log.
3. Paste the key into `NVIDIA_NIM_API_KEY`.
4. Leave `MODEL` on the default `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, or select another model.
5. Click **Validate**, then **Apply**.
[](https://github.com/Alishahryar1/free-claude-code/blob/main/assets/admin-page.png)
### 4\. Run Your Coding Agent
[Permalink: 4. Run Your Coding Agent](https://github.com/Alishahryar1/free-claude-code#4-run-your-coding-agent)
Claude Code:
```
fcc-claude
```
Codex:
```
fcc-codex
```
Both launchers use the current Admin UI settings. Type `/model` inside either agent to choose from the models FCC exposes. Normal CLI arguments still work, for example:
```
fcc-codex exec "hello"
```
## Choose A Provider
[Permalink: Choose A Provider](https://github.com/Alishahryar1/free-claude-code#choose-a-provider)
Enter the listed setting in the Admin UI, set `MODEL` to a provider-prefixed model ID, then click **Validate** and **Apply**. Provider names link to their key, model, or setup pages.
| Provider | Admin UI setting | Example `MODEL` |
| --- | --- | --- |
| [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
| [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
| [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
| [DeepSeek](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
| [Mistral La Plateforme](https://console.mistral.ai/) | `MISTRAL_API_KEY` | `mistral/devstral-small-latest` |
| [Mistral Codestral](https://console.mistral.ai/) | `CODESTRAL_API_KEY` | `mistral_codestral/codestral-latest` |
| [OpenCode Zen](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode/gpt-5.3-codex` |
| [OpenCode Go](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode_go/minimax-m2.7` |
| [Vercel AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers) | `AI_GATEWAY_API_KEY` | `vercel/openai/gpt-5.5` |
| [Hugging Face Inference Providers](https://huggingface.co/settings/tokens) | `HUGGINGFACE_API_KEY` | `huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest` |
| [Cohere](https://dashboard.cohere.com/api-keys) | `COHERE_API_KEY` | `cohere/command-a-plus-05-2026` |
| [GitHub Models](https://github.com/marketplace?type=models) | `GITHUB_MODELS_TOKEN` | `github_models/openai/gpt-4.1` |
| [Wafer](https://wafer.ai/) | `WAFER_API_KEY` | `wafer/DeepSeek-V4-Pro` |
| [Kimi](https://platform.moonshot.ai/console/api-keys) | `KIMI_API_KEY` | `kimi/kimi-k2.5` |
| [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_API_KEY` | `minimax/MiniMax-M3` |
| [Cerebras Inference](https://cloud.cerebras.ai/) | `CEREBRAS_API_KEY` | `cerebras/gpt-oss-120b` |
| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [SambaNova](https://cloud.sambanova.ai/apis) | `SAMBANOVA_API_KEY` | `sambanova/Meta-Llama-3.3-70B-Instruct` |
| [Fireworks AI](https://fireworks.ai/account/api-keys) | `FIREWORKS_API_KEY` | `fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct` |
| [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` | `cloudflare/@cf/moonshotai/kimi-k2.6` |
| [Z.ai](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai/glm-5.2` |
| [LM Studio](https://lmstudio.ai/) | `LM_STUDIO_BASE_URL` | `lmstudio/` |
| [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/` |
| [Ollama](https://ollama.com/) | `OLLAMA_BASE_URL` | `ollama/` |
Important provider notes:
- Mistral Codestral uses a separate key from Mistral La Plateforme.
- OpenCode Zen and OpenCode Go share `OPENCODE_API_KEY` but use different model prefixes.
- Cloudflare requires both its API token and account ID.
- Prefer tool-capable models for coding agents. Local models also need enough context for the agent's system prompt and tool definitions.
**Local provider setup**
### LM Studio
[Permalink: LM Studio](https://github.com/Alishahryar1/free-claude-code#lm-studio)
Start LM Studio's local server, load a tool-capable model, and use the model identifier shown by LM Studio with the `lmstudio/` prefix. The default URL is `http://localhost:1234/v1`.
### llama.cpp
[Permalink: llama.cpp](https://github.com/Alishahryar1/free-claude-code#llamacpp)
Start `llama-server` with its OpenAI-compatible Chat Completions API and enough context for the model. Use the local model ID with the `llamacpp/` prefix. `LLAMACPP_BASE_URL` defaults to `http://localhost:8080/v1`; FCC accepts either the server root or an explicit `/v1` suffix.
### Ollama
[Permalink: Ollama](https://github.com/Alishahryar1/free-claude-code#ollama)
```
ollama pull llama3.1
ollama serve
```
Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL` defaults to `http://localhost:11434`; FCC accepts either the root URL or an explicit `/v1` suffix.
### Optional Model-Tier Routing
[Permalink: Optional Model-Tier Routing](https://github.com/Alishahryar1/free-claude-code#optional-model-tier-routing)
`MODEL` is the fallback for every request. Set `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override individual Claude Code tiers; leave a tier blank to inherit `MODEL`.
For example, route Opus to `nvidia_nim/moonshotai/kimi-k2.6`, Sonnet to `open_router/openrouter/free`, Haiku to `lmstudio/qwen3.5-coder`, and keep `MODEL` on `zai/glm-5.2`.
## Connect Your Client
[Permalink: Connect Your Client](https://github.com/Alishahryar1/free-claude-code#connect-your-client)
For terminal use, start `fcc-server`, then prefer `fcc-claude` or `fcc-codex`. Use the guides below for editor integrations.
**Claude Code in VS Code**
Install the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). In VS Code settings, edit `claudeCode.environmentVariables`:
```
"claudeCode.environmentVariables": [\
{ "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },\
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },\
{ "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" },\
{ "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "190000" }\
]
```
Match the port and authentication token to the Admin UI, then reload the extension. If prompted to log in, choose the Anthropic Console path once; FCC still handles model traffic.
**Codex in VS Code**
Install the [Codex extension](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt). Create or edit `~/.codex/config.toml` (`%USERPROFILE%\.codex\config.toml` on Windows):
```
model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
[model_providers.fcc]
name = "Free Claude Code"
base_url = "http://127.0.0.1:8082/v1"
env_key = "FCC_CODEX_API_KEY"
wire_api = "responses"
```
Store the Admin UI authentication token in `~/.codex/auth.json` or its Windows equivalent:
```
{
"FCC_CODEX_API_KEY": "freecc"
}
```
Match `model`, the port, and the token to the Admin UI, then restart VS Code. For WSL-backed Codex, edit the files inside WSL.
**Claude Code in JetBrains ACP**
Edit the installed Claude ACP configuration:
- Windows: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json`
- Linux/macOS: `~/.jetbrains/acp.json`
Set the environment for `acp.registry.claude-acp`:
```
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:8082",
"ANTHROPIC_AUTH_TOKEN": "freecc",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000"
}
```
Match the port and token to the Admin UI, then restart the IDE.
## Optional Integrations
[Permalink: Optional Integrations](https://github.com/Alishahryar1/free-claude-code#optional-integrations)
Configure integrations from **Admin UI → Messaging**, then click **Validate** and **Apply**.
[](https://github.com/Alishahryar1/free-claude-code/blob/main/assets/admin-messaging.png)
**Discord bot**
1. Create a bot in the [Discord Developer Portal](https://discord.com/developers/applications).
2. Enable **Message Content Intent** and invite it with read, send,
message-history, and **Manage Messages** permissions so `/clear` can remove
user prompts.
3. Set **Messaging Platform** to **discord**.
4. Enter **Discord Bot Token**, **Allowed Discord Channels**, and an absolute **Allowed Directory**.
5. Apply the settings and restart the server if requested.
**Telegram bot**
1. Create a bot with [@BotFather](https://t.me/BotFather).
2. Get your numeric user ID from [@userinfobot](https://t.me/userinfobot).
In groups, grant the bot permission to delete messages.
3. Set **Messaging Platform** to **telegram**.
4. Enter **Telegram Bot Token**, **Allowed Telegram User ID**, and an absolute **Allowed Directory**.
5. Apply the settings and restart the server if requested.
Bot commands: standalone `/stop` cancels all work, standalone `/clear` resets all
FCC state and removes every tracked message in that chat—including user prompts,
voice notes, FCC replies, Telegram's online notice, and the clear command itself.
`/stats` shows session state. Reply with `/stop` to cancel only that request while
other queued requests continue. Reply with `/clear` to delete the selected message
and its literal platform reply subtree while preserving its ancestors and siblings.
A successful stop updates the affected task status instead of posting a second
confirmation message. A no-op, or a global stop whose affected statuses are in
another chat, still replies explicitly.
**Voice notes**
Re-run the installer with the voice backend you need.
macOS/Linux:
```
# NVIDIA NIM transcription
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-nim
# Local Whisper on CPU or CUDA
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-local
# Both backends
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-all
# Local Whisper with the CUDA 13.0 PyTorch backend
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-local --torch-backend cu130
```
Windows PowerShell:
```
# NVIDIA NIM transcription
& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceNim
# Local Whisper on CPU or CUDA
& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceLocal
# Both backends
& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceAll
# Local Whisper with the CUDA 13.0 PyTorch backend
& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceLocal -TorchBackend cu130
```
Restart `fcc-server`. In **Admin UI → Messaging → Voice**, enable voice notes, select `cpu`, `cuda`, or `nvidia_nim`, and choose the Whisper model. Local gated models need `HUGGINGFACE_API_KEY`; NVIDIA NIM transcription needs `NVIDIA_NIM_API_KEY`.
## Manage Your Installation
[Permalink: Manage Your Installation](https://github.com/Alishahryar1/free-claude-code#manage-your-installation)
### Update
[Permalink: Update](https://github.com/Alishahryar1/free-claude-code#update)
Re-run the matching command from [Install Or Update](https://github.com/Alishahryar1/free-claude-code#install).
### Uninstall
[Permalink: Uninstall](https://github.com/Alishahryar1/free-claude-code#uninstall)
Stop every running FCC command first. The uninstall script removes the FCC uv tool and always deletes `~/.fcc/`; it does not remove uv, Python, Claude Code, or Codex.
macOS/Linux:
```
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh
```
Windows PowerShell:
```
irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1" | iex
```
## Project Links
[Permalink: Project Links](https://github.com/Alishahryar1/free-claude-code#project-links)
- [Report bugs or request features](https://github.com/Alishahryar1/free-claude-code/issues)
- [Architecture and extension guide](https://github.com/Alishahryar1/free-claude-code/blob/main/ARCHITECTURE.md)
- [Contributing guide](https://github.com/Alishahryar1/free-claude-code/blob/main/CONTRIBUTING.md)
## License
[Permalink: License](https://github.com/Alishahryar1/free-claude-code#license)
MIT License. See [LICENSE](https://github.com/Alishahryar1/free-claude-code/blob/main/LICENSE) for details.
## About
Use claude code and codex for free in the terminal, VSCode extension, and discord like OpenClaw (voice supported)
### Resources
[Readme](https://github.com/Alishahryar1/free-claude-code#readme-ov-file)
### License
[MIT license](https://github.com/Alishahryar1/free-claude-code#MIT-1-ov-file)
### Contributing
[Contributing](https://github.com/Alishahryar1/free-claude-code#contributing-ov-file)
### Uh oh!
There was an error while loading. [Please reload this page](https://github.com/Alishahryar1/free-claude-code).
[Activity](https://github.com/Alishahryar1/free-claude-code/activity)
### Stars
**39.7k**
stars
### Watchers
**302**
watching
### Forks
[**6.5k**\\
forks](https://github.com/Alishahryar1/free-claude-code/forks)
[Report repository](https://github.com/contact/report-content?content_url=https%3A%2F%2Fgithub.com%2FAlishahryar1%2Ffree-claude-code&report=Alishahryar1+%28user%29)
## [Releases](https://github.com/Alishahryar1/free-claude-code/releases)
No releases published
## [Packages\ 0](https://github.com/users/Alishahryar1/packages?repo_name=free-claude-code)
No packages published
## [Contributors\ 36](https://github.com/Alishahryar1/free-claude-code/graphs/contributors)
- [](https://github.com/Alishahryar1)
- [](https://github.com/cursoragent)
- [![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4)](https://github.com/apps/dependabot)
- [](https://github.com/claude)
- [](https://github.com/rishiskhare)
- [![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4)](https://github.com/apps/github-actions)
- [](https://github.com/aaravsw3)
- [](https://github.com/suryawanshishantanu6)
- [](https://github.com/Jiwangreal)
- [](https://github.com/duckinzzz)
- [](https://github.com/jankeydadondc-byte)
- [](https://github.com/newmemories360)
- [](https://github.com/Ahmet-Kaplan)
[\+ 22 contributors](https://github.com/Alishahryar1/free-claude-code/graphs/contributors)
## Languages
- [Python97.5%](https://github.com/Alishahryar1/free-claude-code/search?l=python)
- [PowerShell0.7%](https://github.com/Alishahryar1/free-claude-code/search?l=powershell)
- [Shell0.6%](https://github.com/Alishahryar1/free-claude-code/search?l=shell)
- [JavaScript0.5%](https://github.com/Alishahryar1/free-claude-code/search?l=javascript)
- [CSS0.5%](https://github.com/Alishahryar1/free-claude-code/search?l=css)
- [HTML0.1%](https://github.com/Alishahryar1/free-claude-code/search?l=html)
- [Mermaid0.1%](https://github.com/Alishahryar1/free-claude-code/search?l=mermaid)
You can’t perform that action at this time.
![\"T-Rex\"](\"https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg\")
T-Rex Logs![\"View](\"https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4\")
![\"Fix](\"https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodex.svg?v=6\")