Metadata-Version: 2.5
Name: opencode-zen-adapter
Version: 1.0.0
Summary: OpenAI-compatible adapter for OpenCode Zen free models with automatic fingerprint gate bypass
Project-URL: Homepage, https://github.com/Nwokike/opencode-zen-adapter
Project-URL: Repository, https://github.com/Nwokike/opencode-zen-adapter
Author-email: Onyeka Nwokike <nwokikeonyeka@gmail.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: uvicorn[standard]>=0.30.0
Description-Content-Type: text/markdown

# OpenCode Zen Adapter

[![PyPI version](https://img.shields.io/pypi/v/opencode-zen-adapter.svg)](https://pypi.org/project/opencode-zen-adapter/)
[![Python versions](https://img.shields.io/pypi/pyversions/opencode-zen-adapter.svg)](https://pypi.org/project/opencode-zen-adapter/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A high-performance local proxy server that exposes an **OpenAI-compatible API** backed by **OpenCode Zen's Free Models**, featuring transparent gatekeeper bypass, dynamic model discovery, and an interactive Web Management Console.

Use OpenCode's free models with **ZCode**, **Claude Code CLI**, **Cursor**, **Cline**, or any custom agent **without an account, credit card, or API key**.

---

## 🏗️ How It Works

```text
┌──────────────────────────────────────────────────┐
│   Coding Client / AI Assistant                   │
│   (ZCode / Claude Code / Cursor / Cline / cURL)  │
└──────────────────────────────────────────────────┘
                         │
                         │ Standard OpenAI API format (stream / non-stream)
                         ▼
┌──────────────────────────────────────────────────┐
│   OpenCode Zen Adapter (This Server)             │
│   • Injects 3-condition fingerprint bypass       │
│   • Injects required placeholder tools           │
│   • Auto-routes: /chat/completions & /responses  │
│   • Buffers SSE stream for non-streaming clients │
│   • Web Management Console on http://127.0.0.1   │
└──────────────────────────────────────────────────┘
                         │
                         │ OpenCode CLI-fingerprinted HTTPS Stream
                         ▼
┌──────────────────────────────────────────────────┐
│   OpenCode Zen Gateway (opencode.ai/zen/v1)      │
│   (mimo-v2.5-free, nemotron-3.5-lightning-free,  │
│    nemotron-3-ultra-free, ling-3.0-flash-fin-free│
│    big-pickle, muse-spark-1.3-contributor-free)  │
└──────────────────────────────────────────────────┘
```

1. Receives requests in **OpenAI Chat Completions** or **Responses API** format.
2. Requires **zero authentication** (automatically authenticates with `Bearer public` or passes through your optional key).
3. Transparently injects OpenCode's gatekeeper fingerprint (`stream: true`, `tools: [shell, read]`, and `x-opencode-*` headers).
4. Dynamically routes between `/chat/completions` and `/responses` depending on the requested model.
5. If the client asked for non-streaming (`stream: false`), the adapter consumes the upstream SSE stream and aggregates it into a complete OpenAI `chat.completion` response.

---

## ⚡ Quick Start

### Option 1: Run with `uvx` (Recommended — Zero Installation)

```bash
uvx opencode-zen-adapter start
```

Or with the short alias:

```bash
uvx opencode-zen-adapter oza start
```

### Option 2: Install Globally with `uv` or `pip`

```bash
# Using uv (fastest)
uv tool install opencode-zen-adapter

# Or using standard pip
pip install opencode-zen-adapter
```

---

## 💻 CLI Commands

| Command | Description |
| :--- | :--- |
| `opencode-zen-adapter start` | Launch proxy server on `http://127.0.0.1:8082` |
| `opencode-zen-adapter test` | Real-time diagnostic probe testing latency and health across all free models |
| `opencode-zen-adapter models` | Discover and list all available models and their native endpoint formats |
| `opencode-zen-adapter status` | Check if the local adapter server is online and view uptime |
| `opencode-zen-adapter ui` | Open the interactive Web Management Console in your default browser |

---

## 🌐 Web Management Console

With the server running, visit **`http://127.0.0.1:8082/`** in your browser:

- **Live Service Health:** Real-time uptime, active port, and connection status to OpenCode Zen.
- **Model Sandbox:** Click "Test" on any model to send a real-time prompt and view response tokens and latency.
- **Dynamic Catalog:** Automatically displays newly added models from OpenCode Zen.
- **Interactive Connect Snippets:** Pre-formatted connection blocks for ZCode, Claude Code, Cursor, Cline, and Python.

---

## 🧠 Why This Exists (The 403 FreeTier Gatekeeper)

On September 19, 2026, OpenCode added a server-side gatekeeper to their free tier. Calling free models (`mimo-v2.5-free`, `nemotron-3.5-lightning-free`, `big-pickle`, etc.) from external clients began returning:

```json
403 FreeTierError: "OpenCode's free tier can only be used from within OpenCode"
```

### The 3 Gatekeeper Conditions (All Must Match Simultaneously)

1. **`stream: true`**: Non-streaming requests are rejected instantly with 403.
2. **Tool Declarations**: The request body's `tools` array must declare functions named `shell` (or `bash`) and `read`.
3. **Client Identification**: Headers must include `User-Agent: opencode/1.18.31` (or ≥ 1.17.0) and `x-opencode-client: cli` with a session ID matching `^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$`.

**This adapter automatically fulfills all 3 requirements on every request**, so you never see `FreeTierError` again.

---

## 🚀 Model Support & Endpoint Routing

OpenCode Zen serves models across different internal endpoints. The adapter automatically handles routing and payload translation:

| Model ID | Tier | Native Upstream Endpoint | Notes |
| :--- | :--- | :--- | :--- |
| **`mimo-v2.5-free`** | 🟢 FREE | `/chat/completions` | Full thinking & reasoning stream |
| **`nemotron-3.5-lightning-free`** | 🟢 FREE | `/chat/completions` | Ultra high-speed code generation |
| **`nemotron-3-ultra-free`** | 🟢 FREE | `/chat/completions` | High-accuracy reasoning |
| **`ling-3.0-flash-fin-free`** | 🟢 FREE | `/chat/completions` | Code and financial domain |
| **`big-pickle`** | 🟢 FREE | `/chat/completions` | OpenCode's internal coding model |
| **`muse-spark-1.3-contributor-free`** | 🟢 FREE | `/responses` | Uses OpenAI Responses format |
| **`muse-spark-1.2-contributor-free`** | 🟢 FREE | `/responses` | Uses OpenAI Responses format |

> **Dynamic Discovery:** Models are not hardcoded. The adapter queries `https://opencode.ai/zen/v1/models` dynamically, so whenever OpenCode adds new free models, they appear automatically!

---

## 🔌 Connecting Your Tools

### 1. ZCode Desktop
Configure a custom OpenAI provider:
- **Base URL:** `http://127.0.0.1:8082/v1`
- **API Key:** `test` (any string)
- **Model:** `mimo-v2.5-free` or `nemotron-3.5-lightning-free`

### 2. Claude Code CLI
```bash
# Set environment variables
export ANTHROPIC_BASE_URL="http://127.0.0.1:8082/v1"
export ANTHROPIC_AUTH_TOKEN="test"
export ANTHROPIC_MODEL="mimo-v2.5-free"

# Run Claude Code
claude
```

### 3. Cursor / Cline
- **API Type:** OpenAI Compatible
- **Base URL:** `http://127.0.0.1:8082/v1`
- **API Key:** `test`
- **Model ID:** `mimo-v2.5-free`, `nemotron-3.5-lightning-free`, `nemotron-3-ultra-free`, or `big-pickle`

### 4. Python (`openai` SDK)
```python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8082/v1",
    api_key="test",  # No key needed
)

response = client.chat.completions.create(
    model="mimo-v2.5-free",
    messages=[{"role": "user", "content": "Write a Python script to sort a list."}],
    stream=True,
)

for chunk in response:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)
```

---

## 🧪 Real-Time Model Diagnostics

Run `opencode-zen-adapter test` anytime to probe all models against the live upstream:

```bash
opencode-zen-adapter test
```

```text
                      OpenCode Zen Free Models Diagnostic                      
┌─────────────────────────┬──────────────────┬─────────────┬─────────┬─────────────────┐
│ Model ID                │ Native Endpoint  │ Status      │ Latency │ Notes / Message │
├─────────────────────────┼──────────────────┼─────────────┼─────────┼─────────────────┤
│ mimo-v2.5-free          │ /chat.completion │ ✅ ACTIVE   │ 1850 ms │ Ready           │
│ nemotron-3.5-lightning… │ /chat.completion │ ✅ ACTIVE   │ 1420 ms │ Ready           │
│ nemotron-3-ultra-free   │ /chat.completion │ ✅ ACTIVE   │ 1260 ms │ Ready           │
│ ling-3.0-flash-fin-free │ /chat.completion │ ✅ ACTIVE   │ 1880 ms │ Ready           │
│ big-pickle              │ /chat.completion │ ✅ ACTIVE   │ 2450 ms │ Ready           │
│ muse-spark-1.3-contrib… │ /response        │ ❌ BLOCKED  │  960 ms │ Upstream error  │
└─────────────────────────┴──────────────────┴─────────────┴─────────┴─────────────────┘
```

---

## 📦 Automated PyPI Publishing

This repository includes a fully configured **GitHub Actions workflow** (`.github/workflows/publish.yml`) that automatically builds and deploys to PyPI using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/):

### Trigger Publishing:
1. Create a git tag and push it:
   ```bash
   git tag v0.1.0
   git push origin v0.1.0
   ```
2. Or create a GitHub Release from the web interface.

The GitHub Action runs `uv build` and uploads the wheel and source distribution to PyPI automatically.

---

## 📄 License

MIT License. Open source and free for personal and commercial use.
