@naarang/ccc 1.0.15 → 1.1.0-beta.2

package/README.md

@@ -20,12 +20,20 @@ CCC is a powerful CLI tool that creates a bridge between [Claude Code](https://c
   <a href="https://play.google.com/store/apps/details?id=com.naarang.ccc">
     <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/GetItOnGooglePlay_Badge_Web_color_English.png?alt=media&token=d2f34558-ce96-4882-9225-8ded76f759ba" alt="Get it on Google Play" height="80">
   </a>
+  <br/>
+  <a href="https://play.google.com/apps/testing/com.naarang.ccc">
+    <sub>Join Android Beta Testing</sub>
+  </a>
 </p>
 
 <p align="center">
   <a href="https://apps.apple.com/in/app/ccc-ui-for-coding-agents/id6753870766">
     <img src="https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg" alt="Download on the App Store" height="80">
   </a>
+  <br/>
+  <a href="https://testflight.apple.com/join/bEVNMrNH">
+    <sub>Join iOS Beta Testing (TestFlight)</sub>
+  </a>
 </p>
 
 ## ✨ Features
@@ -33,6 +41,7 @@ CCC is a powerful CLI tool that creates a bridge between [Claude Code](https://c
 - **Mobile Control** - Chat with Claude from your phone or tablet
 - **Real-time Sync** - See Claude's responses instantly on your device
 - **Smart Permission System** - Fine-grained control over code modifications
+- **Web Terminal Access** 🆕 (Beta) - Full terminal access in mobile app with authentication
 - **Remote Access** - Optional ngrok integration for access from anywhere
 - **Secure MQTT** - Built-in MQTT broker with authentication support
 - **Session Management** - Persistent sessions across reconnections
@@ -66,10 +75,14 @@ ccc
 
 The server will start and display:
 ```
-✓ Claude Chat Backend v1.0.5 started successfully
+✓ Claude Chat Backend v1.1.0 started successfully
 
 Server URLs (Add one of these in the app settings):
-  • Local:  192.168.1.100:8883
+  Localhost: localhost:8080
+  Network:   192.168.1.100:8080
+
+Services:
+  MQTT:      Port 8883 (via /mqtt)
 ```
 
 ### 2. Configure the Mobile App
@@ -99,15 +112,20 @@ Open the app, create a project pointing to your local directory, and start chatt
 ccc [options]
 
 Options:
-  --debug                      Enable debug logging
-  -u, --username <user>        MQTT broker username
-  -p, --password <pass>        MQTT broker password
-  --port <port>                MQTT broker port (default: 8883)
-  -t, --ngrok-token <token>    ngrok auth token (enables public tunnel)
-  --ngrok-domain <domain>      ngrok static domain
-  --no-auto-update             Disable automatic updates (enabled by default)
-  -v, --version                Show version number
-  -h, --help                   Show help message
+  --debug                           Enable debug logging
+  -u, --username <user>             MQTT broker username
+  -p, --password <pass>             MQTT broker password
+  --mqtt-port <port>                Internal MQTT broker port (default: 8883)
+  --port <port>                     [DEPRECATED] Use --mqtt-port instead
+  --router-port <port>              Router port for ngrok (default: 8080)
+  --terminal-port <port>            Internal terminal server port (default: 3001)
+  --terminal-username <user>        Terminal authentication username (enables terminal)
+  --terminal-password <pass>        Terminal authentication password (enables terminal)
+  -t, --ngrok-token <token>         ngrok auth token (enables public tunnel)
+  --ngrok-domain <domain>           ngrok static domain
+  --no-auto-update                  Disable automatic updates (enabled by default)
+  -v, --version                     Show version number
+  -h, --help                        Show help message
 ```
 
 > **Auto-Update**: By default, CCC checks for updates on startup and automatically downloads the latest version. After a successful update, you'll be prompted to manually restart the server. Use `--no-auto-update` to disable this behavior.
@@ -124,19 +142,26 @@ ccc
 ccc -u admin -p secret
 ```
 
+**With terminal access (Beta):**
+```bash
+ccc --terminal-username admin --terminal-password secret
+```
+
 **With ngrok for remote access:**
 ```bash
 ccc --ngrok-token YOUR_NGROK_TOKEN
 ```
 
-**Custom port with debug logging:**
+**Full example with ngrok, authentication, and terminal:**
 ```bash
-ccc --port 9000 --debug
+ccc --ngrok-token YOUR_TOKEN \
+    --terminal-username admin \
+    --terminal-password secret
 ```
 
-**Full example with ngrok and authentication:**
+**Custom ports with debug logging:**
 ```bash
-ccc -u admin -p secret -t YOUR_TOKEN --ngrok-domain myapp.ngrok.app
+ccc --mqtt-port 9000 --terminal-port 3002 --debug
 ```
 
 ### Environment Variables
@@ -144,15 +169,126 @@ ccc -u admin -p secret -t YOUR_TOKEN --ngrok-domain myapp.ngrok.app
 Create a `.env` file in your working directory:
 
 ```env
+# MQTT Configuration
 MQTT_BROKER_PORT=8883
 MQTT_USERNAME=your-username
 MQTT_PASSWORD=your-password
+
+# Router Configuration
+ROUTER_PORT=8080
+
+# Terminal Configuration (Beta)
+TERMINAL_PORT=3001
+TERMINAL_USERNAME=your-terminal-username
+TERMINAL_PASSWORD=your-terminal-password
+
+# Ngrok Configuration
 NGROK_AUTH_TOKEN=your-ngrok-token
 NGROK_DOMAIN=your-custom-domain.ngrok.app
 ```
 
 > **Note:** CLI arguments override environment variables
 
+## 🖥️ Terminal Access (Beta)
+
+CCC now includes a built-in web terminal that can be accessed directly from the mobile app. This feature is currently in **beta** and provides full terminal access to your development environment.
+
+### Enabling Terminal Access
+
+Terminal access is **opt-in** for security reasons. To enable it, you must provide authentication credentials:
+
+```bash
+ccc --terminal-username admin --terminal-password your-secure-password
+```
+
+Or via environment variables:
+```env
+TERMINAL_USERNAME=admin
+TERMINAL_PASSWORD=your-secure-password
+```
+
+### How It Works
+
+1. **Architecture:**
+   - Internal terminal server runs on port 3001 (localhost only)
+   - Proxied through the main router on `/terminal` path
+   - Full terminal emulation with bash/powershell support
+
+2. **Security Features:**
+   - Basic authentication required for all connections
+   - Rate limiting: max 5 failed auth attempts (15-minute IP block)
+   - Session limit: maximum 5 concurrent terminals
+   - Bound to localhost only (never exposed directly)
+   - All connections must go through authenticated router
+
+3. **Mobile Integration:**
+   - Terminal embedded in mobile app
+   - Auto-configures when credentials are provided
+   - **Automatic authentication** - App automatically authenticates with terminal (no manual login needed)
+   - Project path updates automatically when switching projects
+   - Starts in your project directory by default
+
+### Terminal Features
+
+- ✅ Full terminal emulation
+- ✅ Color support and ANSI escape sequences
+- ✅ Responsive design (works on mobile)
+- ✅ Multiple concurrent sessions
+- ✅ Automatic resize on orientation change
+- ✅ Custom theme matching app design
+- ✅ Scrollback history
+
+### Usage from Mobile App
+
+Once enabled on the backend:
+1. Open CCC mobile app
+2. Navigate to project settings
+3. Terminal tab will appear automatically
+4. Tap to open full-screen terminal
+5. Terminal opens directly in your project directory
+6. Use on-screen keyboard or external keyboard
+
+### Security Best Practices
+
+⚠️ **Important Security Notes:**
+
+1. **Use Strong Passwords:** Terminal gives full shell access
+   ```bash
+   # Generate a secure password
+   openssl rand -base64 32
+   ```
+
+2. **Combine with ngrok Authentication:** For remote access
+   ```bash
+   ccc --ngrok-token YOUR_TOKEN \
+       --terminal-username admin \
+       --terminal-password $(openssl rand -base64 32)
+   ```
+
+3. **Monitor Active Sessions:** Check logs for suspicious activity
+   ```bash
+   ccc --debug  # Enable detailed logging
+   ```
+
+4. **Restrict Network Access:** Only use on trusted networks or via ngrok
+
+### Troubleshooting Terminal
+
+**Terminal won't connect:**
+- Verify credentials are correct
+- Check logs with `--debug` flag
+- Ensure port 3001 is not in use
+
+**Authentication failures:**
+- Check for IP blocking (max 5 failed attempts)
+- Wait 15 minutes if blocked
+- Restart server to clear blocks
+
+**Terminal not showing in app:**
+- Ensure terminal credentials are set on backend
+- Restart the mobile app
+- Check app settings for terminal configuration
+
 ## Permission Modes
 
 CCC offers four permission modes to balance convenience and security:
@@ -182,11 +318,14 @@ CCC offers four permission modes to balance convenience and security:
 
 When you start CCC, it:
 
-1. **Starts MQTT Broker** - Embedded broker on port 8883 (WebSocket)
-2. **Sets Up Projects** - Auto-configures permission hooks
-3. **Manages Sessions** - Persistent sessions across disconnects
-4. **Streams Responses** - Real-time Claude responses to mobile
-5. **Handles Permissions** - Smart permission checks based on mode
+1. **Starts MQTT Broker** - Embedded broker on port 8883 (localhost)
+2. **Starts Path Router** - HTTP router on port 8080 proxying MQTT and terminal
+3. **Starts Terminal Server** (Optional) - Web terminal on port 3001 if credentials provided
+4. **Sets Up ngrok Tunnel** (Optional) - Public URL pointing to router
+5. **Sets Up Projects** - Auto-configures permission hooks
+6. **Manages Sessions** - Persistent sessions across disconnects
+7. **Streams Responses** - Real-time Claude responses to mobile
+8. **Handles Permissions** - Smart permission checks based on mode
 
 ### Project Structure
 
@@ -213,18 +352,27 @@ The CCC mobile app is required to interact with the backend.
   <a href="https://play.google.com/store/apps/details?id=com.naarang.ccc">
     <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/GetItOnGooglePlay_Badge_Web_color_English.png?alt=media&token=d2f34558-ce96-4882-9225-8ded76f759ba" alt="Get it on Google Play" height="80">
   </a>
+  <br/>
+  <a href="https://play.google.com/apps/testing/com.naarang.ccc">
+    <sub>Join Android Beta Testing</sub>
+  </a>
 </p>
 
 <p align="center">
   <a href="https://apps.apple.com/in/app/ccc-ui-for-coding-agents/id6753870766">
     <img src="https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg" alt="Download on the App Store" height="80">
   </a>
+  <br/>
+  <a href="https://testflight.apple.com/join/bEVNMrNH">
+    <sub>Join iOS Beta Testing (TestFlight)</sub>
+  </a>
 </p>
 
 ### Features
 - Multiple project management
 - Real-time chat interface
 - Permission request handling
+- Integrated web terminal (Beta) - when enabled on backend
 - Server profile management
 - Connection health monitoring
 - Theme support (light/dark)
@@ -263,7 +411,7 @@ ccc --port 9000
 **Checklist:**
 1. Check you're on the same WiFi network (for local)
 2. Verify server is running (`ccc` should show "started successfully")
-3. Check firewall settings allow port 8883
+3. Check firewall settings allow port 8080 (router) and 8883 (MQTT)
 4. Use correct format: `hostname:port` (no `http://`)
 5. Enable debug mode: `ccc --debug`
 
@@ -335,38 +483,4 @@ Make quick code changes without opening your laptop.
 Learn coding concepts by chatting with Claude from mobile.
 
 ### Pair Programming
-Collaborate with Claude on coding tasks remotely.
-
-## Comparison
-
-### vs Claude Web
-- ✅ Mobile access
-- ✅ Offline project access
-- ✅ Real-time streaming
-- ✅ Local file system access
-
-### vs Claude Desktop
-- ✅ Mobile control
-- ✅ Remote access
-- ✅ Multi-device support
-- ✅ Session persistence
-
-## Performance
-
-- **Startup Time**: ~2 seconds
-- **Response Latency**: <100ms (local network)
-- **Concurrent Sessions**: Unlimited
-- **Memory Usage**: ~150MB (varies with active sessions)
-
-## Support & Community
-
-- **Issues**: Report bugs and request features
-- **Discussions**: Ask questions and share ideas
-- **Updates**: Check npm for latest version
-- **Contact**: Email us at cccuiapp@gmail.com
-
-**Made with ❤️ by naarang**
-
-> **Note**: This tool requires an active Claude subscription and Claude Code to function properly.
-
-**Get Started:** `npm install -g @naarang/ccc && ccc`
+Co                                      @naarang/ccc && ccc`