@naarang/ccc 2.0.0-beta.7 → 2.0.0

package/README.md

@@ -1,6 +1,73 @@
-# CCC Backend v2 - Code Chat Connect
-
-A clean, modular backend for Code Chat Connect using Bun's native capabilities and modern service-oriented architecture.
+# CCC - UI Interface for Coding Agents like Claude Code
+
+**Control Claude Code and other coding agents from your mobile device**
+
+CCC is a powerful CLI tool that creates a bridge between [Claude Code](https://claude.com/product/claude-code) and your mobile device, allowing you to chat with Claude and execute code operations remotely through the CCC mobile app.
+
+[![npm version](https://img.shields.io/npm/v/@naarang/ccc.svg?style=flat-square)](https://www.npmjs.com/package/@naarang/ccc)
+
+![CCC Terminal Screenshot](https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/v2%2Fnpm_readme%2Fcarbon.png?alt=media&token=0ae87eba-4cfd-4d58-ab4a-b7330cbb62be)
+
+<p align="center">
+  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/v2%2Fnpm_readme%2FWhatsApp%20Image%202026-01-16%20at%2010.55.20%20PM%20(2).jpeg?alt=media&token=9f71a100-c9ed-4e4e-ae60-f04b86c2b3e7" width="150" style="margin-right: 8px;" />
+  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/v2%2Fnpm_readme%2FWhatsApp%20Image%202026-01-16%20at%2010.55.20%20PM%20(1).jpeg?alt=media&token=6fbb3693-17e1-439e-92f0-f634f79ad51f" width="150" style="margin-right: 8px;" />
+  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/v2%2Fnpm_readme%2FWhatsApp%20Image%202026-01-16%20at%2010.55.20%20PM.jpeg?alt=media&token=3c74c222-7ea5-4e2c-961a-66bcc476a6d7" width="150" style="margin-right: 8px;" />
+  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/v2%2Fnpm_readme%2FWhatsApp%20Image%202026-01-16%20at%2010.55.19%20PM%20(1).jpeg?alt=media&token=e4faec8b-4ad4-400e-9af8-2d0187157f97" width="150" style="margin-right: 8px;" />
+  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/v2%2Fnpm_readme%2FWhatsApp%20Image%202026-01-16%20at%2010.55.19%20PM.jpeg?alt=media&token=b87ce7ad-dc6e-42d4-a6ac-2d1787f206bd" width="150" style="margin-right: 8px;" />
+</p>
+</p>
+
+<p align="center">
+  <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>
+
+<p align="center">
+  <a href="https://discord.gg/9EjE8t4YCF">
+    <img src="https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://getc3.app">
+    <img src="https://img.shields.io/badge/Website-getc3.app-green?style=for-the-badge" alt="Visit Website">
+  </a>
+  &nbsp;
+  <a href="https://getc3.app/docs">
+    <img src="https://img.shields.io/badge/Docs-Documentation-blue?style=for-the-badge" alt="Documentation">
+  </a>
+</p>
+
+## Features
+
+- **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** - Full terminal access with auto-generated secure credentials
+- **Checkpoints & Rewind** - Rewind Claude's changes to any checkpoint
+- **Git Integration** - View diffs, commit, push, and create PRs from mobile
+- **File Explorer & Editor** - Browse and edit project files with syntax highlighting
+- **Session Resume** - Resume sessions and seamlessly switch between devices
+- **Context Window Monitor** - Track token usage and context breakdown
+- **Model Switcher** - Switch between Claude models during conversations
+- **Push Notifications** - Get notified when Claude needs attention
+- **Remote Access** - Optional ngrok integration for access from anywhere
+- **Auto-Update System** - Automatic version checks and updates
 
 ## Requirements
 
@@ -15,11 +82,11 @@ powershell -c "irm bun.sh/install.ps1|iex"
 curl -fsSL https://bun.sh/install | bash
 ```
 
-Learn more: https://bun.sh
+Learn more at [bun.sh](https://bun.sh)
 
 ## Installation
 
-### Global Install (Recommended)
+### Option 1: npm Install (Recommended)
 
 ```bash
 npm install -g @naarang/ccc
@@ -30,107 +97,166 @@ Then run:
 ccc
 ```
 
-### Local Development
+### Option 2: Standalone Binary (Beta)
+
+For users who prefer not to install npm/Bun, standalone binaries are available:
 
+**macOS / Linux:**
 ```bash
-bun install
-bun src/index.ts
+curl -fsSL https://getc3.app/install.sh | bash
 ```
 
-## Usage
+**Windows (PowerShell as Administrator):**
+```powershell
+irm https://getc3.app/install.ps1 | iex
+```
+
+The binary will be installed to `~/.ccc/bin` and added to your PATH.
+
+## Quick Start
+
+### 1. Start the Backend Server
 
 ```bash
-# Start with default settings
 ccc
+```
 
-# Enable debug logging
-ccc --debug
+The server will start and display a QR code for easy mobile setup.
 
-# With custom ports
-ccc --mqtt-port 8884 --router-port 8883 --terminal-port 3001
+### 2. Configure the Mobile App
 
-# With MQTT authentication (required for ngrok)
-ccc --username myuser --password mypass
+Download the CCC mobile app and scan the QR code, or manually add the server:
+
+**For Local Network:**
+```
+Server URL: 192.168.x.xxx:8883
+```
 
-# With ngrok tunnel for remote access
-ccc --username myuser --password mypass --ngrok-token YOUR_TOKEN
+**For Remote Access:**
+```bash
+ccc --ngrok-token YOUR_TOKEN --username admin --password yourpassword
 ```
 
+### 3. Start Chatting
+
+Open the app, create a project pointing to your local directory, and start chatting with Claude!
+
 ## CLI Options
 
+```bash
+ccc [options]
+
+Options:
+  -d, --debug                Enable debug logging
+  --mqtt-port <port>         Internal broker port (default: 8884)
+  --router-port <port>       Main server port - app connects here (default: 8883)
+  --terminal-port <port>     Terminal server port (default: 3001)
+  -u, --username <user>      Authentication username (required for ngrok)
+  -p, --password <pass>      Authentication password (required for ngrok)
+  -t, --ngrok-token <token>  ngrok auth token for remote access
+  --ngrok-domain <domain>    ngrok static domain (paid plan)
+  --no-auto-update           Disable automatic updates
+  -v, --version              Show version number
+  -h, --help                 Show help message
 ```
--d, --debug                          Enable debug logging
---mqtt-port <port>                   MQTT broker port (default: 8884)
---terminal-port <port>               Terminal server port (default: 3001)
---router-port <port>                 Router port (default: 8883)
---username <username>                MQTT broker username (optional)
---password <password>                MQTT broker password (optional)
---ngrok-token <token>                ngrok auth token for remote access
---ngrok-domain <domain>              ngrok static domain (paid plan)
---no-auto-update                     Disable automatic updates
--h, --help                           Show help message
+
+### Examples
+
+```bash
+# Basic usage (local network)
+ccc
+
+# With authentication
+ccc -u admin -p secret
+
+# With ngrok for remote access
+ccc --ngrok-token YOUR_TOKEN -u admin -p secret
+
+# Debug mode with custom ports
+ccc --debug --router-port 9000
 ```
 
-## Services
+## Permission Modes
+
+CCC offers four permission modes to balance convenience and security:
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| **Default** | Prompts for approval on first use | Balanced security |
+| **Accept Edits** | Auto-approves file modifications | Active development |
+| **Plan Mode** | Analysis only, no code changes | Code review |
+| **Bypass All** | Skips all prompts (use with caution!) | Controlled environments |
 
-The backend provides these core services:
+## Terminal Access
 
-1. **MQTT Broker** - Real-time communication with mobile apps (port 8884)
-2. **Terminal Server** - Secure PTY-based terminal access (port 3001)
-3. **Router** - Path-based reverse proxy for unified access (port 8883)
-4. **Claude Agent** - Manages Claude Code CLI sessions
-5. **File Browser** - Remote file system access
-6. **Git Service** - Git operations and GitHub integration
-7. **Notifications** - Push notifications via Expo
+CCC includes a built-in terminal accessible from the mobile app:
+
+- Full terminal emulation with color support
+- Auto-generated secure credentials
+- Project-aware (opens in your project directory)
+- Multiple concurrent sessions (max 5)
+- Automatic resize on orientation change
 
 ## Security
 
 - Terminal credentials are auto-generated and never logged
-- MQTT authentication is optional but required for ngrok tunnels
-- MQTT/Terminal services bind to localhost only
-- Router is the only public-facing service
+- Authentication required for remote access (ngrok)
+- All internal services bind to localhost only
+- Rate limiting on failed authentication attempts
 
-## Architecture
+## System Requirements
 
-```
-src/
-├── index.ts                    # Main entry point
-├── cli/                        # CLI argument parsing
-├── services/                   # Service implementations
-│   ├── mqtt-broker/            # MQTT broker
-│   ├── terminal-server/        # Terminal server
-│   ├── router/                 # HTTP/WS proxy
-│   ├── claude-agent/           # Claude Code CLI management
-│   ├── file-browser/           # File system access
-│   ├── git-service/            # Git operations
-│   ├── notification/           # Push notifications
-│   └── ...                     # Other services
-├── core/                       # Service orchestration
-└── utils/                      # Shared utilities
-```
+- **Bun**: v1.0.0 or higher
+- **Claude Code**: Latest version ([Download](https://claude.com/product/claude-code))
+- **Claude Subscription**: Active Pro / Max account or API KEY
+- **Operating Systems**: Linux, macOS, Windows
 
-## Development
+## Troubleshooting
 
-```bash
-# Run in development mode
-bun src/index.ts --debug
+### Server Won't Start
 
-# Type checking
-bun run type-check
+```bash
+# Check if ports are in use
+lsof -i :8883
+lsof -i :8884
 
-# Build for distribution
-bun run build
+# Use different ports
+ccc --router-port 9000 --mqtt-port 9001
 ```
 
-## Why Bun?
+### Connection Issues
+
+1. Ensure you're on the same WiFi network (for local connections)
+2. Check firewall allows port 8883
+3. Use correct format: `hostname:8883` (no `http://`)
+4. Enable debug mode: `ccc --debug`
+
+### Claude Not Responding
+
+1. Verify Claude Code is installed: `claude --version`
+2. Check authentication: `claude auth status`
+3. Verify project path exists and is accessible
+
+## Support & Community
+
+- **Documentation**: [getc3.app/docs](https://getc3.app/docs)
+- **Discord**: [Join our community](https://discord.gg/9EjE8t4YCF)
+- **Email**: cccuiapp@gmail.com
+
+## Support the Project
+
+If you find CCC useful, consider supporting its development:
+
+<p align="center">
+  <a href="https://getc3.app/support">
+    <img src="https://img.shields.io/badge/Support-CCC-blue?style=for-the-badge" alt="Support CCC">
+  </a>
+</p>
 
-This project uses Bun because:
-- Native TypeScript support without transpilation
-- Faster startup and runtime performance
-- Built-in WebSocket server (`Bun.serve()`)
-- `bun-pty` for reliable PTY handling (node-pty has compatibility issues)
-- Simpler dependency management
+---
 
-## License
+**Made with ❤️ by naarang**
 
-UNLICENSED - Private package
+> **Note**: This tool requires an active Claude subscription and Claude Code to function properly. This project is not affiliated with, endorsed by, or sponsored in any form by Anthropic, Claude or Claude Code.
+            Claude & Claude Code are/may be a trademark and product of Anthropic, PBC.
+            This is an independent project built to use Claude Code in a convenient way.