Metadata-Version: 2.4
Name: free-claude
Version: 0.3.1
Summary: Free AI coding agent powered by Claude — built-in tools, multi-agent teams, MCP plugins, $0 cost
Project-URL: Homepage, https://github.com/TLQB/fclaude
Project-URL: Repository, https://github.com/TLQB/fclaude
Project-URL: Documentation, https://github.com/TLQB/fclaude/blob/main/README.md
Project-URL: Issues, https://github.com/TLQB/fclaude/issues
Project-URL: Changelog, https://github.com/TLQB/fclaude/blob/main/CHANGELOG.md
Author: free-claude contributors
License: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,claude,coding-assistant,free,llm,mcp,multi-agent,open-source,terminal,tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: fast
Requires-Dist: tiktoken>=0.5; extra == 'fast'
Provides-Extra: security
Requires-Dist: cryptography>=41.0; extra == 'security'
Requires-Dist: keyring>=24.0; extra == 'security'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">⚡ free-claude</h1>
  <p align="center">
    <strong>Free AI coding agent powered by Claude</strong><br>
    Built-in tools · Extended thinking · Multi-agent teams · MCP plugins
  </p>
  <p align="center">
    <a href="https://pypi.org/project/free-claude/"><img src="https://img.shields.io/pypi/v/free-claude?color=7c3aed&style=flat-square" alt="PyPI"></a>
    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python 3.8+"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT License"></a>
  </p>
</p>

---

A terminal-based AI coding agent that runs **Claude Opus 4, Sonnet 4, and Haiku** models — completely free through the **fclaude Gateway**. No API key required.

```
┌ fclaude • opus 4.6 • 🧠 adaptive
│
╰─❯ refactor the auth module to use JWT tokens

⚡ fclaude
I'll refactor the auth module. Let me start by examining the current code...

  ┌─ bash ─────────────────────────────────────────────
  │ find src/auth -name "*.py" -type f
  └────────────────────────────────────────────────────
```

## Why free-claude?

- **$0 cost** — uses the fclaude Gateway proxy, no Anthropic API key needed
- **Latest models** — Claude Opus 4.6, Sonnet 4.6, Haiku 4.5
- **Real tools** — executes bash, reads/writes files, fetches URLs, runs Python
- **MCP plugins** — connect any [Model Context Protocol](https://modelcontextprotocol.io) server
- **Thinking mode** — extended reasoning with configurable token budget
- **Multi-agent** — 7 specialist teammates working in parallel
- **Session memory** — save, resume, and carry context across conversations
- **Minimal** — only `rich` + `prompt_toolkit` as dependencies

---

## Installation

```bash
pip install free-claude
```

## Quick Start

```bash
# 1. Register (one-time, requires invite code)
fclaude-register --invite YOUR_INVITE_CODE

# 2. Start the agent
fclaude
```

> **No invite code?** Ask your team admin, or [self-host the Gateway](#self-hosting).

### One-shot mode

```bash
fclaude -q "explain this error" --cwd /my/project
fclaude -q "write unit tests for auth.py" -m sonnet4
```

### Choose a model

```bash
fclaude -m opus4    # Claude Opus 4.6 — most capable (default)
fclaude -m sonnet4  # Claude Sonnet 4.6 — fast + capable
fclaude -m haiku    # Claude Haiku 4.5 — fastest
```

### Extended thinking

```bash
fclaude --think                  # default budget: 8,000 tokens
fclaude --think-budget 16000     # custom budget
```

### MCP plugins

```bash
fclaude --plugin context7        # documentation search
fclaude --plugin serena           # code intelligence (LSP-powered)
fclaude --plugin context7 serena  # multiple plugins
```

---

## Models

| Shortcut | Model | Best for |
|----------|-------|----------|
| `opus4` | `claude-opus-4-6` | Complex coding, architecture — **default** |
| `sonnet4` | `claude-sonnet-4-6` | General coding, fast iteration |
| `haiku` | `claude-haiku-4-5` | Quick questions, summarization |

---

## Built-in Tools

| Tool | Description |
|------|-------------|
| `bash` | Execute shell commands |
| `read_file` | Read file contents |
| `write_file` | Write or create files |
| `edit_file` | Search-and-replace edits |
| `list_directory` | List files and directories |
| `web_fetch` | Fetch URL content (HTML, JSON, text) |
| `python_eval` | Execute Python code in isolated subprocess |
| `read_document` | Read PDF, Excel, Word, CSV, and images (Claude Vision) |
| `search` | Project-wide code search (ripgrep or Python fallback) |

---

## In-Chat Commands

<details>
<summary><strong>General</strong></summary>

| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/quit` | Exit |
| `/model [key]` | Switch model |
| `/clear` | Clear conversation |
| `/tools` | List available tools |
| `/usage` | Show token usage |

</details>

<details>
<summary><strong>Extended Thinking</strong></summary>

| Command | Description |
|---------|-------------|
| `/think` | Toggle thinking (default: 8,000 tokens) |
| `/think 16000` | Set custom budget |
| `/think off` | Disable |
| `/adaptive on/off` | Toggle adaptive thinking |

</details>

<details>
<summary><strong>Planning</strong></summary>

| Command | Description |
|---------|-------------|
| `/autoplan <goal>` | Auto-decompose goal into steps |
| `/plan show` | View current plan |
| `/plan next` | Execute next step |

</details>

<details>
<summary><strong>Multi-Agent Teams</strong></summary>

| Command | Description |
|---------|-------------|
| `/team <task>` | Auto-delegate to specialist (non-blocking) |
| `/team on/off` | Toggle auto-delegation |
| `/team status` | Show active delegations |
| `/inbox` | View teammate results |
| `/inbox apply` | Inject results into context |
| `/dashboard` | Live team dashboard (TUI) |

**Roles:** `code_reviewer` · `test_writer` · `debugger` · `refactorer` · `architect` · `security_auditor` · `docs_writer`

</details>

<details>
<summary><strong>Sessions & Memory</strong></summary>

| Command | Description |
|---------|-------------|
| `/save` | Save conversation |
| `/resume` | Resume last session |
| `/sessions` | List all sessions |
| `/export` | Export as Markdown |
| `/memory set <k> <v>` | Store persistent fact |
| `/memory get <k>` | Recall a fact |

</details>

<details>
<summary><strong>Search</strong></summary>

| Command | Description |
|---------|-------------|
| `/search <query>` | Search project files |
| `/index` | Index project for faster search |

</details>

---

## Python API

```python
from free_claude import Agent

# Basic usage
agent = Agent(model="opus4")
response = agent.run("List all Python files and count lines of code")

# With extended thinking
agent = Agent(model="opus4", thinking_budget=12000)
response = agent.run("Design a rate limiter for a distributed system")

# With MCP server
agent = Agent(
    mcp_servers={"fs": ["npx", "@mcp/server-filesystem", "/workspace"]}
)
response = agent.run("Read the config file and explain its structure")
```

---

## Authentication

free-claude uses the **fclaude Gateway** — a Cloudflare Workers proxy that handles auth and API routing.

```bash
# Register (one-time)
fclaude-register --invite YOUR_CODE

# Check your account
fclaude me

# Re-login if needed
fclaude login
```

| Detail | Value |
|--------|-------|
| Auth method | Email + password → JWT |
| Token storage | `~/.free_claude/token.json` (mode `0600`) |
| Access token | 24-hour expiry, auto-refreshed |
| Refresh token | 30-day expiry |
| Invite codes | Required for registration (from admin) |

> Your credentials never leave the Gateway. API keys are stored server-side only.

---

## Self-Hosting

The fclaude Gateway is a Cloudflare Worker you can deploy yourself:

```bash
cd gateway-cf
npm install
cp wrangler.toml.example wrangler.toml  # edit with your KV namespace IDs

# Set secrets
wrangler secret put ADMIN_EMAIL
wrangler secret put ADMIN_PASSWORD
wrangler secret put JWT_SECRET
wrangler secret put UPSTREAM_URL
wrangler secret put UPSTREAM_TOKEN

# Deploy
wrangler deploy
```

Then point your client:

```bash
export FREE_CLAUDE_API_BASE="https://your-worker.your-subdomain.workers.dev"
fclaude
```

The Gateway includes:
- **Admin dashboard** at `/admin` — user management, analytics, invite codes
- **Usage tracking** — per-user daily limits, token counting, request logs
- **Auto token refresh** — cron-based upstream token rotation
- **Plan system** — free (100/day), pro (1,000/day), vip (unlimited), admin

---

## Project Structure

```
free-claude/
├── src/free_claude/       # Python package
│   ├── cli.py             # CLI entry point
│   ├── agent.py           # Agent loop + commands
│   ├── config.py          # Models, API config
│   ├── auth.py            # Gateway authentication
│   ├── tools.py           # Built-in tool definitions
│   ├── mcp.py             # MCP client + plugin discovery
│   ├── core/              # Streaming, context management
│   ├── intelligence/      # Summarizer, memory, adaptive thinking
│   ├── session/           # Save/resume/export
│   └── ui/                # Rich terminal UI
├── gateway-cf/            # Cloudflare Worker gateway
│   └── src/index.js       # Auth, proxy, admin API, dashboard
├── tests/                 # Test suite
└── pyproject.toml         # Package config
```

---

## Contributing

```bash
git clone https://github.com/TLQB/fclaude
cd fclaude
pip install -e ".[dev]"
pytest
```

---

## License

[MIT](LICENSE)
