CC Mobile Controller

Control Claude Code from your phone via WeChat Mini Program.

---

What is CC Mobile Controller?

CC Mobile Controller is a system that lets you interact with Claude Code running on your computer from your phone, using a WeChat Mini Program as the mobile interface.

Phone (WeChat Mini Program)
        ↓ WebSocket
Bridge Server (Node.js)
        ↓ Claude Code CLI
Your Computer

Key Features:

• Switch between multiple workspaces
• Real-time streaming responses
• Token-based authentication
• Multi-workspace support
• Voice input (iFlytek API)

---

How It Works

1. Bridge Server runs on your computer, managing Claude Code sessions
2. ngrok creates a public tunnel to your local server
3. WeChat Mini Program connects to the public URL
4. Messages are sent via WebSocket, responses stream back in real-time

---

Quick Start

Prerequisites

• Node.js 20+
• Claude Code CLI installed
• ngrok account (free)
• WeChat Developer Tools

Step 1: Install Bridge Server

cd bridge-server
npm install
cp .env.example .env
# Edit .env with your configuration

Step 2: Configure Environment

Edit .env:

PORT=3000
AUTH_TOKEN=your-strong-token-at-least-32-chars
WS_WORKSPACE=D:/path/to/your/workspace
WS_KNOWLEDGE=D:/path/to/your/knowledge
WS_CODEDEV=D:/path/to/your/codedev
LOG_LEVEL=info

Step 3: Start Bridge Server

npm run dev

Step 4: Start ngrok

ngrok http 3000

Note the public URL (e.g., https://xxx.ngrok-free.dev).

Step 5: Configure Mini Program

1. Open WeChat Developer Tools
2. Import miniprogram/ directory
3. Go to Settings page
4. Enter server URL: wss://xxx.ngrok-free.dev/ws
5. Enter your AUTH_TOKEN
6. Test connection

---

Configuration

Bridge Server (.env)

Variable	Description	Example
PORT	Server port	3000
AUTH_TOKEN	Access token (≥32 chars)	your-secret-token
WS_WORKSPACE	Workspace path	D:/workspace
WS_KNOWLEDGE	Knowledge base path	D:/knowledge
WS_CODEDEV	Code dev path	D:/codedev
LOG_LEVEL	Log level	info

ngrok Setup

# Install
winget install Ngrok.Ngrok  # Windows
brew install ngrok            # macOS

# Configure
ngrok config add-authtoken YOUR_AUTHTOKEN

# Start
ngrok http 3000

WeChat Mini Program

The mini program needs:

• Server URL: wss://your-domain/ws
• Token: Same as AUTH_TOKEN in .env

---

Architecture

┌─────────────────────────────────┐
│        WeChat Mini Program      │
│  (Workspace selection, Chat)    │
└────────────┬────────────────────┘
             │ WebSocket (wss://)
             │ Bearer Token auth
┌────────────▼────────────────────┐
│         ngrok Tunnel            │
│  (Public URL → Local port)      │
└────────────┬────────────────────┘
             │ localhost:3000
┌────────────▼────────────────────┐
│       Bridge Server             │
│  (Fastify + WebSocket)          │
│  - Session management           │
│  - Token authentication         │
│  - Claude Code integration      │
└──────┬──────────┬──────┬────────┘
       │          │      │
  ┌────▼───┐ ┌───▼──┐ ┌─▼──────┐
  │Workspace│ │Knowl.│ │Code Dev│
  └────────┘ └──────┘ └────────┘
       └──────────┴──────┘
       Claude Code CLI

---

Project Structure

cc-mobile-controller/
├── README.md
├── LICENSE
├── .gitignore
├── bridge-server/
│   ├── package.json
│   ├── tsconfig.json
│   ├── .env.example
│   ├── src/
│   │   ├── index.ts
│   │   ├── config.ts
│   │   ├── auth.ts
│   │   ├── cc-adapter.ts
│   │   ├── speech.ts
│   │   ├── session/
│   │   └── ws/
│   └── ecosystem.config.js
├── miniprogram/
│   ├── app.json
│   ├── app.js
│   ├── app.wxss
│   ├── pages/
│   │   ├── index/
│   │   ├── chat/
│   │   └── settings/
│   ├── components/
│   │   ├── code-block/
│   │   └── voice-input/
│   └── utils/
│       ├── ws.js
│       └── storage.js
└── docs/
    ├── QUICKSTART.md
    ├── INSTALLATION.md
    ├── SECURITY.md
    ├── TROUBLESHOOTING.md
    └── ARCHITECTURE.md

---

Security Notes

Important: This tool is designed for personal local use.

• Keep Bridge Server local — Do not expose directly to the internet
• Use strong tokens — AUTH_TOKEN must be at least 32 characters
• Use ngrok carefully — Free ngrok URLs change on each restart
• Token protection — Never commit .env files or share tokens
• Workspace access — Claude Code has access to your workspace files

Do not deploy publicly without proper security measures.

---

Troubleshooting

Cannot connect to server

1. Check Bridge Server is running (npm run dev)
2. Check ngrok is running (ngrok http 3000)
3. Verify server URL format: wss://xxx.ngrok-free.dev/ws
4. Verify token matches .env configuration

Claude Code not available

# Check Claude Code CLI
claude --version

# If not found, install from https://claude.ai/code

ngrok URL changed

ngrok free tier assigns a new URL on each restart. Update the URL in Mini Program settings.

WebSocket connection failed

• Ensure "不校验合法域名" is enabled in WeChat Developer Tools (for testing)
• For production, configure proper domain in WeChat backend

---

Roadmap

v1.0 (Current)

• ✅ Bridge Server with Fastify
• ✅ WeChat Mini Program
• ✅ Multi-workspace support
• ✅ Streaming responses
• ✅ Token authentication
• ✅ Voice input (iFlytek API)

Future

• Fixed domain support
• Multi-user support
• File sharing
• Message history persistence
• More AI model support

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

License

MIT License — see LICENSE for details.

---

Acknowledgments

• Claude Code — AI coding assistant
• Fastify — Web framework
• ngrok — Tunnel service
• WeChat Mini Program — Mobile platform

---

CC Mobile Controller — Control Claude Code from your phone.