From 5a497d61ae658b8fa0a2cd6979ce8722951e2252 Mon Sep 17 00:00:00 2001 From: snehasishcodes Date: Wed, 19 Aug 2026 12:42:36 +0530 Subject: [PATCH] docs: simplify README to quick-start and move docs to docs/ --- README.md | 138 ++++++-------------------------------------- docs/README.md | 8 +++ docs/development.md | 74 ++++++++++++++++++++++++ docs/features.md | 28 +++++++++ 4 files changed, 127 insertions(+), 121 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/development.md create mode 100644 docs/features.md diff --git a/README.md b/README.md index f091221..49e719d 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,46 @@ # CrossCode -CrossCode is a free, open-source mobile client for [OpenCode](https://opencode.ai) - the terminal AI coding agent. It lets you control your PC's OpenCode instance from your phone, anywhere in the world, with no shared network required. +Control your PC's [OpenCode](https://opencode.ai) — the terminal AI coding agent — from your phone, from anywhere in the world. Free, open source, and private: your code never touches CrossCode's servers, because there are none. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![npm](https://img.shields.io/npm/v/crosscode)](https://www.npmjs.com/package/crosscode) [![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org) -## What is CrossCode? - -CrossCode connects your phone to a running `opencode serve` instance on your PC or VPS through a Cloudflare Tunnel. Your code never touches CrossCode's servers - there are none. Everything runs locally on your machine. - -- **Zero config**: `npx crosscode` starts everything and shows a QR code -- **Scan to connect**: open the app, scan the QR, you're in -- **Works anywhere**: mobile data, different WiFi, across the world -- **Full control**: chat, approve tool calls, review diffs, manage sessions - -## Features - -### Companion CLI (`npx crosscode`) - -Run this on your PC (current working directory) to bootstrap the entire connection: - -- Starts `opencode serve` automatically -- Opens a Cloudflare Tunnel (no account needed) -- Renders a QR code in your terminal -- Scan from the CrossCode app → connected instantly -- Graceful shutdown on `Ctrl+C` -- Auto-detects missing dependencies and guides installation - -### Mobile App - -- **QR Connect**: scan and connect in one tap, no copy-pasting URLs -- **Real-time Chat**: prompts from your phone, responses streamed back live with full markdown and code block rendering -- **Inline Diffs**: see exactly what the agent changed before it happens, with expandable side-by-side view -- **Tool Call Approvals**: approve or reject every shell command, file write, or API call before it runs on your PC -- **Session Management**: browse, switch, and create sessions; run multiple sessions simultaneously -- **File Tree Browser**: navigate your project with syntax highlighting and line numbers -- **Push Notifications**: get notified when the agent finishes, needs approval, or hits an error - ## Quick Start -### 1. Install prerequisites +### 1. On your PC -Make sure you have [OpenCode](https://opencode.ai) and [Cloudflare tunnel](https://developers.cloudflare.com/tunnel) installed on your PC: - -```bash -# Install opencode and cloudflared (if not already installed) -# See https://opencode.ai and https://developers.cloudflare.com/tunnel for installation instructions -``` - -### 2. Start the companion CLI +Open a terminal in your project directory and run: ```bash npx crosscode ``` -This will: -1. Start `opencode serve` on your PC -2. Open a Cloudflare Tunnel -3. Display a QR code in your terminal +This starts `opencode serve`, opens a tunnel, and prints a QR code in your terminal. (Make sure [OpenCode](https://opencode.ai) is installed first.) -### 3. Connect from your phone +### 2. On your phone -1. Install the CrossCode app (iOS / Android) +1. Install the CrossCode app — [Android](https://crosscode.site/download) (iOS coming soon) 2. Open the app and scan the QR code -3. You're connected: start chatting with your AI agent - -## Monorepo Structure - -``` -crosscode/ -├── apps/ -│ ├── mobile/ # React Native + Expo (iOS + Android) -│ └── web/ # Website -├── packages/ -│ ├── crosscode/ # Companion CLI: `npx crosscode` -│ └── shared/ # Shared types, constants, QR payload schema -└── README.md -``` - -## Development +3. Start chatting with your agent -### Prerequisites - -- [Node.js](https://nodejs.org) >= 20 -- [pnpm](https://pnpm.io) >= 9 - -### Setup - -```bash -# Clone the repo -git clone https://github.com/snhsish/crosscode.git -cd crosscode - -# Install dependencies -pnpm install - -# Start all apps in development mode -pnpm dev - -# Build everything -pnpm build - -# Run linter -pnpm lint -``` - -### Developing the CLI - -```bash -cd packages/crosscode -pnpm dev # Watch mode -pnpm build # Build for production -``` - -### Developing the Mobile App - -```bash -cd apps/mobile -pnpm start # Start Expo dev server -pnpm android # Run on Android -pnpm ios # Run on iOS -``` +That's it. No account, no configuration, no shared network. -## What CrossCode is NOT +## How It Works -- **Not a standalone agent** — it requires a running `opencode serve` on a PC or VPS -- **Not a cloud service** — your code never touches CrossCode's servers (there are none) -- **Not paid** — free and open source, MIT licensed, forever +Your phone connects to the OpenCode instance running on your machine through a secure tunnel, and streams everything back in real time — prompts, streaming responses, tool-call approvals, and file diffs. -## Tech Stack +## Documentation -| Layer | Choice | -|---|---| -| Mobile | React Native + Expo | -| Navigation | Expo Router | -| State | Zustand | -| Styling | NativeWind (Tailwind) | -| Companion CLI | Node.js | -| Tunnel | Cloudflare Tunnel | -| Monorepo | pnpm workspaces + Turborepo | +- [CLI Reference](docs/cli.md) — all commands, flags, and configuration +- [Development](docs/development.md) — set up and build the project locally +- [Features](docs/features.md) — what CrossCode can do +- [Tunnel Server](docs/tunnel-server/README.md) — self-hosted relay for paid users ## Contributing -Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started. +Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). ## License -CrossCode is licensed under the [MIT License](LICENSE). +MIT — see [LICENSE](LICENSE). \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dd7ca47 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# CrossCode Documentation + +- **[CLI Reference](cli.md)** — all commands, flags, tunnel options, config, and environment variables +- **[Development](development.md)** — set up and build the monorepo locally +- **[Features](features.md)** — what CrossCode can do +- **[Tunnel Server](tunnel-server/README.md)** — self-hosted WebSocket relay for paid users + +See the [README](../README.md) for a quick-start guide. \ No newline at end of file diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..c80d57f --- /dev/null +++ b/docs/development.md @@ -0,0 +1,74 @@ +# Development + +Set up and build the CrossCode monorepo locally. + +## Prerequisites + +- [Node.js](https://nodejs.org) >= 20 +- [pnpm](https://pnpm.io) >= 9 + +## Setup + +```bash +# Clone the repo +git clone https://github.com/snhsish/crosscode.git +cd crosscode + +# Install dependencies +pnpm install + +# Start all apps in development mode +pnpm dev + +# Build everything +pnpm build + +# Run linter +pnpm lint +``` + +## Monorepo Structure + +``` +crosscode/ +├── apps/ +│ ├── mobile/ # React Native + Expo (iOS + Android) +│ └── web/ # Website +├── packages/ +│ ├── crosscode/ # Companion CLI: `npx crosscode` +│ └── shared/ # Shared types, constants, QR payload schema +└── README.md +``` + +## Developing the CLI + +```bash +cd packages/crosscode +pnpm dev # Watch mode +pnpm build # Build for production +``` + +## Developing the Mobile App + +```bash +cd apps/mobile +pnpm start # Start Expo dev server +pnpm android # Run on Android +pnpm ios # Run on iOS +``` + +## Tech Stack + +| Layer | Choice | +|---|---| +| Mobile | React Native + Expo | +| Navigation | Expo Router | +| State | Zustand | +| Styling | NativeWind (Tailwind) | +| Companion CLI | Node.js | +| Tunnel | Cloudflare Tunnel | +| Monorepo | pnpm workspaces + Turborepo | + +## Contributing + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for branch naming, commit conventions, and the PR workflow. \ No newline at end of file diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..1ac2ddd --- /dev/null +++ b/docs/features.md @@ -0,0 +1,28 @@ +# Features + +## Companion CLI (`npx crosscode`) + +Run this on your PC (current working directory) to bootstrap the entire connection: + +- Starts `opencode serve` automatically +- Opens a Cloudflare Tunnel (no account needed) +- Renders a QR code in your terminal +- Scan from the CrossCode app → connected instantly +- Graceful shutdown on `Ctrl+C` +- Auto-detects missing dependencies and guides installation + +## Mobile App + +- **QR Connect**: scan and connect in one tap, no copy-pasting URLs +- **Real-time Chat**: prompts from your phone, responses streamed back live with full markdown and code block rendering +- **Inline Diffs**: see exactly what the agent changed before it happens, with expandable side-by-side view +- **Tool Call Approvals**: approve or reject every shell command, file write, or API call before it runs on your PC +- **Session Management**: browse, switch, and create sessions; run multiple sessions simultaneously +- **File Tree Browser**: navigate your project with syntax highlighting and line numbers +- **Push Notifications**: get notified when the agent finishes, needs approval, or hits an error + +## What CrossCode is NOT + +- **Not a standalone agent** — it requires a running `opencode serve` on a PC or VPS +- **Not a cloud service** — your code never touches CrossCode's servers (there are none) +- **Not paid** — free and open source, MIT licensed, forever \ No newline at end of file