claude-ds

# claude-ds [English](./README.en.md) | <p align="center"> <img src="assets/banner.png" alt="claude-ds banner" width="100%"> </p> > A cost-effective alternative to Claude Code's default backend -- same experience, a fraction of the cost. ## What is this? [Claude Code](https://code.claude.com/docs/en/overview) is an AI-powered coding assistant developed by Anthropic, capable of reading code, modifying files, running commands, and managing Git. However, it uses the Claude Opus model by default, which costs **$25 per million tokens**, making it expensive. **claude-ds** offers a low-cost solution by replacing the backend with [DeepSeek V4](https://api-docs.deepseek.com/), while maintaining the same tools, workflows, and built-in features, **saving 7~89 times the cost**. This is a practical alternative for developers who want to save money without switching tools. | Model | Output Price (per million tokens) | Compared to Opus | |------|:----------------------:|:---------:| | Claude Opus 4.7 | $25.00 | 1x | | DeepSeek V4-Pro | $3.48 (promotion: $0.87 ¹) | **7x cheaper (~29x during promotion)** | | DeepSeek V4-Flash | $0.28 | **89x cheaper** | > ¹ DeepSeek V4-Pro is currently on a 75% discount promotion until **2026-05-31 15:59 UTC**, with a discounted price of $0.87/million output tokens. The price will return to $3.48 after the promotion ends. Please refer to [DeepSeek's official pricing page](https://api-docs.deepseek.com/quick_start/pricing) for the latest prices. ## Before you start 1. **Claude Code CLI** -- `curl -fsSL https://claude.ai/install.sh | bash` or `npm install -g @anthropic-ai/claude-code` ([official documentation](https://code.claude.com/docs/en/overview)) 2. **DeepSeek API key** -- apply on [platform.deepseek.com](https://platform.deepseek.com/api_keys) 3. **Python 3.10+** -- only required for image recognition features (optional) ## Quick Start ```bash # 1. Clone git clone https://github.com/danielzhangau/claude-ds.git cd claude-ds # 2. Install (interactive, will prompt for API key) ./install.sh # 3. Reload shell source ~/.zshrc # or ~/.bashrc # 4. Start using claude-ds # V4-Pro -- complex coding, architecture design, refactoring claude-ds-flash # V4-Flash -- small changes, simple tasks ``` That's it. `claude-ds` and `claude-ds-flash` can directly replace the `claude` command. All features of Claude Code (slash commands, `/compact`, Agent tool, hooks, MCP servers) are available. See [known limitations](#known-limitations) for edge cases. > If you find Claude Code useful but expensive, and don't want to switch to another tool, try this. ## Project Structure | Component | Description | |------|------| | **Shell functions** | `claude-ds` / `claude-ds-flash` commands, environment variables set up | | **Vision MCP server** | adds image recognition capability to text models (optional) | | **Vision guard hook** | intercepts image reads and forwards to Vision MCP | | **One-click installation script** | interactive setup for all configurations | ## How it works `claude-ds` is a thin wrapper -- it redirects `claude` API requests to DeepSeek instead of Anthropic using environment variables. Claude Code remains unchanged, as DeepSeek provides an [Anthropic-compatible interface](https://api-docs.deepseek.com/guides/anthropic_api). No code changes, no additional proxies required, and it works out of the box. <p align="center"> <img src="assets/architecture.svg" alt="architecture diagram" width="100%"/> </p> **Two modes:** - **`claude-ds`** (Pro mode) -- main conversation uses V4-Pro (1M context), internal tasks use V4-Flash. Suitable for heavy tasks. - **`claude-ds-flash`** (Flash mode) -- all tasks use V4-Flash. Most cost-effective. <p align="center"> <img src="assets/model-tiers.svg" alt="model routing" width="100%"/> </p> <details> <summary><strong>Environment Variables (advanced)</strong></summary> These variables were reverse-engineered from Claude Code 2.1.x binaries (verified in v2.1.71 and reconfirmed in 2.1.133). Most third-party tutorials miss a few critical ones, which are highlighted below. | Variable | Purpose | What happens if not set | |------|-----------|-----------| | `ANTHROPIC_BASE_URL` | points requests to DeepSeek | uses Anthropic (subscription required) | | `ANTHROPIC_AUTH_TOKEN` | DeepSeek API key | authentication fails | | `ANTHROPIC_MODEL` | main conversation model | uses Claude model name (API error) | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus tier mapping | uses `claude-opus-*` | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet tier mapping | uses `claude-sonnet-*` | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku tier mapping | uses `claude-haiku-*` | | **`ANTHROPIC_SMALL_FAST_MODEL`** | **internal lightweight tasks (binary references)** | **uses `claude-haiku-*` -- silently fails** | | `CLAUDE_CODE_SUBAGENT_MODEL` | Agent tool sub-agent model | falls back to Sonnet tier | | `CLAUDE_CODE_MAX_RETRIES` | API 503 retry count | no retries (direct failure) | | `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | prevents model name rewriting | may break `deepseek-v4-*` | | `CLAUDE_CODE_EFFORT_LEVEL` | thinking depth | `auto` (DeepSeek recommends `max`) | These don't need to be set manually -- `install.sh` handles them. This table is for understanding the underlying mechanics. > **Note**: default model names (`deepseek-v4-pro[1m]`, `deepseek-v4-flash`) may change with DeepSeek API updates. Refer to [DeepSeek's official documentation](https://api-docs.deepseek.com/) for the latest information. You can override using `CLAUDE_DS_PRO_MODEL` / `CLAUDE_DS_FLASH_MODEL` environment variables. </details> <details> <summary><strong>Vision MCP Server (optional)</strong></summary> DeepSeek V4 is a text-only model and cannot recognize images. The Vision MCP server forwards image recognition requests to models that support vision (any OpenAI-compatible interface), filling this gap. **Two tools:** | Tool | Description | |------|------| | `see_image` | recognizes images from disk (absolute path) | | `see_clipboard` | recognizes images from system clipboard | Both support an optional `question` parameter -- omitting it returns a complete description, while providing it gives a targeted answer. **Supported vision backends:** Any OpenAI-compatible vision API works, here are a few examples: | Vendor | Model | Endpoint | |------|------|----------| | Alibaba Cloud Baizhan | `qwen3-vl-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | | OpenAI | `gpt-4o` | `https://api.openai.com/v1` | | Groq | `meta-llama/llama-4-scout-17b-16e-instruct` | `https://api.groq.com/openai/v1` | | Local Ollama | `llama3.2-vision` | `http://localhost:11434/v1` | **Vision guard hook:** `vision-guard.sh` is a PreToolUse hook -- when the model attempts to read an image using `Read`, the hook intercepts it and redirects to `see_image`. This is a hard constraint, independent of CLAUDE.md prompts. <p align="center"> <img src="assets/vision-flow.svg" alt="Vision guard hook flow" width="100%"/> </p> Behavior: - intercepts `Read` calls for image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`) - only effective when `ANTHROPIC_BASE_URL` points to a non-Anthropic endpoint - returns exit code 2 with a "use `see_image`" prompt - **native Claude Opus unaffected** (it has built-in multimodal capabilities and doesn't need this) </details> ## Known Limitations | Issue | Solution | |------|--------| | Ctrl+V paste image may report 400 error with text backend | save image to file and use `see_image`; or use `see_clipboard` | | paste image error may corrupt session ([#19031](https://github.com/anthropics/claude-code/issues/19031)) | `/rewind` or double Esc to revert; otherwise, start a new session | | DeepSeek API 503 errors during peak hours | `MAX_RETRIES=3` will retry automatically | | response quality may degrade after 500K tokens | use `/compact` to compress context in long sessions | | V4 thinking mode `reasoning_content` may report 400 after multiple rounds | restart session | | `claude-ds` cannot `/resume` sessions started with `claude` | no solution -- backend differs | | no automatic switching between Anthropic/DeepSeek | manual selection of `claude-ds` or `claude` required | | moving repository directory may invalidate installation | re-run `./install.sh` | ## Uninstall ```bash ./install.sh --uninstall ``` or manual cleanup: 1. remove `claude-ds` / `claude-ds-flash` functions from `~/.zshrc` (or `~/.bashrc`) 2. delete `~/.claude/claude-ds-vision-mcp.json` 3. remove `"vision-guard"` hook from `~/.claude/settings.json` 4. remove permissions for `"mcp__vision"` from `~/.claude/settings.json` ## License MIT --- *All product names, logos, and brands are the property of their respective owners. Use of these names does not imply any endorsement.* ## Acknowledgements - [Claude Code](https://code.claude.com/docs/en/overview) -- Anthropic - [DeepSeek V4](https://api-docs.deepseek.com/) -- DeepSeek - Vision MCP server based on [clipboard-vision-mcp](https://github.com/Capetlevrai/clipboard-vision-mcp) (Capetlevrai)