Metadata-Version: 2.4
Name: free-claude
Version: 0.1.4
Summary: Free Claude AI agent with tools and MCP support via HFI API
Project-URL: Homepage, https://github.com/yourusername/free-claude
Project-URL: Repository, https://github.com/yourusername/free-claude
Project-URL: Issues, https://github.com/yourusername/free-claude/issues
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: 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.9+](https://img.shields.io/badge/python-3.9+-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 Claude AI agent** (claude-opus-4-6 and others) with built-in tools, extended thinking, auto-planning, session memory, multi-agent teams, and MCP support. Zero cost, full power.

## ✨ Features

- 🆓 **Free** — uses Claude via HFI API proxy (`costUSD: 0`)
- 🧠 **Latest models** — claude-opus-4-6, claude-sonnet-4-6, and more
- 🔧 **Built-in tools** — bash, file read/write, web fetch, python eval, directory listing
- 🔌 **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** — Claude 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** — specialized AI roles (architect, debugger, reviewer…)
- 🔍 **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/yourusername/free-claude
cd free-claude
cp .env.example .env   # fill in your OAuth credentials
pip install -e .
```

---

## ⚙️ Setup

All configuration is done via environment variables. Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

```env
# .env
FREE_CLAUDE_OAUTH_DOMAIN=your-tenant.us.auth0.com
FREE_CLAUDE_OAUTH_CLIENT_ID=your-client-id
FREE_CLAUDE_OAUTH_AUDIENCE=https://your-api-audience/
FREE_CLAUDE_API_BASE=https://your-proxy/api_proxy
```

> **Note:** `clientId` is a public OAuth PKCE value — not a secret. The actual API key never leaves the proxy server.

---

## 🚀 Quick Start

```bash
# Step 1: Login (one-time setup — opens browser)
fclaude-login

# Step 2: Start chatting!
fclaude
```

### 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 opus     # claude-opus-4-5-20251101
fclaude -m haiku    # claude-haiku-4-5-20251001 (fastest)
```

### Extended Thinking mode
```bash
fclaude --think                  # enable with default budget (8,000 tokens)
fclaude --think-budget 16000     # custom budget
fclaude --think -q "design a distributed cache system"
```

### With MCP server
```bash
fclaude --mcp fs npx @modelcontextprotocol/server-filesystem /home/user
fclaude --mcp gh npx @modelcontextprotocol/server-github
```

---

## 🤖 Models

| Key | Model | Notes |
|-----|-------|-------|
| `opus4` | claude-opus-4-6 | **Default** — newest, most capable |
| `sonnet4` | claude-sonnet-4-6 | Fast + smart |
| `opus` | claude-opus-4-5-20251101 | Stable eval version |
| `sonnet` | claude-sonnet-4-5-20250929 | Stable eval version |
| `haiku` | claude-haiku-4-5-20251001 | Fastest, cheapest |

---

## 💬 In-Chat Commands

### General
```
/help                   Show all commands
/quit                   Exit
/model [key]            Switch model (e.g. /model sonnet4)
/clear                  Clear conversation history
/system [text]          View or update system prompt
/cd <path>              Change working directory
/tools                  List available tools
```

### 🧠 Extended Thinking
```
/think                  Toggle extended thinking on/off (default: 8,000 tokens)
/think 16000            Enable with custom token budget
/think off              Disable thinking mode
```
When active, Claude shows a 🧠 panel with its internal reasoning before answering.

### 🗺️ Auto-Planning
```
/autoplan <goal>        Ask Claude to decompose a goal into ordered steps
/plan show              Show current plan and progress
/plan next              Execute and advance to the next step
/plan done              Mark current step as completed
/plan new <goal>        Start a new manual plan
/plan reset             Clear the current plan
```

**Example:**
```
/autoplan refactor the authentication module to use JWT
→ Claude creates a 7-step plan
→ /plan next — executes step 1
→ /plan done — marks it done, advances
```

### 💾 Sessions
```
/save [name]            Save current conversation
/resume [id]            Resume a saved session
/sessions               List recent sessions
/export [md|json]       Export conversation to file
/checkpoint             Quick-save current state
/restore                Restore from last checkpoint
```

### 🧬 Memory
```
/memory set <key> <val>     Store a persistent fact
/memory get <key>           Recall a stored fact
/memory forget <key>        Delete a memory entry
/memory search <query>      Search across memories
/memory list                List all stored memories
```

**Example:**
```
/memory set project "Django REST API with PostgreSQL"
/memory set style "always use type hints and docstrings"
# Next session: Claude remembers these automatically
```

### 👥 Multi-Agent Teams
```
/team <task>            Delegate to a specialist team
/team list              List available roles
```
Available roles: `architect`, `code_reviewer`, `debugger`, `tester`, `documenter`, `optimizer`, `security`

### 🔍 Search
```
/search <query>             Search code in project
/search <query> *.py        Filter by file type
```

### 🔌 MCP
```
/mcp <name> <command>   Add MCP server at runtime
```

---

## 🔧 Built-in Tools

| Tool | Description |
|------|-------------|
| `bash` | Execute shell commands (subprocess, safe) |
| `read_file` | Read file contents |
| `write_file` | Write/create files |
| `list_dir` | List directory contents |
| `web_fetch` | Fetch URLs and extract text |
| `python_eval` | Execute Python code in isolated subprocess |

---

## 🔌 MCP Support

Connect any MCP server for extended capabilities:

```bash
# Filesystem access
fclaude --mcp fs npx @modelcontextprotocol/server-filesystem /workspace

# Multiple servers
fclaude \
  --mcp fs npx @mcp/server-filesystem . \
  --mcp db npx @mcp/server-postgres postgresql://localhost/mydb
```

In chat:
```
/mcp github npx @modelcontextprotocol/server-github
```

---

## 🐍 Python API

```python
from free_claude import Agent

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

# With system prompt
agent = Agent(
    model="sonnet4",
    system="You are a Python expert. Always write clean, typed code."
)
response = agent.run("Write a binary search function")
print(response)

# With Extended Thinking
agent = Agent(model="opus4", thinking_budget=12000)
response = agent.run("Design a fault-tolerant microservices architecture")
print(response)

# With MCP
agent = Agent(
    model="opus4",
    mcp_servers={"fs": ["npx", "@modelcontextprotocol/server-filesystem", "/workspace"]}
)
print(agent.run("Read the README and summarize it"))

# Multi-turn conversation
agent = Agent()
agent.run("My name is Alice and I work on a Django project")
response = agent.run("What stack should I use for background jobs?")
print(response)
```

---

## 🔐 Authentication

Login uses OAuth PKCE flow (no client secret required):

```bash
fclaude-login    # Opens browser, saves token to ~/.free_claude/token.json
```

- Token is stored at `~/.free_claude/token.json` (mode `0600`)
- Auto-refreshed using refresh token — re-login only needed if refresh token expires
- Never committed to git (listed in `.gitignore`)

---

## 📄 License

MIT — see [LICENSE](LICENSE)
