Content
# cline.code 🎉
### Claude Code Bridge for Cline
**Use Claude Code with the Cline VS Code extension through a simple OpenAI-compatible bridge.**
## 🚀 **What is cline.code?**
`cline.code` makes Claude Code work with the Cline VS Code extension. It's a bridge that translates between Cline's OpenAI API format and Claude's MCP (Model Context Protocol).
**🎉 BREAKTHROUGH: Fully Working with Cline!**
After extensive debugging and solving multiple critical compatibility issues, the bridge now provides complete Cline integration. See [BREAKTHROUGH_SOLUTION.md](./docs/BREAKTHROUGH_SOLUTION.md) for the technical journey.
This bridge enables the Cline VS Code extension to work with Claude AI by:
- Accepting OpenAI-formatted requests from Cline
- Communicating with Claude via the MCP (Model Context Protocol)
- Returning responses in OpenAI-compatible format
- **Full streaming support (SSE)** for real-time responses
### ✅ **What Works:**
- **🎯 Cline VS Code Extension** - Complete integration with all features
- **📂 File Operations**: Create, read, modify files through Cline
- **⚡ Command Execution**: Run shell commands via Claude
- **🧠 Planning & Execution**: Support for Cline's PLAN and ACT modes
- **📡 Streaming Support**: Real-time responses with Server-Sent Events
- **🔧 Tool Integration**: Full XML tool processing for Cline compatibility
## 💡 **The Story Behind This**
Hey! 👋 I'm someone who **loves Claude Code** - it's my main go-to coding assistant. I kept seeing people in forums and Discord asking "Can I use Claude with Cline?" The Cline VS Code extension is amazing, but it only worked with OpenAI.
I thought: *"This sounds like a fun personal challenge... I wonder if I can make Claude work with Cline?"*
**Spoiler alert: I did!** 🎉
After lots of experimenting, I figured out how to use Claude's MCP (Model Context Protocol) server as a bridge. This adapter sits between Cline and Claude Code, translating API calls so they work together perfectly.
## ⚠️ **Real Talk**
This is a **personal project** I built for fun and to help the community. Here's what that means:
- **Things might break** 🔧 (I'm just one person!)
- **I'll do my best** to fix issues and respond to questions
- **Your help is invaluable** - testing, bug reports, and contributions are super welcome!
- **It's unofficial** - not affiliated with Anthropic or any IDE companies
## 🛠️ **How It Works**
`cline.code` leverages Anthropic's official [Model Context Protocol (MCP) server functionality](https://docs.anthropic.com/en/docs/claude-code/tutorials#use-claude-code-as-an-mcp-server) built into Claude Code. Here's the complete architecture:
```mermaid
graph TD
A[Cline VS Code Extension] -->|OpenAI API format| B[cline.code Bridge<br/>Express.js Server]
B -->|JSON-RPC calls| C[Claude MCP Server<br/>claude mcp serve]
C -->|Task tool requests| D[Claude AI<br/>Anthropic's API]
D -->|AI responses| C
C -->|MCP responses| B
B -->|OpenAI format| A
E[Your Authentication<br/>Claude CLI login] -.->|Credentials| C
F[File System<br/>Your Project] -.->|Access| A
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#fce4ec
style F fill:#f1f8e9
```
### 🔧 **Component Breakdown:**
#### **1. Cline VS Code Extension**
- Sends standard OpenAI API requests (`/v1/chat/completions`)
- Expects OpenAI-format responses with `choices`, `usage`, etc.
- Handles file operations, command execution through tool calls
#### **2. cline.code Bridge (This Project)**
- **Express.js server** on `localhost:8000`
- **Protocol translator** between Cline's OpenAI format and Claude's MCP
- **Streaming support** - Converts to Server-Sent Events for Cline
- **Tool processing** - Handles XML tool tags for Cline's PLAN/ACT modes
#### **3. Claude MCP Server (Official Anthropic)**
- **Spawned automatically** by our gateway using `claude mcp serve`
- **JSON-RPC 2.0** communication over stdio pipes
- **Task tool** - The key discovery! Uses the `Task` tool to send prompts to Claude
- **Official implementation** - We're using Anthropic's own MCP server
#### **4. Claude AI (Anthropic's API)**
- **The actual AI** - Claude Sonnet, Opus, etc.
- **Your authentication** - Uses your Claude CLI credentials
- **Smart responses** - Understands context and generates appropriate tool usage
### 🎯 **The Magic Happens Here:**
1. **Cline Request**: `POST /v1/chat/completions` with OpenAI format
2. **Bridge Translation**: Converts to MCP `tools/call` with `Task` tool
3. **MCP Communication**: JSON-RPC over stdio to Claude MCP server
4. **Claude Processing**: AI generates response with tool usage (XML tags)
5. **Response Translation**: Converts back to OpenAI format with `choices` array
6. **Cline Receives**: Standard OpenAI response that Cline understands perfectly
### 🔑 **Key Technical Insights:**
- **Official MCP Server**: We discovered Claude Code has a built-in MCP server mode
- **Task Tool**: The `Task` tool is Claude's gateway for chat-style interactions
- **XML Tool Processing**: Cline expects specific XML tool formats for file operations
- **Streaming Translation**: Cline requires Server-Sent Events, not JSON responses
- **Mode Detection**: Handle Cline's PLAN MODE vs ACT MODE workflows
✅ **WORKING SOLUTION** - Successfully tested with Cline!
- ✅ Full OpenAI API compatibility
- ✅ Streaming support (Server-Sent Events)
- ✅ XML tool format compatibility
- ✅ Production code structure
- ✅ Configuration management & authentication
## Quick Start
### 1. Install and Run
```bash
# Clone the repository
git clone https://github.com/vanzan01/cline.code.git
cd cline.code
# Install dependencies
npm install
# Run the production server (recommended for local use)
HOST=127.0.0.1 PORT=8000 AUTH_ENABLED=false npm start
# Or simple start (binds to all interfaces)
npm start
# Or run in development mode with auto-reload
npm run dev
```
That's it! The bridge is now running on http://localhost:8000
### 2. Test the Bridge
```bash
# In a new terminal, test with curl:
curl -X POST http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "claude-code",
"messages": [{"role": "user", "content": "Hello"}]
}'
```
### 3. Try the Demo Applications
```bash
# Run the minimal POC demo
npm run demo:minimal
# Or try the chatbot demo
# With the bridge running, open demos/chatbot/claude-bridge-chatbot-demo/index.html in your browser
```
## Configuration
The bridge supports environment variables for production configuration:
### Server Configuration
```bash
PORT=3000 # Server port (default: 8000)
HOST=localhost # Server host (default: 0.0.0.0)
```
### Authentication (Optional)
```bash
AUTH_ENABLED=true # Enable API key validation (default: false)
API_KEYS=key1,key2,key3 # Comma-separated list of valid API keys
```
### Logging
```bash
LOG_LEVEL=debug # Logging level: info, debug (default: info)
LOGGING_ENABLED=true # Enable request logging (default: true)
```
### MCP Configuration
```bash
MCP_COMMAND=claude # Claude CLI command (default: claude)
MCP_TIMEOUT=15000 # MCP initialization timeout ms (default: 10000)
```
## Configuration Examples
### Server Configuration
```bash
# Default setup (port 8000, all interfaces)
npm start
curl http://localhost:8000/health
# Custom port
PORT=3000 npm start
curl http://localhost:3000/health
# Localhost only (more secure for development)
HOST=localhost PORT=3000 npm start
curl http://localhost:3000/health
# Production setup
HOST=0.0.0.0 PORT=8080 npm start
curl http://localhost:8080/health
```
### Authentication Examples
```bash
# Enable authentication with API keys
AUTH_ENABLED=true API_KEYS=key1,key2,key3 npm start
# Test with valid API key
curl -H "Authorization: Bearer key1" http://localhost:8000/health
# Test with invalid key (should get 401)
curl -H "Authorization: Bearer wrong-key" http://localhost:8000/health
# Test without key (should get 401)
curl http://localhost:8000/health
```
### Logging Examples
```bash
# Default logging (info level)
npm start
curl http://localhost:8000/health
# See: [2025-05-27T08:13:13.316Z] GET /health - 200 - 3ms
# Debug logging (detailed JSON)
LOG_LEVEL=debug npm start
curl http://localhost:8000/health
# See detailed request info in JSON format
# Disable logging
LOGGING_ENABLED=false npm start
curl http://localhost:8000/health
# No request logs (only startup logs)
```
### Combined Examples
```bash
# Development setup
HOST=localhost PORT=3000 LOG_LEVEL=debug npm start
# Production-like setup
PORT=8080 AUTH_ENABLED=true API_KEYS=prod-key LOG_LEVEL=info npm start
curl -H "Authorization: Bearer prod-key" http://localhost:8080/health
# High-performance setup (no logging)
PORT=8000 LOGGING_ENABLED=false MCP_TIMEOUT=5000 npm start
```
## Project Structure
```
cline.code/
├── src/ # Production implementation
│ ├── index.js # Application entry point
│ ├── app.js # Express app configuration
│ ├── services/ # Business logic
│ │ └── mcp/ # MCP client implementation
│ ├── routes/ # API endpoints
│ ├── middleware/ # Express middleware
│ └── config/ # Configuration (Phase 2)
├── demos/ # Working demonstrations
│ ├── minimal-bridge/ # Minimal POC that works
│ └── chatbot/ # Example chatbot using the bridge
├── docs/ # Documentation
│ ├── README.md # Documentation overview
│ ├── PRODUCTION_UPGRADE_PLAN.md # Roadmap for production
│ └── architecture/ # Design specs and diagrams
├── tests/ # Test suite (coming soon)
└── CHANGELOG.md # Version history
```
## How It Works
1. **Startup**: Bridge automatically spawns Claude MCP server as child process
2. **Client** (e.g., Cursor IDE) sends OpenAI-format request to bridge
3. **Bridge** receives request on OpenAI-compatible endpoints
4. **Bridge** communicates with Claude MCP server via JSON-RPC over stdio
5. **Claude MCP** processes request using the Task tool
6. **Bridge** parses and formats response in OpenAI format
7. **Client** receives standard OpenAI response
## Key Discovery
The Claude MCP server exposes a `Task` tool that enables chat functionality:
- Method: `tools/call` with `name: "Task"`
- Sends prompts to Claude AI
- Returns responses in nested JSON structure
## Requirements
- Node.js 18+
- Claude Code CLI installed and authenticated
- WSL (if running on Windows)
## 🧪 **Using cline.code with Cline**
### ✅ **Setup Instructions**
1. Install [Cline VS Code Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
2. Start cline.code: `npm start`
3. Configure Cline to use `http://localhost:8000` as the OpenAI API endpoint
4. Try creating files, running commands, asking questions - it should all work!
### 🤔 **Help Make It Better**
**Making it more robust:**
- Cline-specific edge cases
- Error scenarios
- Performance improvements
- Better documentation
### 🙌 **How You Can Help**
**🐛 Found a bug with Cline?**
- Open an issue with details (what happened, error messages)
- I'll do my best to fix it quickly
**💡 Got an idea?**
- Cline-specific feature requests welcome
- Architecture improvements
- Better Cline integration ideas
**🔧 Want to contribute code?**
- Fork it, fix it, PR it!
- All skill levels welcome
- Even small improvements are hugely appreciated
**📢 Just want to test?**
- Try different Cline workflows and let me know what works (or doesn't)
- Share your Cline setup tips
Remember: This project exists to make Claude work perfectly with Cline! 🚀
## Development
```bash
# Clone and setup
git clone https://github.com/vanzan01/cline.code.git
cd cline.code
npm install
# Run the production server (one command - handles everything!)
npm start
# Or run in development mode with auto-reload
npm run dev
# In another terminal, test it
curl http://localhost:8000/health
# Test the chat endpoint
curl -X POST http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "claude-code", "messages": [{"role": "user", "content": "Hello"}]}'
# Run tests
node tests/integration/openai-compatibility.test.js
node tests/manual/basic-functionality.js
```
## Documentation
- [Production Upgrade Plan](docs/PRODUCTION_UPGRADE_PLAN.md) - Roadmap for incremental production development
- [Architecture Specification](docs/architecture/claude-code-openai-bridge-spec.md) - Detailed technical design (legacy)
- [Source Code Documentation](src/README.md) - Production code structure
- [Documentation Overview](docs/README.md) - Guide to all documentation
- [Changelog](CHANGELOG.md) - Version history and updates
## Roadmap
### Phase 1 - Core Implementation ✅ COMPLETE
- [x] Proof of concept
- [x] Basic demos
- [x] Modular production structure
- [x] MCPClient class implementation
- [x] Route separation
### Phase 2 - Configuration & Auth ✅ COMPLETE
- [x] Configuration management (environment variables)
- [x] API key validation (configurable authentication)
- [x] Request logging middleware
- [x] Error handling middleware
- [x] Environment-based settings
### Phase 3 - Additional Endpoints
- [ ] GET /v1/models endpoint
- [ ] Model listing
### Phase 4 - Advanced Features
- [ ] Connection resilience
- [ ] Request queuing
- [ ] Streaming responses
### Phase 5 - Production Ready
- [ ] Comprehensive testing
- [ ] Docker support
- [ ] Cline-specific optimizations
See [PRODUCTION_UPGRADE_PLAN.md](docs/PRODUCTION_UPGRADE_PLAN.md) for detailed roadmap.
## 📋 **Contributing**
This project started as my personal challenge, but I'd love to turn it into something the whole community can benefit from!
### 🎯 **What I'm Looking For**
**🧪 Testers:**
- Try cline.code with different Cline workflows and use cases
- Report what works and what doesn't
- Help me understand how Cline behaves in different scenarios
**🔧 Developers:**
- Improve Cline-specific compatibility and features
- Improve error handling and edge cases
- Make the code more robust and maintainable
**📚 Writers:**
- Cline setup guides and tutorials
- Troubleshooting documentation
- Improve the README and docs
### 💭 **Philosophy**
I built this because I love Claude Code and wanted to share it with people who love Cline. The goal is simple: **make Claude work perfectly with Cline**.
This isn't about building a business or becoming the "official" solution. It's about solving a real problem that Cline users have and doing it in the open where everyone can benefit.
### 🤝 **How to Contribute**
1. **Start small** - even fixing typos or improving error messages helps!
2. **Open an issue first** for bigger features so we can discuss the approach
3. **Test thoroughly** - include steps to reproduce and test your changes
4. **Be patient** - this is a side project, but I'll do my best to respond quickly
### 🎉 **Credit Where Credit's Due**
If you contribute something meaningful, I'll make sure you get credit in the README and releases. This is a community effort!
### ☕ **Support This Project**
If `cline.code` saves you time or you'd like to see more tools like this, consider [sponsoring me on GitHub](https://github.com/sponsors/vanzan01)!
**More coffee = More code = More awesome tools for the community!** ☕→💻→🚀
Even small contributions help keep me motivated to build cool stuff and respond to issues quickly. Plus, sponsors get my eternal gratitude and maybe early access to new experiments! 😊
## ⚠️ **Important Disclaimers**
- **Unofficial**: Not affiliated with Anthropic, Cline, or any IDE companies
- **Personal Project**: Built by one person in their spare time
- **No Warranties**: Use at your own risk, things might break
- **Community Driven**: Success depends on people like you testing and contributing
- **Requires Claude Access**: You need your own Claude Code authentication
## License
MIT License - See [LICENSE](./LICENSE) file
**TL;DR:** Use it, modify it, share it, contribute to it! Just keep the license notice. 🎉
