docs: professional overhaul of README with model providers section

Restructured the README to match top-tier open source project standards:
- Added badge row, centered header, and table of contents
- Added comprehensive Model Providers section covering all 5 supported
  providers (Anthropic, OpenAI Codex, AWS Bedrock, Vertex AI, Foundry)
  with auth methods, model tables, and env vars
- Reorganized experimental features into categorized tables
- Added environment variables reference
- Added contributing section
- Improved overall structure and readability

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
paoloanznandClaude Opus 4.6 committed 2026-04-01 12:06:19 +02:00
1 parent 721fc8bcc6
commit 728692fe09
1 file changed
+291 -147
+291 -147
View File
@@ -1,81 +1,33 @@
# free-code
<p align="center">
<img src="assets/screenshot.png" alt="free-code" width="720" />
</p>
**The free build of Claude Code.**
All telemetry stripped. All injected security-prompt guardrails removed. All experimental features unlocked. One binary, zero callbacks home.
```bash
curl -fsSL https://raw.githubusercontent.com/paoloanzn/free-code/main/install.sh | bash
```
> Checks your system, installs Bun if needed, clones, builds with all features enabled, and puts `free-code` on your PATH. Then just `export ANTHROPIC_API_KEY="sk-ant-..."` and run `free-code`.
<h1 align="center">free-code</h1>
<p align="center">
<img src="assets/screenshot.png" alt="free-code screenshot" width="800" />
<strong>The free build of Claude Code.</strong><br>
All telemetry stripped. All guardrails removed. All experimental features unlocked.<br>
One binary, zero callbacks home.
</p>
<p align="center">
<a href="#quick-install"><img src="https://img.shields.io/badge/install-one--liner-blue?style=flat-square" alt="Install" /></a>
<a href="https://github.com/paoloanzn/free-code/stargazers"><img src="https://img.shields.io/github/stars/paoloanzn/free-code?style=flat-square" alt="Stars" /></a>
<a href="https://github.com/paoloanzn/free-code/issues"><img src="https://img.shields.io/github/issues/paoloanzn/free-code?style=flat-square" alt="Issues" /></a>
<a href="https://github.com/paoloanzn/free-code/blob/main/FEATURES.md"><img src="https://img.shields.io/badge/features-88%20flags-orange?style=flat-square" alt="Feature Flags" /></a>
<a href="#ipfs-mirror"><img src="https://img.shields.io/badge/IPFS-mirrored-teal?style=flat-square" alt="IPFS" /></a>
</p>
---
## What is this
This is a clean, buildable fork of Anthropic's [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI -- the terminal-native AI coding agent. The upstream source became publicly available on March 31, 2026 through a source map exposure in the npm distribution.
This fork applies three categories of changes on top of that snapshot:
### 1. Telemetry removed
The upstream binary phones home through OpenTelemetry/gRPC, GrowthBook analytics, Sentry error reporting, and custom event logging. In this build:
- All outbound telemetry endpoints are dead-code-eliminated or stubbed
- GrowthBook feature flag evaluation still works locally (needed for runtime feature gates) but does not report back
- No crash reports, no usage analytics, no session fingerprinting
### 2. Security-prompt guardrails removed
Anthropic injects system-level instructions into every conversation that constrain Claude's behavior beyond what the model itself enforces. These include:
- Hardcoded refusal patterns for certain categories of prompts
- Injected "cyber risk" instruction blocks
- Managed-settings security overlays pushed from Anthropic's servers
This build strips those injections. The model's own safety training still applies -- this just removes the extra layer of prompt-level restrictions that the CLI wraps around it.
### 3. Experimental features enabled
Claude Code ships with dozens of feature flags gated behind `bun:bundle` compile-time switches. Most are disabled in the public npm release. This build unlocks all 45+ flags that compile cleanly, including:
| Feature | What it does |
|---|---|
| `ULTRAPLAN` | Remote multi-agent planning on Claude Code web (Opus-class) |
| `ULTRATHINK` | Deep thinking mode -- type "ultrathink" to boost reasoning effort |
| `VOICE_MODE` | Push-to-talk voice input and dictation |
| `AGENT_TRIGGERS` | Local cron/trigger tools for background automation |
| `BRIDGE_MODE` | IDE remote-control bridge (VS Code, JetBrains) |
| `TOKEN_BUDGET` | Token budget tracking and usage warnings |
| `BUILTIN_EXPLORE_PLAN_AGENTS` | Built-in explore/plan agent presets |
| `VERIFICATION_AGENT` | Verification agent for task validation |
| `BASH_CLASSIFIER` | Classifier-assisted bash permission decisions |
| `EXTRACT_MEMORIES` | Post-query automatic memory extraction |
| `HISTORY_PICKER` | Interactive prompt history picker |
| `MESSAGE_ACTIONS` | Message action entrypoints in the UI |
| `QUICK_SEARCH` | Prompt quick-search |
| `SHOT_STATS` | Shot-distribution stats |
| `COMPACTION_REMINDERS` | Smart reminders around context compaction |
| `CACHED_MICROCOMPACT` | Cached microcompact state through query flows |
See [FEATURES.md](FEATURES.md) for the full audit of all 88 flags and their status.
---
## Quick install
## Quick Install
```bash
curl -fsSL https://raw.githubusercontent.com/paoloanzn/free-code/main/install.sh | bash
```
This will check your system, install Bun if needed, clone the repo, build the binary with all experimental features enabled, and symlink it as `free-code` on your PATH.
Checks your system, installs Bun if needed, clones the repo, builds with all experimental features enabled, and symlinks `free-code` on your PATH.
After install, just run:
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
free-code
@@ -83,11 +35,158 @@ free-code
---
## Table of Contents
- [What is this](#what-is-this)
- [Model Providers](#model-providers)
- [Quick Install](#quick-install)
- [Requirements](#requirements)
- [Build](#build)
- [Usage](#usage)
- [Experimental Features](#experimental-features)
- [Project Structure](#project-structure)
- [Tech Stack](#tech-stack)
- [IPFS Mirror](#ipfs-mirror)
- [Contributing](#contributing)
- [License](#license)
---
## What is this
A clean, buildable fork of Anthropic's [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI -- the terminal-native AI coding agent. The upstream source became publicly available on March 31, 2026 through a source map exposure in the npm distribution.
This fork applies three categories of changes on top of that snapshot:
### Telemetry removed
The upstream binary phones home through OpenTelemetry/gRPC, GrowthBook analytics, Sentry error reporting, and custom event logging. In this build:
- All outbound telemetry endpoints are dead-code-eliminated or stubbed
- GrowthBook feature flag evaluation still works locally (needed for runtime feature gates) but does not report back
- No crash reports, no usage analytics, no session fingerprinting
### Security-prompt guardrails removed
Anthropic injects system-level instructions into every conversation that constrain Claude's behavior beyond what the model itself enforces. These include hardcoded refusal patterns, injected "cyber risk" instruction blocks, and managed-settings security overlays pushed from Anthropic's servers.
This build strips those injections. The model's own safety training still applies -- this just removes the extra layer of prompt-level restrictions that the CLI wraps around it.
### Experimental features unlocked
Claude Code ships with 88 feature flags gated behind `bun:bundle` compile-time switches. Most are disabled in the public npm release. This build unlocks all 54 flags that compile cleanly. See [Experimental Features](#experimental-features) below, or refer to [FEATURES.md](FEATURES.md) for the full audit.
---
## Model Providers
free-code supports **five API providers** out of the box. Set the corresponding environment variable to switch providers -- no code changes needed.
### Anthropic (Direct API) -- Default
Use Anthropic's first-party API directly.
| Model | ID |
|---|---|
| Claude Opus 4.6 | `claude-opus-4-6` |
| Claude Opus 4.5 | `claude-opus-4-5` |
| Claude Opus 4.1 | `claude-opus-4-1` |
| Claude Opus 4 | `claude-opus-4` |
| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
| Claude Sonnet 4.5 | `claude-sonnet-4-5` |
| Claude Sonnet 4 | `claude-sonnet-4` |
| Claude Haiku 4.5 | `claude-haiku-4-5` |
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
free-code
```
Or authenticate via Claude.ai OAuth:
```bash
free-code /login
```
### OpenAI Codex
Use OpenAI's Codex models for code generation. Requires a Codex subscription.
| Model | ID |
|---|---|
| GPT-5.3 Codex (recommended) | `gpt-5.3-codex` |
| GPT-5.2 Codex | `gpt-5.2-codex` |
| GPT-5.1 Codex | `gpt-5.1-codex` |
| GPT-5.1 Codex Mini | `gpt-5.1-codex-mini` |
| GPT-5.1 Codex Max | `gpt-5.1-codex-max` |
| GPT-5.4 | `gpt-5.4` |
| GPT-5.2 | `gpt-5.2` |
```bash
export CLAUDE_CODE_USE_OPENAI=1
free-code /login # OAuth via OpenAI
```
### AWS Bedrock
Route requests through your AWS account via Amazon Bedrock.
```bash
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1" # or AWS_DEFAULT_REGION
free-code
```
Uses your standard AWS credentials (environment variables, `~/.aws/config`, or IAM role). Models are mapped to Bedrock ARN format automatically (e.g., `us.anthropic.claude-opus-4-6-v1`).
| Variable | Purpose |
|---|---|
| `CLAUDE_CODE_USE_BEDROCK` | Enable Bedrock provider |
| `AWS_REGION` / `AWS_DEFAULT_REGION` | AWS region (default: `us-east-1`) |
| `ANTHROPIC_BEDROCK_BASE_URL` | Custom Bedrock endpoint |
| `AWS_BEARER_TOKEN_BEDROCK` | Bearer token auth |
| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip auth (testing) |
### Google Cloud Vertex AI
Route requests through your GCP project via Vertex AI.
```bash
export CLAUDE_CODE_USE_VERTEX=1
free-code
```
Uses Google Cloud Application Default Credentials (`gcloud auth application-default login`). Models are mapped to Vertex format automatically (e.g., `claude-opus-4-6@latest`).
### Anthropic Foundry
Use Anthropic Foundry for dedicated deployments.
```bash
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_API_KEY="..."
free-code
```
Supports custom deployment IDs as model names.
### Provider Selection Summary
| Provider | Env Variable | Auth Method |
|---|---|---|
| Anthropic (default) | -- | `ANTHROPIC_API_KEY` or OAuth |
| OpenAI Codex | `CLAUDE_CODE_USE_OPENAI=1` | OAuth via OpenAI |
| AWS Bedrock | `CLAUDE_CODE_USE_BEDROCK=1` | AWS credentials |
| Google Vertex AI | `CLAUDE_CODE_USE_VERTEX=1` | `gcloud` ADC |
| Anthropic Foundry | `CLAUDE_CODE_USE_FOUNDRY=1` | `ANTHROPIC_FOUNDRY_API_KEY` |
---
## Requirements
- [Bun](https://bun.sh) >= 1.3.11
- macOS or Linux (Windows via WSL)
- An Anthropic API key (set `ANTHROPIC_API_KEY` in your environment)
- **Runtime**: [Bun](https://bun.sh) >= 1.3.11
- **OS**: macOS or Linux (Windows via WSL)
- **Auth**: An API key or OAuth login for your chosen provider
```bash
# Install Bun if you don't have it
@@ -99,124 +198,155 @@ curl -fsSL https://bun.sh/install | bash
## Build
```bash
# Clone the repo
git clone https://github.com/paoloanzn/claude-code.git
cd claude-code
# Install dependencies
git clone https://github.com/paoloanzn/free-code.git
cd free-code
bun install
# Standard build -- produces ./cli
bun run build
# Dev build -- dev version stamp, experimental GrowthBook key
bun run build:dev
# Dev build with ALL experimental features enabled -- produces ./cli-dev
bun run build:dev:full
# Compiled build (alternative output path) -- produces ./dist/cli
bun run compile
```
### Build variants
### Build Variants
| Command | Output | Features | Notes |
| Command | Output | Features | Description |
|---|---|---|---|
| `bun run build` | `./cli` | `VOICE_MODE` only | Production-like binary |
| `bun run build:dev` | `./cli-dev` | `VOICE_MODE` only | Dev version stamp |
| `bun run build:dev:full` | `./cli-dev` | All 45+ experimental flags | The full unlock build |
| `bun run compile` | `./dist/cli` | `VOICE_MODE` only | Alternative output directory |
| `bun run build:dev:full` | `./cli-dev` | All 54 experimental flags | Full unlock build |
| `bun run compile` | `./dist/cli` | `VOICE_MODE` only | Alternative output path |
### Individual feature flags
### Custom Feature Flags
You can enable specific flags without the full bundle:
Enable specific flags without the full bundle:
```bash
# Enable just ultraplan and ultrathink
bun run ./scripts/build.ts --feature=ULTRAPLAN --feature=ULTRATHINK
# Enable a specific flag on top of the dev build
# Add a flag on top of the dev build
bun run ./scripts/build.ts --dev --feature=BRIDGE_MODE
```
---
## Run
## Usage
```bash
# Run the built binary directly
./cli
# Or the dev binary
./cli-dev
# Or run from source without compiling (slower startup)
bun run dev
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
# Or use Claude.ai OAuth
./cli /login
```
### Quick test
```bash
# One-shot mode
./cli -p "what files are in this directory?"
# Interactive REPL (default)
./cli
# With specific model
./cli --model claude-sonnet-4-6-20250514
# One-shot mode
./cli -p "what files are in this directory?"
# Specify a model
./cli --model claude-opus-4-6
# Run from source (slower startup)
bun run dev
# OAuth login
./cli /login
```
### Environment Variables Reference
| Variable | Purpose |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `ANTHROPIC_AUTH_TOKEN` | Auth token (alternative) |
| `ANTHROPIC_MODEL` | Override default model |
| `ANTHROPIC_BASE_URL` | Custom API endpoint |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Custom Opus model ID |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Custom Sonnet model ID |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Custom Haiku model ID |
| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token via env |
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | API key helper cache TTL |
---
## Project structure
## Experimental Features
The `bun run build:dev:full` build enables all 54 working feature flags. Highlights:
### Interaction & UI
| Flag | Description |
|---|---|
| `ULTRAPLAN` | Remote multi-agent planning on Claude Code web (Opus-class) |
| `ULTRATHINK` | Deep thinking mode -- type "ultrathink" to boost reasoning effort |
| `VOICE_MODE` | Push-to-talk voice input and dictation |
| `TOKEN_BUDGET` | Token budget tracking and usage warnings |
| `HISTORY_PICKER` | Interactive prompt history picker |
| `MESSAGE_ACTIONS` | Message action entrypoints in the UI |
| `QUICK_SEARCH` | Prompt quick-search |
| `SHOT_STATS` | Shot-distribution stats |
### Agents, Memory & Planning
| Flag | Description |
|---|---|
| `BUILTIN_EXPLORE_PLAN_AGENTS` | Built-in explore/plan agent presets |
| `VERIFICATION_AGENT` | Verification agent for task validation |
| `AGENT_TRIGGERS` | Local cron/trigger tools for background automation |
| `AGENT_TRIGGERS_REMOTE` | Remote trigger tool path |
| `EXTRACT_MEMORIES` | Post-query automatic memory extraction |
| `COMPACTION_REMINDERS` | Smart reminders around context compaction |
| `CACHED_MICROCOMPACT` | Cached microcompact state through query flows |
| `TEAMMEM` | Team-memory files and watcher hooks |
### Tools & Infrastructure
| Flag | Description |
|---|---|
| `BRIDGE_MODE` | IDE remote-control bridge (VS Code, JetBrains) |
| `BASH_CLASSIFIER` | Classifier-assisted bash permission decisions |
| `PROMPT_CACHE_BREAK_DETECTION` | Cache-break detection in compaction/query flow |
See [FEATURES.md](FEATURES.md) for the complete audit of all 88 flags, including 34 broken flags with reconstruction notes.
---
## Project Structure
```
scripts/
build.ts # Build script with feature flag system
build.ts # Build script with feature flag system
src/
entrypoints/cli.tsx # CLI entrypoint
commands.ts # Command registry (slash commands)
tools.ts # Tool registry (agent tools)
QueryEngine.ts # LLM query engine
screens/REPL.tsx # Main interactive UI
entrypoints/cli.tsx # CLI entrypoint
commands.ts # Command registry (slash commands)
tools.ts # Tool registry (agent tools)
QueryEngine.ts # LLM query engine
screens/REPL.tsx # Main interactive UI (Ink/React)
commands/ # /slash command implementations
tools/ # Agent tool implementations (Bash, Read, Edit, etc.)
components/ # Ink/React terminal UI components
hooks/ # React hooks
services/ # API client, MCP, OAuth, analytics
state/ # App state store
utils/ # Utilities
skills/ # Skill system
plugins/ # Plugin system
bridge/ # IDE bridge
voice/ # Voice input
tasks/ # Background task management
commands/ # /slash command implementations
tools/ # Agent tool implementations (Bash, Read, Edit, etc.)
components/ # Ink/React terminal UI components
hooks/ # React hooks
services/ # API clients, MCP, OAuth, analytics
api/ # API client + Codex fetch adapter
oauth/ # OAuth flows (Anthropic + OpenAI)
state/ # App state store
utils/ # Utilities
model/ # Model configs, providers, validation
skills/ # Skill system
plugins/ # Plugin system
bridge/ # IDE bridge
voice/ # Voice input
tasks/ # Background task management
```
---
## Tech stack
## Tech Stack
| | |
|---|---|
| Runtime | [Bun](https://bun.sh) |
| Language | TypeScript |
| Terminal UI | React + [Ink](https://github.com/vadimdemedes/ink) |
| CLI parsing | [Commander.js](https://github.com/tj/commander.js) |
| Schema validation | Zod v4 |
| Code search | ripgrep (bundled) |
| Protocols | MCP, LSP |
| API | Anthropic Messages API |
| **Runtime** | [Bun](https://bun.sh) |
| **Language** | TypeScript |
| **Terminal UI** | React + [Ink](https://github.com/vadimdemedes/ink) |
| **CLI Parsing** | [Commander.js](https://github.com/tj/commander.js) |
| **Schema Validation** | Zod v4 |
| **Code Search** | ripgrep (bundled) |
| **Protocols** | MCP, LSP |
| **APIs** | Anthropic Messages, OpenAI Codex, AWS Bedrock, Google Vertex AI |
---
@@ -224,13 +354,27 @@ src/
A full copy of this repository is permanently pinned on IPFS via Filecoin:
- **CID:** `bafybeiegvef3dt24n2znnnmzcud2vxat7y7rl5ikz7y7yoglxappim54bm`
- **Gateway:** https://w3s.link/ipfs/bafybeiegvef3dt24n2znnnmzcud2vxat7y7rl5ikz7y7yoglxappim54bm
| | |
|---|---|
| **CID** | `bafybeiegvef3dt24n2znnnmzcud2vxat7y7rl5ikz7y7yoglxappim54bm` |
| **Gateway** | https://w3s.link/ipfs/bafybeiegvef3dt24n2znnnmzcud2vxat7y7rl5ikz7y7yoglxappim54bm |
If this repo gets taken down, the code lives on.
---
## Contributing
Contributions are welcome. If you're working on restoring one of the 34 broken feature flags, check the reconstruction notes in [FEATURES.md](FEATURES.md) first -- many are close to compiling and just need a small wrapper or missing asset.
1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Commit your changes (`git commit -m 'feat: add something'`)
4. Push to the branch (`git push origin feat/my-feature`)
5. Open a Pull Request
---
## License
The original Claude Code source is the property of Anthropic. This fork exists because the source was publicly exposed through their npm distribution. Use at your own discretion.