cline.code

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 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 built into Claude Code. Here's the complete architecture:

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

# 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

# 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

# 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

PORT=3000                    # Server port (default: 8000)
HOST=localhost              # Server host (default: 0.0.0.0)

Authentication (Optional)

AUTH_ENABLED=true           # Enable API key validation (default: false)
API_KEYS=key1,key2,key3     # Comma-separated list of valid API keys

Logging

LOG_LEVEL=debug             # Logging level: info, debug (default: info)
LOGGING_ENABLED=true        # Enable request logging (default: true)

MCP Configuration

MCP_COMMAND=claude          # Claude CLI command (default: claude)
MCP_TIMEOUT=15000          # MCP initialization timeout ms (default: 10000)

Configuration Examples

Server Configuration

# 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

# 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

# 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

# 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
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

# 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 - Roadmap for incremental production development
• Architecture Specification - Detailed technical design (legacy)
• Source Code Documentation - Production code structure
• Documentation Overview - Guide to all documentation
• Changelog - Version history and updates

Roadmap

Phase 1 - Core Implementation ✅ COMPLETE

• Proof of concept
• Basic demos
• Modular production structure
• MCPClient class implementation
• Route separation

Phase 2 - Configuration & Auth ✅ COMPLETE

• Configuration management (environment variables)
• API key validation (configurable authentication)
• Request logging middleware
• Error handling middleware
• 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 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!

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 file

TL;DR: Use it, modify it, share it, contribute to it! Just keep the license notice. 🎉