agentrelay-cli 0.5.1__tar.gz

agentrelay_cli-0.5.1/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest tests/ -v

agentrelay_cli-0.5.1/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-agentrelay-cli:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-claude-relay-compat:
+    runs-on: ubuntu-latest
+    needs: publish-agentrelay-cli
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build compatibility package
+        run: |
+          python - <<'PY'
+          import pathlib
+          import tomllib
+
+          root = pathlib.Path(".")
+          version = tomllib.loads((root / "pyproject.toml").read_text())["project"]["version"]
+
+          compat_root = root / "compat" / "claude-relay"
+          pkg_dir = compat_root / "src" / "claude_relay_compat"
+          pkg_dir.mkdir(parents=True, exist_ok=True)
+          (pkg_dir / "__init__.py").write_text('__all__ = ["__version__"]\n__version__ = "' + version + '"\n')
+
+          (compat_root / "README.md").write_text(
+              "# claude-relay (compatibility package)\n\n"
+              "Deprecated compatibility package. Install `agentrelay-cli` for canonical updates.\n"
+          )
+
+          (compat_root / "pyproject.toml").write_text(
+              f'''[project]
+              name = "claude-relay"
+              version = "{version}"
+              description = "Compatibility package; use agentrelay-cli"
+              readme = "README.md"
+              requires-python = ">=3.10"
+              dependencies = ["agentrelay-cli=={version}"]
+
+              [build-system]
+              requires = ["hatchling"]
+              build-backend = "hatchling.build"
+
+              [tool.hatch.build.targets.wheel]
+              packages = ["src/claude_relay_compat"]
+              '''
+          )
+          PY
+          uv build compat/claude-relay --out-dir compat/claude-relay/dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: compat/claude-relay/dist

agentrelay_cli-0.5.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+CLAUDE.md
+*.egg-info/
+uv.lock

agentrelay_cli-0.5.1/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md — Agent Relay
+
+## What this is
+
+Drop-in OpenAI & Anthropic API-compatible server that routes requests through `claude -p` CLI.
+
+## Quick setup
+
+**Prerequisites:** `claude` CLI installed and on PATH, Python 3.10+, `uv`
+
+```bash
+# Install and run
+uvx agent-relay serve
+
+# Or from source
+git clone https://github.com/npow/claude-relay.git
+cd claude-relay && uv sync && uv run agent-relay serve
+```
+
+Default: `http://0.0.0.0:8082`. Override with `--host` / `--port`.
+
+## Configuring clients
+
+**OpenAI SDK (Python):**
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:8082/v1", api_key="unused")
+response = client.chat.completions.create(
+    model="sonnet", messages=[{"role": "user", "content": "Hello"}], stream=True
+)
+```
+
+**Anthropic SDK (Python):**
+```python
+from anthropic import Anthropic
+client = Anthropic(base_url="http://localhost:8082", api_key="unused")
+response = client.messages.create(
+    model="sonnet", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+**LangChain:**
+```python
+from langchain_openai import ChatOpenAI
+llm = ChatOpenAI(base_url="http://localhost:8082/v1", api_key="unused", model="sonnet")
+```
+
+**curl:**
+```bash
+curl http://localhost:8082/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Server + CLI status |
+| GET | `/v1/models` | List available models |
+| POST | `/v1/chat/completions` | OpenAI-compatible chat |
+| POST | `/v1/messages` | Anthropic-compatible messages |
+
+All endpoints also available without `/v1` prefix (e.g. `/models`, `/chat/completions`, `/messages`).
+
+## Models
+
+| Model | Notes |
+|-------|-------|
+| `opus` | Most capable |
+| `sonnet` | **Default** if omitted |
+| `haiku` | Fastest |
+
+Passed directly to `claude --model`.
+
+## Ignored parameters
+
+These are silently discarded — Claude Code CLI does not expose them:
+
+`temperature`, `max_tokens`, `top_p`, `top_k`, `n`, `tools`, `tool_choice`, `functions`, `function_call`, `response_format`
+
+Image/audio content blocks are stripped to text-only.
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Health check fails | `curl http://localhost:8082/health` — verify `claude` is on PATH |
+| `claude` not found | Ensure CLI installed: `which claude`. Restart shell if just installed |
+| Slow responses (~2-3s overhead) | Expected — each request spawns a `claude -p` subprocess |
+| Images/audio ignored | Only text content is extracted from multimodal messages |
+| No tool calling | Claude Code uses its own tools internally; tool parameters are ignored |
+| CORS errors | CORS is enabled for all origins by default |
+
+## Development
+
+**Source layout:**
+```
+src/claude_relay/
+├── __init__.py        # Version
+├── __main__.py        # CLI entry point (argparse)
+└── server.py          # FastAPI app, all endpoints and logic
+tests/
+└── test_server.py     # Unit + integration tests
+```
+
+**Run tests:**
+```bash
+uv sync
+uv run pytest tests/ -v
+```

agentrelay_cli-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 npow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentrelay_cli-0.5.1/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: agentrelay-cli
+Version: 0.5.1
+Summary: OpenAI- and Anthropic-compatible API server that routes through agent CLIs
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.34
+Description-Content-Type: text/markdown
+
+# agent-relay
+
+[![CI](https://github.com/npow/claude-relay/actions/workflows/ci.yml/badge.svg)](https://github.com/npow/claude-relay/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentrelay-cli)](https://pypi.org/project/agentrelay-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Drop-in OpenAI **and Anthropic** API server that routes through agent CLIs (currently [Claude Code](https://docs.anthropic.com/en/docs/claude-code)).
+
+> Compatibility note: `claude-relay` remains available as a compatibility package/command alias.
+
+## Why
+
+You have tools that speak the OpenAI or Anthropic API. You have Claude Code with its tools, MCP servers, and agentic capabilities. **agent-relay** bridges the two — point any compatible client at it and every request flows through `claude -p` under the hood.
+
+- **Use Claude Code from any OpenAI or Anthropic client** — Cursor, Continue, aider, LangChain, custom scripts
+- **Keep Claude Code's superpowers** — tool use, MCP servers, file access, shell execution
+- **Zero config** — if `claude` works on your machine, so does this
+- **Real token usage** — reports actual token counts from Claude (not zeros)
+- **Token-level streaming** — uses `--include-partial-messages` for true real-time deltas
+
+## Install
+
+```bash
+# With uv (recommended)
+uvx agent-relay serve
+
+# Or install globally
+uv tool install agentrelay-cli
+agent-relay serve
+
+# Or from source
+git clone https://github.com/npow/claude-relay.git
+cd claude-relay
+uv sync
+uv run agent-relay serve
+```
+
+## Quick start
+
+```bash
+agent-relay serve
+# Server starts on http://localhost:18082
+```
+
+### Run as background service (macOS)
+
+```bash
+# Install and auto-start on login
+agent-relay service install
+```
+
+The installer will offer to add these to your `~/.zshrc` (or `~/.bashrc`) so every SDK and agent picks up the relay automatically:
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:18082"
+export OPENAI_BASE_URL="http://127.0.0.1:18082/v1"
+```
+
+```bash
+# Check status
+agent-relay service status
+
+# Update
+uv tool upgrade agentrelay-cli
+agent-relay service restart
+
+# Stop and remove
+agent-relay service uninstall
+```
+
+Point any OpenAI-compatible client at it:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:18082/v1", api_key="unused")
+
+# Streaming
+for chunk in client.chat.completions.create(
+    model="sonnet",
+    messages=[{"role": "user", "content": "Hello!"}],
+    stream=True,
+):
+    print(chunk.choices[0].delta.content or "", end="")
+
+# Non-streaming
+resp = client.chat.completions.create(
+    model="sonnet",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.choices[0].message.content)
+```
+
+### Anthropic SDK
+
+```python
+import anthropic
+
+# Just set the base URL — the SDK reads ANTHROPIC_BASE_URL automatically
+# export ANTHROPIC_BASE_URL=http://localhost:18082
+client = anthropic.Anthropic(base_url="http://localhost:18082")
+
+# Streaming
+with client.messages.stream(
+    model="sonnet",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="")
+
+# Non-streaming
+resp = client.messages.create(
+    model="sonnet",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.content[0].text)
+```
+
+### LangChain
+
+```python
+from langchain_anthropic import ChatAnthropic
+
+# export ANTHROPIC_BASE_URL=http://localhost:18082
+llm = ChatAnthropic(model="sonnet")
+print(llm.invoke("Hello!").content)
+```
+
+### curl
+
+```bash
+# OpenAI format
+curl http://localhost:18082/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","messages":[{"role":"user","content":"Hello"}],"stream":true}'
+
+# OpenAI Responses format
+curl http://localhost:18082/v1/responses \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","input":"Hello"}'
+
+# Anthropic format
+curl http://localhost:18082/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Configuration
+
+```
+agent-relay serve [--host HOST] [--port PORT]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--host` | `0.0.0.0` | Bind address |
+| `--port` | `18082` | Bind port |
+
+## API
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible) |
+| `/v1/responses` | POST | Responses API (OpenAI-compatible) |
+| `/v1/messages` | POST | Messages (Anthropic-compatible) |
+| `/v1/models` | GET | List available models |
+| `/health` | GET | Server and CLI status |
+
+All endpoints also work without the `/v1` prefix. CORS is enabled for all origins.
+
+### Supported features
+
+| Feature | Status |
+|---|---|
+| Streaming (SSE) | Yes |
+| System messages | Yes (via `--system-prompt`) |
+| Multi-turn conversations | Yes |
+| Multimodal (text parts) | Yes |
+| Model selection | Yes |
+| Token usage reporting | Yes |
+| CORS | Yes |
+
+### Models
+
+Pass any model name — it goes directly to `claude --model`:
+
+| Model | Description |
+|---|---|
+| `opus` | Most capable |
+| `sonnet` | Balanced (default) |
+| `haiku` | Fastest |
+
+## Limitations
+
+- `temperature`, `max_tokens`, `top_p`, and other sampling parameters are ignored (Claude Code CLI does not expose them)
+- No tool/function calling passthrough (Claude Code uses its own tools internally, but they aren't exposed via the OpenAI tool-calling protocol)
+- Each request spawns a new `claude` process (~2-3s overhead on top of API latency)
+- No image/audio content forwarding — only text parts of multimodal messages are extracted
+
+## How it works
+
+```
+OpenAI client     ─┐
+                    ├→  claude-relay  →  claude -p  →  Anthropic API
+Anthropic client  ─┘     (FastAPI)      (stream-json)
+```
+
+Each request spawns a `claude -p` process with `--output-format stream-json --include-partial-messages`. The proxy translates between the OpenAI or Anthropic wire format and Claude Code's streaming JSON protocol. Requests are stateless — no conversation history bleeds between calls.
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+```
+
+## License
+
+[MIT](LICENSE)

agentrelay_cli-0.5.1/README.md

@@ -0,0 +1,222 @@
+# agent-relay
+
+[![CI](https://github.com/npow/claude-relay/actions/workflows/ci.yml/badge.svg)](https://github.com/npow/claude-relay/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentrelay-cli)](https://pypi.org/project/agentrelay-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Drop-in OpenAI **and Anthropic** API server that routes through agent CLIs (currently [Claude Code](https://docs.anthropic.com/en/docs/claude-code)).
+
+> Compatibility note: `claude-relay` remains available as a compatibility package/command alias.
+
+## Why
+
+You have tools that speak the OpenAI or Anthropic API. You have Claude Code with its tools, MCP servers, and agentic capabilities. **agent-relay** bridges the two — point any compatible client at it and every request flows through `claude -p` under the hood.
+
+- **Use Claude Code from any OpenAI or Anthropic client** — Cursor, Continue, aider, LangChain, custom scripts
+- **Keep Claude Code's superpowers** — tool use, MCP servers, file access, shell execution
+- **Zero config** — if `claude` works on your machine, so does this
+- **Real token usage** — reports actual token counts from Claude (not zeros)
+- **Token-level streaming** — uses `--include-partial-messages` for true real-time deltas
+
+## Install
+
+```bash
+# With uv (recommended)
+uvx agent-relay serve
+
+# Or install globally
+uv tool install agentrelay-cli
+agent-relay serve
+
+# Or from source
+git clone https://github.com/npow/claude-relay.git
+cd claude-relay
+uv sync
+uv run agent-relay serve
+```
+
+## Quick start
+
+```bash
+agent-relay serve
+# Server starts on http://localhost:18082
+```
+
+### Run as background service (macOS)
+
+```bash
+# Install and auto-start on login
+agent-relay service install
+```
+
+The installer will offer to add these to your `~/.zshrc` (or `~/.bashrc`) so every SDK and agent picks up the relay automatically:
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:18082"
+export OPENAI_BASE_URL="http://127.0.0.1:18082/v1"
+```
+
+```bash
+# Check status
+agent-relay service status
+
+# Update
+uv tool upgrade agentrelay-cli
+agent-relay service restart
+
+# Stop and remove
+agent-relay service uninstall
+```
+
+Point any OpenAI-compatible client at it:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:18082/v1", api_key="unused")
+
+# Streaming
+for chunk in client.chat.completions.create(
+    model="sonnet",
+    messages=[{"role": "user", "content": "Hello!"}],
+    stream=True,
+):
+    print(chunk.choices[0].delta.content or "", end="")
+
+# Non-streaming
+resp = client.chat.completions.create(
+    model="sonnet",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.choices[0].message.content)
+```
+
+### Anthropic SDK
+
+```python
+import anthropic
+
+# Just set the base URL — the SDK reads ANTHROPIC_BASE_URL automatically
+# export ANTHROPIC_BASE_URL=http://localhost:18082
+client = anthropic.Anthropic(base_url="http://localhost:18082")
+
+# Streaming
+with client.messages.stream(
+    model="sonnet",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="")
+
+# Non-streaming
+resp = client.messages.create(
+    model="sonnet",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.content[0].text)
+```
+
+### LangChain
+
+```python
+from langchain_anthropic import ChatAnthropic
+
+# export ANTHROPIC_BASE_URL=http://localhost:18082
+llm = ChatAnthropic(model="sonnet")
+print(llm.invoke("Hello!").content)
+```
+
+### curl
+
+```bash
+# OpenAI format
+curl http://localhost:18082/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","messages":[{"role":"user","content":"Hello"}],"stream":true}'
+
+# OpenAI Responses format
+curl http://localhost:18082/v1/responses \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","input":"Hello"}'
+
+# Anthropic format
+curl http://localhost:18082/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{"model":"sonnet","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Configuration
+
+```
+agent-relay serve [--host HOST] [--port PORT]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--host` | `0.0.0.0` | Bind address |
+| `--port` | `18082` | Bind port |
+
+## API
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/v1/chat/completions` | POST | Chat completions (OpenAI-compatible) |
+| `/v1/responses` | POST | Responses API (OpenAI-compatible) |
+| `/v1/messages` | POST | Messages (Anthropic-compatible) |
+| `/v1/models` | GET | List available models |
+| `/health` | GET | Server and CLI status |
+
+All endpoints also work without the `/v1` prefix. CORS is enabled for all origins.
+
+### Supported features
+
+| Feature | Status |
+|---|---|
+| Streaming (SSE) | Yes |
+| System messages | Yes (via `--system-prompt`) |
+| Multi-turn conversations | Yes |
+| Multimodal (text parts) | Yes |
+| Model selection | Yes |
+| Token usage reporting | Yes |
+| CORS | Yes |
+
+### Models
+
+Pass any model name — it goes directly to `claude --model`:
+
+| Model | Description |
+|---|---|
+| `opus` | Most capable |
+| `sonnet` | Balanced (default) |
+| `haiku` | Fastest |
+
+## Limitations
+
+- `temperature`, `max_tokens`, `top_p`, and other sampling parameters are ignored (Claude Code CLI does not expose them)
+- No tool/function calling passthrough (Claude Code uses its own tools internally, but they aren't exposed via the OpenAI tool-calling protocol)
+- Each request spawns a new `claude` process (~2-3s overhead on top of API latency)
+- No image/audio content forwarding — only text parts of multimodal messages are extracted
+
+## How it works
+
+```
+OpenAI client     ─┐
+                    ├→  claude-relay  →  claude -p  →  Anthropic API
+Anthropic client  ─┘     (FastAPI)      (stream-json)
+```
+
+Each request spawns a `claude -p` process with `--output-format stream-json --include-partial-messages`. The proxy translates between the OpenAI or Anthropic wire format and Claude Code's streaming JSON protocol. Requests are stateless — no conversation history bleeds between calls.
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+```
+
+## License
+
+[MIT](LICENSE)