Metadata-Version: 2.4
Name: free-claude
Version: 0.2.0b1
Summary: Free Claude AI agent with tools and MCP support via fclaude API
Project-URL: Homepage, https://github.com/TLQB/fclaude
Project-URL: Repository, https://github.com/TLQB/fclaude
Project-URL: Issues, https://github.com/TLQB/fclaude/issues
Project-URL: Changelog, https://github.com/TLQB/fclaude/blob/main/CHANGELOG.md
License: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,claude,llm,mcp,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
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'
Description-Content-Type: text/markdown

# free-claude 🤖

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/free-claude.svg)](https://pypi.org/project/free-claude/)

**Free AI coding agent** with built-in tools, extended thinking, auto-planning, session memory, multi-agent teams, and MCP support. Zero cost, full power.

## ✨ Features

- 🆓 **Free** — uses the fclaude Gateway, no API key needed (`cost: $0`)
- 🧠 **Latest models** — claude-opus-4-6, claude-sonnet-4-6, and more
- 🔧 **Built-in tools** — bash, file read/write, web fetch, python eval, document reader
- 🔌 **MCP support** — connect any [Model Context Protocol](https://modelcontextprotocol.io) server
- 💬 **Interactive chat** — with full conversation history
- 🧠 **Extended Thinking** — deep reasoning mode with configurable token budget
- 🗺️ **Auto-planning** — automatically decomposes complex tasks into steps
- 💾 **Session system** — save, resume, and export conversations
- 🧬 **Long-term memory** — persistent facts and preferences across sessions
- 👥 **Multi-agent teams** — 7 specialized AI roles (architect, debugger, reviewer…)
- 📬 **Smart Inbox** — teammate results delivered asynchronously, never interrupts your flow
- 🔍 **Code search** — fast project-wide search with ripgrep or Python fallback
- 🔄 **Auto token refresh** — stays logged in automatically
- 📦 **Minimal dependencies** — only `rich` for terminal UI

---

## 📦 Installation

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

Or from source:
```bash
git clone https://github.com/TLQB/fclaude
cd free-claude
pip install -e .
```

---

## 🚀 Quick Start

```bash
# Step 1: Register (one-time — need invite code)
fclaude-register --invite YOUR_CODE

# Step 2: Start chatting!
fclaude
```

> Don't have an invite code? Ask your admin or self-host the Gateway.

### Single query mode
```bash
fclaude -q "list files in current directory"
fclaude -q "write a Python fibonacci function" -m sonnet4
fclaude -q "what's in README.md?" --cwd /my/project
```

### Choose model
```bash
fclaude -m opus4    # claude-opus-4-6 (newest, default)
fclaude -m sonnet4  # claude-sonnet-4-6
fclaude -m haiku    # claude-haiku-4-5 (fastest)
```

### Extended Thinking mode
```bash
fclaude --think                  # enable (default budget: 8,000 tokens)
fclaude --think-budget 16000     # custom budget
```

### With MCP plugins
```bash
fclaude --plugin context7        # documentation search
fclaude --plugin serena           # code intelligence
fclaude --plugin context7 serena  # multiple plugins
```

---

## 🤖 Models

| Key | Model | Notes |
|-----|-------|-------|
| `opus4` | claude-opus-4-6 | **Default** — most capable |
| `sonnet4` | claude-sonnet-4-6 | Fast + smart |
| `haiku` | claude-haiku-4-5 | Fastest |

---

## 💬 In-Chat Commands

### General
```
/help                   Show all commands
/quit                   Exit
/model [key]            Switch model
/clear                  Clear conversation
/tools                  List available tools
/usage                  Show token usage
```

### 🧠 Extended Thinking
```
/think                  Toggle on/off (default: 8,000 tokens)
/think 16000            Custom budget
/think off              Disable
```

### 🗺️ Auto-Planning
```
/autoplan <goal>        Decompose goal into steps
/plan show              View current plan
/plan next              Execute next step
```

### 👥 Multi-Agent Teams
```
/team <task>            Auto-delegate to specialist teammates (non-blocking!)
/team on/off            Toggle auto-delegation mode
/team status            Show active delegations
/inbox                  View teammate results
/inbox apply            Inject results into conversation context
/teammate add <role>    Add a teammate
/teammate ask <role> <q> Ask a teammate directly
/dashboard              Live TUI team dashboard
```

Available roles: `code_reviewer`, `test_writer`, `debugger`, `refactorer`, `architect`, `security_auditor`, `docs_writer`

### 💾 Sessions & Memory
```
/save                   Save conversation
/resume                 Resume last session
/memory set <k> <v>     Store persistent fact
/memory get <k>         Recall a fact
```

### 🔍 Search
```
/search <query>         Search project files
/index                  Index project files
```

---

## 🔧 Built-in Tools

| Tool | Description |
|------|-------------|
| `bash` | Execute shell commands |
| `read_file` | Read file contents |
| `write_file` | Write/create files |
| `edit_file` | String-replace edit |
| `list_directory` | List files and dirs |
| `web_fetch` | Fetch URL content |
| `python_eval` | Execute Python code |
| `read_document` | Read PDF, Excel, Word, CSV, images |
| `search` | Search project files |

---

## 🐍 Python API

```python
from free_claude import Agent

# Simple
agent = Agent(model="opus4")
response = agent.run("List files in /tmp and count them")

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

# With MCP
agent = Agent(
    mcp_servers={"fs": ["npx", "@mcp/server-filesystem", "/workspace"]}
)
```

---

## 🔐 Authentication

```bash
# First time: register with invite code
fclaude-register --invite YOUR_CODE

# Returning user: login
fclaude login
```

- Registration requires an **invite code** (from admin)
- Token stored at `~/.free_claude/token.json` (mode `0600`)
- Auto-refreshed — re-login only needed if refresh token expires (30 days)
- Uses the fclaude Gateway for auth + API proxy
- API keys never leave the server
- Check your account: `fclaude me`

---

## 📄 License

MIT — see [LICENSE](LICENSE)
