remote-claude-code 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+[中文](./README.zh-CN.md) | **English**
+
+<p align="center">
+  <img src="./public/images/logo.png" alt="Remote Claude Code" width="80%" />
+</p>
+
+# Remote Claude Code
+
+Self-hosted tool to remotely control your local [Claude Code](https://docs.anthropic.com/en/docs/claude-code) from your phone — via Cloudflare Tunnel + PWA.
+
+## Features
+
+- **Remote Access** — Instantly expose your local Claude Code via Cloudflare Quick Tunnel, no configuration needed
+- **PWA** — Install as a native-feeling app on your phone with offline support
+- **Real-time Streaming** — WebSocket-based full-duplex communication with live text, thinking blocks, and tool call visualization
+- **Multi-thread** — Create, switch, and resume multiple chat sessions, powered by Claude Agent SDK's session management
+- **Tool Call Visualization** — See file edits, bash commands, and other tool uses as they happen
+- **Thinking Blocks** — View Claude's reasoning process in real time
+- **Light/Dark Theme** — Automatic or manual theme switching with Claude/Anthropic brand colors
+- **Password Auth** — Secure access with bcrypt-hashed password + JWT tokens
+- **File Attachments** — Upload files to provide context for your conversations
+- **Project Switching** — Switch between different local project directories
+- **Model Selection** — Choose from available Claude models
+- **MCP Integration** — Works with configured MCP servers
+- **Built-in Terminal** — Interactive terminal panel supports Windows (Bun pipe mode) and POSIX PTY
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | [Bun](https://bun.sh) |
+| Backend | [Hono](https://hono.dev) |
+| Frontend | React 19 + Vite |
+| Styling | Tailwind CSS v4 + shadcn/ui |
+| AI | [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
+| Tunnel | [cloudflared](https://www.npmjs.com/package/cloudflared) |
+| Database | Bun built-in SQLite (WAL mode) |
+| Auth | Bun.password (bcrypt) + Hono JWT |
+| PWA | vite-plugin-pwa |
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) v1.0+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) configured on your machine
+
+### Install
+
+```bash
+# Using npm
+npm install -g remote-claude-code
+
+# Or using bun
+bun add -g remote-claude-code
+```
+
+### Run
+
+```bash
+rcc start
+```
+
+That's it. The server starts on `http://localhost:3456` and automatically creates a Cloudflare Tunnel.
+All available access URLs are printed in the terminal — open any of them on your phone.
+
+On first visit, you'll be prompted to set a password.
+
+## CLI Reference
+
+```
+rcc start                        Start server in background
+      --port <n>                   Listen on port n (default: 3456)
+      --no-tunnel                  Disable Cloudflare Tunnel
+      --no-tailscale               Disable Tailscale detection
+rcc stop                         Stop the server
+rcc status                       Show PID, uptime, and access URLs
+rcc logs                         Print recent server logs
+      -f, --follow                 Stream new log lines (like tail -f)
+      --lines <n>                  Number of lines to show (default: 50)
+rcc setup                        Rebuild frontend (only needed after source updates)
+```
+
+## Development
+
+### Clone & run from source
+
+```bash
+git clone https://github.com/anthropics/remote-claude-code.git
+cd remote-claude-code
+bun install
+bun link       # register `rcc` globally from this directory
+rcc setup      # build frontend (first time only)
+rcc start
+```
+
+### Dev server
+
+```bash
+bun run dev          # server (watch) + Vite dev server concurrently
+bun run dev:server   # server only
+bun run dev:client   # Vite dev server only
+bun run build        # build frontend
+```
+
+### Windows Terminal Troubleshooting
+
+- On Windows, terminal sessions run in pipe mode (`stdin/stdout`) because Bun PTY is POSIX-only.
+- If "Create Terminal" fails, verify your configured shell exists, then restart the server.
+- Default Windows shell probe order: `pwsh.exe` → `powershell.exe` → `cmd.exe`.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | `3456` |
+| `RCC_JWT_SECRET` | JWT signing key | Auto-generated and persisted in DB |
+| `NO_TUNNEL` | Set to `1` to disable Cloudflare Tunnel | — |
+| `NO_TAILSCALE` | Set to `1` to disable Tailscale detection | — |
+
+## Architecture
+
+```
+cli/
+├── index.ts              # CLI entry point (rcc command)
+├── constants.ts          # Shared constants (APP_NAME)
+├── commands/
+│   ├── start.ts          # rcc start — spawn background server process
+│   ├── stop.ts           # rcc stop  — kill server by PID
+│   ├── status.ts         # rcc status
+│   ├── logs.ts           # rcc logs
+│   └── setup.ts          # rcc setup
+└── utils/
+    ├── process-manager.ts # PID-file-based cross-platform process management
+    └── server.ts          # Health check & network info helpers
+
+server/
+├── index.ts       # HTTP entry, routes, static files
+├── ws.ts          # WebSocket handler & message routing
+├── claude.ts      # ClaudeSessionManager (wraps SDK query())
+├── auth.ts        # Password setup/login (bcrypt + JWT)
+├── db.ts          # SQLite DataStore (~/.remote-claude-code/data.db)
+├── threads.ts     # Thread listing/history API
+├── tunnel.ts      # Cloudflare Quick Tunnel
+├── tailscale.ts   # Tailscale IP detection
+├── upload.ts      # File upload routes
+└── projects.ts    # Project management routes
+
+src/
+├── App.tsx
+├── pages/
+│   ├── Chat.tsx           # Main chat UI
+│   └── Login.tsx          # Auth page
+├── components/
+│   ├── MessageList.tsx
+│   ├── MessageBubble.tsx
+│   ├── InputBar.tsx       # Chat input + attachments
+│   ├── ThreadSidebar.tsx
+│   ├── ToolCallCard.tsx
+│   ├── ThinkingBlock.tsx
+│   ├── MarkdownRenderer.tsx
+│   └── ui/                # shadcn/ui components
+├── hooks/
+│   ├── useAuth.ts
+│   ├── useWebSocket.ts
+│   ├── useMessages.ts
+│   ├── useThreads.ts
+│   └── useTheme.ts
+├── types/messages.ts
+└── styles/globals.css
+```
+
+## WebSocket Protocol
+
+**Client → Server:** `auth`, `chat`, `interrupt`, `abort`, `ping`
+
+**Server → Client:** `status`, `auth_result`, `chat_started`, `stream_delta`, `thinking_delta`, `thinking_start`, `thinking_end`, `tool_start`, `tool_input_delta`, `block_stop`, `assistant_message`, `system_init`, `result`, `chat_complete`, `error`
+
+## Data Storage
+
+All persistent data lives in `~/.remote-claude-code/`:
+
+| Path | Contents |
+|------|----------|
+| `data.db` | SQLite database — config, sessions, messages |
+| `rcc-process.json` | Running server PID and metadata |
+| `logs/rcc-out.log` | Server output log (viewed with `rcc logs`) |
+
+Chat sessions are managed by Claude Agent SDK in `~/.claude/projects/`.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,193 @@
+**中文** | [English](./README.md)
+
+<p align="center">
+  <img src="./public/images/logo.png" alt="Remote Claude Code" width="80%" />
+</p>
+
+# Remote Claude Code
+
+自托管工具，通过 Cloudflare Tunnel + PWA 从手机远程操控本机 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)。
+
+## 功能特性
+
+- **远程访问** — 通过 Cloudflare Quick Tunnel 即时暴露本地 Claude Code，无需额外配置
+- **PWA** — 可安装为手机原生应用体验，支持离线访问
+- **实时流式输出** — 基于 WebSocket 的全双工通信，实时展示文本、思考过程和工具调用
+- **多会话** — 创建、切换和恢复多个聊天会话，基于 Claude Agent SDK 的会话管理
+- **工具调用可视化** — 实时查看文件编辑、Bash 命令等工具调用过程
+- **思考过程** — 实时查看 Claude 的推理过程
+- **亮/暗主题** — 自动或手动切换主题，采用 Claude/Anthropic 品牌配色
+- **密码认证** — bcrypt 哈希密码 + JWT 令牌的安全访问
+- **文件附件** — 上传文件为对话提供上下文
+- **项目切换** — 在不同本地项目目录间切换
+- **模型选择** — 选择可用的 Claude 模型
+- **MCP 集成** — 支持已配置的 MCP 服务器
+- **内置终端** — 交互式终端面板，支持 Windows（管道模式）和 POSIX PTY
+
+## 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 运行时 | [Bun](https://bun.sh) |
+| 后端 | [Hono](https://hono.dev) |
+| 前端 | React 19 + Vite |
+| 样式 | Tailwind CSS v4 + shadcn/ui |
+| AI | [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
+| 隧道 | [cloudflared](https://www.npmjs.com/package/cloudflared) |
+| 数据库 | Bun 内置 SQLite (WAL 模式) |
+| 认证 | Bun.password (bcrypt) + Hono JWT |
+| PWA | vite-plugin-pwa |
+
+## 快速开始
+
+### 前置要求
+
+- [Bun](https://bun.sh) v1.0+
+- 本机已配置 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+### 安装
+
+```bash
+# 使用 npm
+npm install -g remote-claude-code
+
+# 或使用 bun
+bun add -g remote-claude-code
+```
+
+### 启动
+
+```bash
+rcc start
+```
+
+就这些。服务启动在 `http://localhost:3456`，并自动创建 Cloudflare Tunnel。
+终端会打印所有可用访问地址，在手机上打开任意一个即可开始使用。
+
+首次访问时会提示设置密码。
+
+## CLI 命令参考
+
+```
+rcc start                        在后台启动服务
+      --port <n>                   监听指定端口（默认：3456）
+      --no-tunnel                  禁用 Cloudflare Tunnel
+      --no-tailscale               禁用 Tailscale 检测
+rcc stop                         停止服务
+rcc status                       查看 PID、运行时长和访问地址
+rcc logs                         查看服务日志
+      -f, --follow                 实时跟踪新日志（类似 tail -f）
+      --lines <n>                  显示最后 N 行（默认：50）
+rcc setup                        重新构建前端（仅在更新源码后需要）
+```
+
+## 开发
+
+### 从源码克隆并运行
+
+```bash
+git clone https://github.com/anthropics/remote-claude-code.git
+cd remote-claude-code
+bun install
+bun link       # 从当前目录全局注册 rcc 命令
+rcc setup      # 构建前端（仅首次）
+rcc start
+```
+
+### 开发服务器
+
+```bash
+bun run dev          # 服务器（监听变更）+ Vite 开发服务器 同时启动
+bun run dev:server   # 仅服务器
+bun run dev:client   # 仅 Vite 开发服务器
+bun run build        # 构建前端
+```
+
+### Windows 终端排查
+
+- Windows 下终端会话使用管道模式（`stdin/stdout`），因为 Bun PTY 仅支持 POSIX。
+- 若「创建终端」失败，请确认配置的 Shell 存在且可执行，然后重启服务。
+- Windows 默认 Shell 探测顺序：`pwsh.exe` → `powershell.exe` → `cmd.exe`。
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `PORT` | 服务器端口 | `3456` |
+| `RCC_JWT_SECRET` | JWT 签名密钥 | 自动生成并持久化到数据库 |
+| `NO_TUNNEL` | 设为 `1` 禁用 Cloudflare Tunnel | — |
+| `NO_TAILSCALE` | 设为 `1` 禁用 Tailscale 检测 | — |
+
+## 架构
+
+```
+cli/
+├── index.ts              # CLI 入口（rcc 命令）
+├── constants.ts          # 共享常量（APP_NAME）
+├── commands/
+│   ├── start.ts          # rcc start — 后台启动服务进程
+│   ├── stop.ts           # rcc stop  — 通过 PID 终止服务
+│   ├── status.ts         # rcc status
+│   ├── logs.ts           # rcc logs
+│   └── setup.ts          # rcc setup
+└── utils/
+    ├── process-manager.ts # 基于 PID 文件的跨平台进程管理
+    └── server.ts          # 健康检查 & 网络信息工具
+
+server/
+├── index.ts       # HTTP 入口，路由挂载，静态文件服务
+├── ws.ts          # WebSocket 处理器 & 消息路由
+├── claude.ts      # ClaudeSessionManager（封装 SDK query()）
+├── auth.ts        # 密码设置/登录（bcrypt + JWT）
+├── db.ts          # SQLite 数据存储（~/.remote-claude-code/data.db）
+├── threads.ts     # 会话列表/历史 API
+├── tunnel.ts      # Cloudflare Quick Tunnel
+├── tailscale.ts   # Tailscale IP 检测
+├── upload.ts      # 文件上传路由
+└── projects.ts    # 项目管理路由
+
+src/
+├── App.tsx
+├── pages/
+│   ├── Chat.tsx           # 聊天主界面
+│   └── Login.tsx          # 认证页面
+├── components/
+│   ├── MessageList.tsx
+│   ├── MessageBubble.tsx
+│   ├── InputBar.tsx       # 聊天输入框 + 附件
+│   ├── ThreadSidebar.tsx
+│   ├── ToolCallCard.tsx
+│   ├── ThinkingBlock.tsx
+│   ├── MarkdownRenderer.tsx
+│   └── ui/                # shadcn/ui 组件
+├── hooks/
+│   ├── useAuth.ts
+│   ├── useWebSocket.ts
+│   ├── useMessages.ts
+│   ├── useThreads.ts
+│   └── useTheme.ts
+├── types/messages.ts
+└── styles/globals.css
+```
+
+## WebSocket 协议
+
+**客户端 → 服务器：** `auth`、`chat`、`interrupt`、`abort`、`ping`
+
+**服务器 → 客户端：** `status`、`auth_result`、`chat_started`、`stream_delta`、`thinking_delta`、`thinking_start`、`thinking_end`、`tool_start`、`tool_input_delta`、`block_stop`、`assistant_message`、`system_init`、`result`、`chat_complete`、`error`
+
+## 数据存储
+
+所有持久化数据存储在 `~/.remote-claude-code/`：
+
+| 路径 | 内容 |
+|------|------|
+| `data.db` | SQLite 数据库——配置、会话、消息 |
+| `rcc-process.json` | 运行中的服务 PID 及元数据 |
+| `logs/rcc-out.log` | 服务输出日志（通过 `rcc logs` 查看）|
+
+聊天会话由 Claude Agent SDK 管理，位于 `~/.claude/projects/`。
+
+## 许可证
+
+MIT

package/cli/commands/logs.ts

@@ -0,0 +1,68 @@
+import { defineCommand } from 'citty'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { readProcessInfo } from '../utils/process-manager'
+
+async function tailFile(filePath: string, lines: number, follow: boolean) {
+  if (!existsSync(filePath)) {
+    console.log('[rcc] 日志文件不存在，服务可能尚未输出任何日志')
+    return
+  }
+
+  const content = readFileSync(filePath, 'utf-8')
+  const allLines = content.split('\n')
+  const tail = allLines.slice(-lines).join('\n')
+  process.stdout.write(tail + '\n')
+
+  if (!follow) return
+
+  let offset = Buffer.byteLength(content, 'utf-8')
+
+  const { watch } = await import('node:fs')
+  watch(filePath, () => {
+    try {
+      const buf = readFileSync(filePath)
+      if (buf.byteLength < offset) {
+        // 日志被轮转，文件从头开始
+        offset = 0
+      }
+      if (buf.byteLength > offset) {
+        process.stdout.write(buf.slice(offset).toString('utf-8'))
+        offset = buf.byteLength
+      }
+    } catch {
+      // ignore read errors (e.g. file temporarily unavailable)
+    }
+  })
+
+  // 保持进程运行直到用户 Ctrl+C
+  await new Promise<never>(() => {})
+}
+
+export default defineCommand({
+  meta: { name: 'logs', description: '查看 Remote Claude Code 服务日志' },
+  args: {
+    lines: {
+      type: 'string',
+      description: '显示最后 N 行',
+      default: '50',
+    },
+    follow: {
+      type: 'boolean',
+      description: '实时跟踪日志（类似 tail -f）',
+      default: false,
+      alias: 'f',
+    },
+  },
+  async run({ args }) {
+    const lines = parseInt(args.lines as string, 10)
+    const follow = args.follow as boolean
+
+    const info = readProcessInfo()
+    const logFile = info?.logFile ?? join(homedir(), '.remote-claude-code', 'logs', 'rcc-out.log')
+
+    await tailFile(logFile, lines, follow)
+  },
+})

package/cli/commands/setup.ts

@@ -0,0 +1,43 @@
+import { defineCommand } from 'citty'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+
+export default defineCommand({
+  meta: { name: 'setup', description: '初始化 Remote Claude Code（安装依赖 + 构建前端）' },
+  async run() {
+    const root = join(import.meta.dir, '../../')
+    const distIndex = join(root, 'dist/client/index.html')
+
+    if (existsSync(distIndex)) {
+      console.log('[rcc] 前端已构建，跳过构建步骤')
+    } else {
+      console.log('[rcc] 安装依赖...')
+      const installResult = Bun.spawnSync(['bun', 'install'], {
+        cwd: root,
+        stdout: 'inherit',
+        stderr: 'inherit',
+        stdin: 'inherit',
+      })
+      if (installResult.exitCode !== 0) {
+        console.error('[rcc] bun install 失败')
+        process.exit(1)
+      }
+
+      console.log('[rcc] 构建前端...')
+      const buildResult = Bun.spawnSync(['bun', 'run', 'build'], {
+        cwd: root,
+        stdout: 'inherit',
+        stderr: 'inherit',
+        stdin: 'inherit',
+      })
+      if (buildResult.exitCode !== 0) {
+        console.error('[rcc] 前端构建失败')
+        process.exit(1)
+      }
+
+      console.log('[rcc] 构建完成')
+    }
+
+    console.log('\n运行 "rcc start" 启动服务')
+  },
+})

package/cli/commands/start.ts

@@ -0,0 +1,68 @@
+import { defineCommand } from 'citty'
+import { join } from 'node:path'
+import { readProcessInfo, startProcess } from '../utils/process-manager'
+import { waitForReady, fetchNetworkInfo } from '../utils/server'
+
+export default defineCommand({
+  meta: { name: 'start', description: '启动 Remote Claude Code 服务' },
+  args: {
+    port: {
+      type: 'string',
+      description: '监听端口',
+      default: '3456',
+    },
+    'no-tunnel': {
+      type: 'boolean',
+      description: '禁用 Cloudflare Tunnel',
+      default: false,
+    },
+    'no-tailscale': {
+      type: 'boolean',
+      description: '禁用 Tailscale 检测',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const port = parseInt(args.port as string, 10)
+    const noTunnel = args['no-tunnel'] as boolean
+    const noTailscale = args['no-tailscale'] as boolean
+
+    const existing = readProcessInfo()
+    if (existing) {
+      console.log(`[rcc] 服务已在运行 (PID: ${existing.pid})`)
+      console.log('[rcc] 使用 "rcc status" 查看详情，使用 "rcc stop" 停止服务')
+      return
+    }
+
+    const serverPath = join(import.meta.dir, '../../server/index.ts')
+
+    const env: Record<string, string> = { PORT: String(port) }
+    if (noTunnel) env.NO_TUNNEL = '1'
+    if (noTailscale) env.NO_TAILSCALE = '1'
+
+    startProcess(serverPath, env)
+    console.log('[rcc] 正在启动服务...')
+
+    const ready = await waitForReady(port)
+    if (!ready) {
+      console.error('[rcc] 等待服务就绪超时（15s），请运行 "rcc logs" 查看日志')
+      process.exit(1)
+    }
+
+    const network = await fetchNetworkInfo(port)
+    const width = 42
+    console.log(`\n${'='.repeat(width)}`)
+    console.log('  Remote Claude Code')
+    console.log(`${'-'.repeat(width)}`)
+    console.log(`  Local:      ${network.local}`)
+    if (network.tailscale.isAvailable && network.tailscale.url) {
+      console.log(`  Tailscale:  ${network.tailscale.url}`)
+    }
+    if (network.tunnel.isRunning && network.tunnel.url) {
+      console.log(`  Tunnel:     ${network.tunnel.url}`)
+    }
+    console.log(`${'-'.repeat(width)}`)
+    console.log('  Open any URL above on your phone!')
+    console.log(`${'='.repeat(width)}\n`)
+  },
+})

package/cli/commands/status.ts

@@ -0,0 +1,41 @@
+import { defineCommand } from 'citty'
+import { readProcessInfo } from '../utils/process-manager'
+import { fetchNetworkInfo } from '../utils/server'
+
+function formatUptime(ms: number): string {
+  const s = Math.floor(ms / 1000)
+  const m = Math.floor(s / 60)
+  const h = Math.floor(m / 60)
+  const d = Math.floor(h / 24)
+  if (d > 0) return `${d}d ${h % 24}h`
+  if (h > 0) return `${h}h ${m % 60}m`
+  if (m > 0) return `${m}m ${s % 60}s`
+  return `${s}s`
+}
+
+export default defineCommand({
+  meta: { name: 'status', description: '查看 Remote Claude Code 服务状态' },
+  async run() {
+    const info = readProcessInfo()
+
+    if (!info) {
+      console.log('[rcc] 服务未在运行')
+      console.log('      运行 "rcc start" 启动服务')
+      return
+    }
+
+    console.log('[rcc] 服务运行中')
+    console.log(`  PID:     ${info.pid}`)
+    console.log(`  运行时长: ${formatUptime(Date.now() - info.startTime)}`)
+    console.log(`  日志:    ${info.logFile}`)
+
+    const network = await fetchNetworkInfo(info.port)
+    console.log(`\n  Local:      ${network.local}`)
+    if (network.tailscale.isAvailable && network.tailscale.url) {
+      console.log(`  Tailscale:  ${network.tailscale.url}`)
+    }
+    if (network.tunnel.isRunning && network.tunnel.url) {
+      console.log(`  Tunnel:     ${network.tunnel.url}`)
+    }
+  },
+})

package/cli/commands/stop.ts

@@ -0,0 +1,14 @@
+import { defineCommand } from 'citty'
+import { stopProcess } from '../utils/process-manager'
+
+export default defineCommand({
+  meta: { name: 'stop', description: '停止 Remote Claude Code 服务' },
+  async run() {
+    const stopped = stopProcess()
+    if (stopped) {
+      console.log('[rcc] 服务已停止')
+    } else {
+      console.log('[rcc] 服务未在运行')
+    }
+  },
+})

package/cli/constants.ts

@@ -0,0 +1 @@
+export const APP_NAME = 'open-remote-claude'

package/cli/index.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from 'citty'
+import start from './commands/start'
+import stop from './commands/stop'
+import status from './commands/status'
+import logs from './commands/logs'
+import setup from './commands/setup'
+
+const main = defineCommand({
+  meta: {
+    name: 'rcc',
+    version: '0.1.0',
+    description: 'Remote Claude Code CLI — 远程控制 Claude Code',
+  },
+  subcommands: { start, stop, status, logs, setup },
+})
+
+runMain(main)