coder1-bridge

Coder1 Bridge CLI

Connect your local Claude CLI to the Coder1 IDE running in the cloud. This bridge enables you to use Claude Code commands from your browser-based IDE by routing them through your local machine.

🚀 Quick Start

Installation

Option 1: NPM Global Install (Recommended)

npm install -g coder1-bridge

Option 2: NPX (No Installation)

npx coder1-bridge start

Option 3: Pre-built Binaries

Download the appropriate binary for your platform:

Platform	Binary	Notes
macOS Apple Silicon (M1/M2/M3)	coder1-bridge-macos-arm64	For newer Macs
macOS Intel	coder1-bridge-macos-x64	For older Macs
Linux x64	coder1-bridge-linux	Most Linux distros
Windows x64	coder1-bridge-win.exe	Windows 10/11

After downloading:

# macOS/Linux: Make executable
chmod +x coder1-bridge-*

# Run
./coder1-bridge-macos-arm64 start  # or your platform's binary

Option 4: Direct from Source

git clone https://github.com/MichaelrKraft/coder1-ide.git
cd coder1-ide/coder1-ide-next/bridge-cli
npm install
npm start

Usage

• Open Coder1 IDE in your browser:

  • Production: https://coder1.ai
  • Local: http://localhost:3001

• Generate a Pairing Code in the IDE:

  • Click the "Connect Bridge" button in the terminal
  • Or use the status bar bridge indicator
  • A 6-digit code will be displayed

• Start the Bridge on your local machine:

  coder1-bridge start
  

• Enter the Pairing Code when prompted:

  Enter the 6-digit pairing code from the IDE: 123456
  

• Success! You'll see:

  ✅ Bridge connected successfully!
  

• Use Claude in the IDE terminal:

  claude analyze
  claude fix "error message"
  claude explain function.js
  

📋 Prerequisites

• Node.js 18.0.0 or higher
• Claude CLI installed from https://claude.ai/download
• Coder1 IDE account (for cloud version)

🛠️ Commands

coder1-bridge start

Start the bridge service and connect to Coder1 IDE.

Options:

• -s, --server <url> - Server URL (default: https://coder1.ai)
• -d, --dev - Development mode (connects to localhost:3001)
• -v, --verbose - Enable verbose logging
• --no-banner - Skip banner display

Examples:

# Connect to production
coder1-bridge start

# Connect to local development
coder1-bridge start --dev

# Connect to custom server
coder1-bridge start --server https://my-coder1.com

# Verbose mode for debugging
coder1-bridge start --verbose

coder1-bridge status

Check if the bridge service is available on the server.

coder1-bridge status
# Output: ✅ Bridge service is online

coder1-bridge test

Test your local Claude CLI installation.

coder1-bridge test
# Output: ✅ Claude CLI is installed and working

🔧 Configuration

Environment Variables

Create a .env file in your project directory:

# Server configuration
CODER1_SERVER=https://coder1.ai

# Bridge settings
BRIDGE_VERBOSE=true
BRIDGE_AUTO_RECONNECT=true
BRIDGE_MAX_RECONNECT_ATTEMPTS=10

# Security (optional)
BRIDGE_JWT_SECRET=your-secret-key

Working Directory

The bridge runs in your current directory by default. Claude commands will execute in this context:

cd ~/my-project
coder1-bridge start
# Claude commands will run in ~/my-project

🔐 Security

How It Works

• Pairing Code: One-time 6-digit code expires after 5 minutes
• JWT Token: Secure token for authenticated WebSocket connection
• TLS/WSS: All connections encrypted
• Command Sanitization: Dangerous commands are blocked
• Path Validation: Prevents directory traversal attacks

What Bridge Can Access

• ✅ Files in your current working directory
• ✅ Claude CLI on your machine
• ✅ Git repositories you have access to
• ❌ Cannot access system files without permission
• ❌ Cannot run arbitrary shell commands

🐛 Troubleshooting

Bridge Won't Connect

Check Claude CLI:

coder1-bridge test

Check Server Status:

coder1-bridge status

Try Verbose Mode:

coder1-bridge start --verbose

"Claude CLI not found"

• Install Claude Code from https://claude.ai/download
• Restart your terminal
• Verify installation:

  which claude
  claude --version
  

"Invalid pairing code"

• Codes expire after 5 minutes
• Generate a new code in the IDE
• Ensure you're connecting to the correct server

Connection Drops

The bridge auto-reconnects by default. If it doesn't:

• Check your internet connection
• Restart the bridge
• Generate a new pairing code

🏗️ Architecture

Your Machine                    Cloud/Server
┌─────────────┐                ┌──────────────┐
│ Claude CLI  │◄───┐           │  Coder1 IDE  │
└─────────────┘    │           ├──────────────┤
                   │           │   Terminal   │
┌─────────────┐    │    WSS    │   Editor     │
│Coder1 Bridge│◄───┼──────────►│   Preview    │
└─────────────┘    │           └──────────────┘
                   │                   ▲
┌─────────────┐    │                   │
│Local Files  │◄───┘                   │
└─────────────┘                     Browser

📊 Performance

• Latency: < 100ms command routing overhead
• Throughput: Streams output in real-time
• Concurrent Commands: Up to 5 simultaneous
• File Operations: < 500ms for files under 1MB
• Auto-reconnect: Within 1-30 seconds

🤝 Contributing

Development Setup

git clone https://github.com/MichaelrKraft/coder1-ide.git
cd coder1-ide/coder1-ide-next/bridge-cli
npm install
npm link  # Makes 'coder1-bridge' available globally

Running Tests

npm test

Development Mode

# Connect to local IDE server
node src/index.js start --dev --verbose

📚 API Reference

WebSocket Events

Client → Server:

• heartbeat - Keep-alive signal
• claude:output - Stream command output
• claude:complete - Command finished
• file:response - File operation result

Server → Client:

• claude:execute - Execute command request
• file:request - File operation request
• config:update - Configuration change
• connection:accepted - Pairing successful

Error Codes

• 1001 - Invalid pairing code
• 1002 - Token expired
• 1003 - Unauthorized
• 2001 - Command timeout
• 2003 - Claude not found
• 3001 - File not found
• 3002 - Permission denied

📝 License

MIT License - See LICENSE file for details

🆘 Support

• Issues: https://github.com/MichaelrKraft/coder1-ide/issues
• Discord: https://discord.gg/coder1
• Email: [e-mail]

Built with ❤️ for the Coder1 community